Referencia API

Veridia expoe uma API REST pequena. Tres endpoints. JSON in, JSON out. Sem SOAP, sem GraphQL, sem XML.

Base URL

https://api.xxuxe.online

Todas as requests devem usar HTTPS. Requests HTTP sao rejeitadas.

Resumo de endpoints

Metodo	Path	Proposito
POST	/v1/verify/init	Inicia uma verificacao, obtem URLs de upload presigned
POST	/v1/verify/submit	Apos o upload, dispara o pipeline ML
GET	/v1/verify/:id	Consulta status de verificacao / obtem veredicto
GET	/health	Liveness check (nao requer auth)

O widget usa estes endpoints internamente. Voce os chama diretamente apenas quando construir um fluxo server-side ou um cliente mobile custom.

Autenticacao

Cada endpoint (exceto /health) requer um bearer token:

Authorization: Bearer qv_pub_FJJWXMA2RN2XPRDK6YJX4KTVD0XSQHW9

Existem dois tipos de keys:

Tipo	Prefixo	Onde usar
Publishable	qv_pub_*	Browser, widget, clientes publicos
Secret	qv_sec_*	Apenas server-side — obtem veredictos, verifica webhooks

Detalhes completos: Autenticacao.

Versionamento

A API e versionada no path de URL: /v1/.... Mudancas breaking obtem um path de versao novo (/v2/...). A versao atual fica disponivel ao menos 12 meses apos uma sucessora ser publicada.

Adicoes nao-breaking (novos campos opcionais, novos endpoints) acontecem em /v1 sem aviso.

Formato de request

Todos os bodies POST sao JSON:

POST /v1/verify/init HTTP/1.1
Host: api.xxuxe.online
Authorization: Bearer qv_pub_...
Content-Type: application/json

{
  "userRef": "customer-12345",
  "country": "BR",
  "documentType": "national_id"
}

Formato de response

As responses JSON incluem um requestId que voce deve logar. Quando algo da errado, e assim que o suporte rastreia o problema:

{
  "verificationId": "vf_AG07CDWRRFQV4T05ZXG2",
  "uploads": { ... },
  "expiresAt": 1714604000
}

As responses de erro usam um shape consistente:

{
  "error": "invalid_body",
  "message": "Request body failed validation",
  "requestId": "9f511d92ac11236d-SJC",
  "detail": {
    "fieldErrors": {
      "country": ["expected 2 characters"]
    }
  }
}

O response header X-Request-Id carrega o mesmo valor, para que voce possa correlacionar mesmo quando o parsing JSON falha.

Expectativas de latencia

Operacao	Tipico	P99
/v1/verify/init	<400ms	<1.2s
/v1/verify/submit	<2.7s	<5s
/v1/verify/:id (durante processamento)	<150ms	<400ms

O endpoint /submit e o lento — executa OCR, despacha ao backend ML, e espera resposta inicial. O pipeline ML real termina async; faca polling em /v1/verify/:id para o veredicto.

Rate limits

Limites padrao por tenant:

Endpoint	Requests / minuto
/v1/verify/init	60
/v1/verify/submit	30
/v1/verify/:id	600

Precisa de limites mais altos? Contate o suporte — podemos elevar por-tenant.

Quando voce atinge um limite, a resposta e 429 Too Many Requests com um header Retry-After.

CORS

A API permite requests cross-origin de qualquer origem listada nos allowed origins da sua key no dashboard. Requests preflight (OPTIONS) sao cacheadas por 10 minutos.

Erros

Todas as responses de erro seguem o mesmo shape. Veja Erros para o catalogo completo de codigos error que voce pode receber.

Proximos passos

• Autenticacao — keys, environments, seguranca
• POST /v1/verify/init — iniciar uma verificacao
• POST /v1/verify/submit — enviar imagens capturadas
• GET /v1/verify/:id — obter o veredicto
• Erros — referencia de codigos de erro
• Rate limits — limites e quotas