Referencia API

Veridia expone una API REST chica. Tres endpoints. JSON in, JSON out. Sin SOAP, sin GraphQL, sin XML.

Base URL

https://api.xxuxe.online

Todas las requests deben usar HTTPS. Las requests HTTP son rechazadas.

Resumen de endpoints

Metodo	Path	Proposito
POST	/v1/verify/init	Inicia una verificacion, obtene URLs de upload presigned
POST	/v1/verify/submit	Despues del upload, dispara el pipeline ML
GET	/v1/verify/:id	Consulta status de verificacion / obtene veredicto
GET	/health	Liveness check (no requiere auth)

El widget usa estos endpoints internamente. Vos los llamas directamente solo cuando construyas un flujo server-side o un cliente mobile custom.

Autenticacion

Cada endpoint (excepto /health) requiere un bearer token:

Authorization: Bearer qv_pub_FJJWXMA2RN2XPRDK6YJX4KTVD0XSQHW9

Existen dos tipos de keys:

Tipo	Prefijo	Donde usar
Publishable	qv_pub_*	Browser, widget, clientes publicos
Secret	qv_sec_*	Solo server-side — obtene veredictos, verifica webhooks

Detalles completos: Autenticacion.

Versionado

La API esta versionada en el path de URL: /v1/.... Cambios breaking obtienen un path de version nuevo (/v2/...). La version actual queda disponible al menos 12 meses despues que una sucesora se publica.

Adiciones no-breaking (nuevos campos opcionales, nuevos endpoints) suceden en /v1 sin aviso.

Formato de request

Todos los bodies POST son JSON:

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

{
  "userRef": "customer-12345",
  "country": "PY",
  "documentType": "dni"
}

Formato de response

Las responses JSON incluyen un requestId que deberias loguear. Cuando algo sale mal, asi es como soporte rastrea el problema:

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

Las responses de error usan un shape consistente:

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

El response header X-Request-Id lleva el mismo valor, para que puedas correlacionar incluso cuando el parsing JSON falla.

Expectativas de latencia

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

El endpoint /submit es el lento — corre OCR, despacha al backend ML, y espera respuesta inicial. El pipeline ML real termina async; haces polling a /v1/verify/:id para el veredicto.

Rate limits

Limites por defecto por tenant:

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

Necesitas limites mas altos? Contacta soporte — los podemos subir por-tenant.

Cuando llegas a un limite, la respuesta es 429 Too Many Requests con un header Retry-After.

CORS

La API permite requests cross-origin desde cualquier origen listado en los allowed origins de tu key en el dashboard. Las requests preflight (OPTIONS) son cacheadas por 10 minutos.

Errores

Todas las responses de error siguen el mismo shape. Mira Errores para el catalogo completo de codigos error que podes recibir.

Que sigue

• Autenticacion — keys, environments, seguridad
• POST /v1/verify/init — iniciar una verificacion
• POST /v1/verify/submit — enviar imagenes capturadas
• GET /v1/verify/:id — obtener el veredicto
• Errores — referencia de codigos de error
• Rate limits — limites y cuotas