API Backend

Endpoints REST para criação de sessões e consulta de resultados.

Todas as chamadas à API devem ser feitas a partir do backend do integrador — a API Key nunca deve ser exposta no frontend.

Base URL

api.provvi.com.br

Autenticação

A API usa autenticação via header x-api-key. A chave é gerada no Admin Console na seção “API Keys” do cliente.

x-api-key: pvv_api_SuaChaveAqui

Cada cliente recebe sua própria API Key (formato pvv_api_*). A chave é exibida uma única vez ao ser criada — armazene-a com segurança no backend.

A API Key é diferente da License Key do SDK. Veja Licenciamento para entender a diferença.

---

Endpoints

POST /web/sessions

Cria uma nova sessão de captura. Retorna um token com validade de 30 minutos.

Headers:

Header	Valor
Content-Type	application/json
x-api-key	Sua API Key

Request Body:

Campo	Tipo	Obrigatório	Descrição
reference_id	string	Sim	ID do recurso no sistema do integrador (anúncio, veículo, apólice)
redirect_uri	string	Sim	URL de retorno após captura concluída
webhook_url	string	Sim	URL que receberá POST ao concluir a captura
profile	string	Sim	Perfil de captura — valores definidos no contrato (ex: vehicle_inspection, demo)

Exemplo:

curl -X POST https://api.provvi.com.br/web/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -d '{
    "reference_id": "VIN-9BWZZZ377VT004251",
    "redirect_uri": "https://seusite.com/captura/retorno",
    "webhook_url": "https://seusite.com/api/provvi/webhook",
    "profile": "vehicle_inspection"
  }'

Response (201):

{
  "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": "2026-04-13T12:30:00Z"
}

Erros:

HTTP	Causa	Body
400	Payload inválido ou campo ausente	{ "error": "Payload inválido: ..." }
400	Profile não reconhecido	{ "error": "profile inválido — ..." }
401	API Key ausente ou inválida	{ "error": "API key inválida ou ausente" }

---

GET /web/session-results/:token

Consulta os resultados completos de uma sessão após a captura. Use este endpoint no seu backend para obter as URLs das fotos assinadas.

Parâmetros de URL:

Parâmetro	Descrição
token	Token retornado na criação da sessão

Response (200):

{
  "reference_id": "VIN-9BWZZZ377VT004251",
  "profile": "vehicle_inspection",
  "status": "captured",
  "total_photos": 3,
  "captured_count": 3,
  "created_at": "2026-04-13T12:00:00Z",
  "photos": [
    {
      "order": 1,
      "label": "Frente do veículo",
      "status": "captured",
      "session_id": "sess_abc123",
      "gps_lat": -23.5505,
      "gps_lon": -46.6333,
      "gps_accuracy": 12.5,
      "captured_at_ms": 1681394400000,
      "authenticated_jpeg_url": "https://s3.amazonaws.com/..."
    }
  ]
}

Campos de status da sessão:

Status	Descrição
pending	Nenhuma foto capturada ainda
partial	Algumas fotos capturadas
captured	Todas as fotos capturadas

Erros:

HTTP	Causa	Body
400	Token ausente	{ "error": "token ausente no path" }
404	Token não encontrado	{ "error": "Sessão não encontrada" }

Nota: As URLs presigned do S3 têm validade de 7 dias. Armazene o conteúdo antes da expiração se precisar de acesso permanente.

---

Webhook

Quando todas as fotos de uma sessão são capturadas, o backend Provvi envia um POST para o webhook_url configurado na criação da sessão.

Payload:

{
  "session_id": "sess_abc123",
  "reference_id": "VIN-9BWZZZ377VT004251",
  "status": "signed",
  "authenticated_jpeg_url": "https://s3.amazonaws.com/...",
  "processed_at": "2026-04-13T12:05:30Z",
  "icp_brasil": true,
  "recapture_risk": "NONE"
}

Campos do webhook:

Campo	Tipo	Descrição
session_id	string	ID único da captura
reference_id	string	ID do recurso (passado na criação)
status	string	"signed"
authenticated_jpeg_url	string	URL do JPEG com manifesto C2PA + ICP-Brasil embutidos (autoverificável)
processed_at	string	Timestamp ISO 8601 do processamento
icp_brasil	boolean	Se foi assinado com certificado ICP-Brasil
recapture_risk	string	"NONE", "UNKNOWN" ou "HIGH"

Tratamento:

• O webhook é enviado de forma assíncrona (fire-and-forget)
• Não há retry automático em caso de falha
• Seu endpoint deve responder com status 2xx em até 30 segundos
• Em caso de falha no webhook, use GET /web/session-results/:token como fallback

---

Fluxo completo de integração

1. Seu backend ──→ POST /web/sessions (com x-api-key)
   ← token + expires_at

2. Seu frontend ──→ Redireciona usuário para captura (com token)
   (SDK ou Hosted Flow fazem o resto)

3. Provvi ──→ POST webhook_url (quando captura conclui)
   Seu backend recebe session_id + URLs assinadas

4. Seu backend ──→ GET /web/session-results/:token
   ← Fotos com URLs, GPS, timestamps

Todas as timestamps são RFC 3339. Coordenadas são WGS84 (latitude/longitude).