Verificación Server-to-Server

Cuando usted ya cuenta con una interfaz de captura — o está verificando imágenes que fueron recopiladas con anterioridad — envíelas directamente y obtenga el resultado en la respuesta. Sin sesión, sin widget, sin enlace para el cliente.

Crear una Verificación

Endpoint: POST /v1/verifications
Autenticación: token Bearer con el scope verifications
Content-Type: multipart/form-data

curl --request POST \
  --url https://{FQDN}/v1/verifications \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Idempotency-Key: $(uuidgen)" \
  --form userRef=user-123 \
  --form [email protected] \
  --form [email protected] \
  --form [email protected]

Devuelve 201 con el mismo resultado normalizado que produce el widget.

Idempotency-Key es obligatorio

Toda llamada debe llevar un encabezado Idempotency-Key. Una solicitud sin él se rechaza con 422.

Este endpoint ejecuta la extracción del documento, la revisión de autenticidad, el cribado de sanciones y las verificaciones faciales de forma sincrónica, por lo que una sola llamada puede tardar varios segundos. Suficiente para que un timeout del cliente sea un evento común, no exótico — y un reintento ciego ejecutaría todo eso una segunda vez, y se le cobraría.

Use un valor que su propio código pueda reproducir para la misma verificación lógica: un UUID que usted genere y almacene, o un identificador de su sistema. No lo derive de algo que se repite, como solo el userRef — dos verificaciones legítimas de la misma persona colisionarían, y la segunda devolvería el resultado de la primera.

El 409 importa más de lo que parece. Si su solicitud sufrió un timeout, nunca recibió un sessionId, así que no tiene forma de preguntar por el trabajo ya en curso. La respuesta de conflicto se lo devuelve:

{
  "detail": {
    "code": "IDEMPOTENCY_KEY_IN_FLIGHT",
    "message": "A request with this Idempotency-Key is still being processed. Poll GET /v1/sessions/{sessionId} for the outcome.",
    "sessionId": "81e04c30-2620-42f1-a3e0-68aef1f84043"
  }
}

Por lo tanto el comportamiento correcto ante un timeout es: repita la misma llamada con la misma clave. Recibirá el resultado o un 409 que le dice dónde mirar. Nunca reintente con una clave nueva — eso inicia una segunda verificación cobrada de la misma persona.

POST /v1/sessions no acepta Idempotency-Key. Su respuesta contiene un enlace de widget de un solo uso que no puede reemitirse, así que un reintento allí crea una sesión nueva; un duplicado cuesta un enlace sin usar, no una verificación repetida.

Campos del Formulario

Tenga en cuenta que prefill aquí es una cadena JSON dentro de un campo multipart, no un objeto anidado:

  --form 'prefill={"firstName":"Ana","lastName":"Silva","dateOfBirth":"1988-03-04"}' \
  --form dataCheck=true

Envíe el Reverso de la Tarjeta

Para las licencias de conducir y documentos de identidad estatales de EE. UU., el reverso contiene un código de barras PDF417 que codifica los datos del titular. Inyo lo decodifica al recibirlo, y dado que el código de barras es autoverificable — la simbología incluye su propia corrección de errores — prevalece sobre el OCR de la zona visual para los campos que contiene. La decodificación es independiente de la rotación, por lo que un reverso boca abajo se lee igual.

Un reverso faltante, ilegible o sin código de barras es una no-operación silenciosa: los valores de OCR se mantienen y ninguna verificación cambia. No hay desventaja en enviarlo, y hay una ganancia de precisión medible cuando se decodifica. Los pasaportes llevan en cambio una zona de lectura mecánica en la página con foto, por lo que frontImage solo es suficiente para ellos.

Verificación Solo de Documento

Omita selfieImage para verificar el documento sin biometría. Las verificaciones de documento se ejecutan — legibilidad, formato, vencimiento, autenticidad, jurisdicción — y no aparece ninguna verificación facial en checks[].

Una consecuencia que debe planificar: una verificación solo de documento no tiene puntaje biométrico. Si tiene configurado un umbral de revisión, no hay nada contra qué compararlo, y una verificación no medida se trata como no medida, no confiable — por lo que se enruta a in_review en lugar de aprobarse automáticamente. Envíe una selfie, o deje el umbral de revisión sin configurar, si necesita que las verificaciones solo de documento se decidan de forma sincrónica.

in_review No Es una Respuesta Final

POST /v1/verifications devuelve el resultado de forma sincrónica, pero una respuesta 201 no garantiza una decisión terminal. status puede ser in_review, lo que significa que un analista aún debe decidir.

Esto ocurre cuando usted ha configurado un umbral de revisión, o cuando los rechazos retenidos están habilitados y las verificaciones rechazaron el documento. Sin ninguno de los dos configurados, cada verificación regresa decidida.

Cuando esto ocurre:

Use sessionId del cuerpo de la respuesta como identificador para ambos. No se envía ningún webhook para la respuesta sincrónica original — el 201 ya la entregó. Vea Revisión Manual para el panorama completo.

Respuestas de Error

¿Widget o Server-to-Server?

Ambos puntos de entrada comparten el mismo pipeline y la misma estructura de resultado, y sus umbrales, enrutamiento de revisión, jurisdicciones aceptadas y opciones de enriquecimiento se aplican de forma idéntica. Dos configuraciones son por naturaleza a nivel de sesión y no tienen efecto aquí: los tipos de documento permitidos y el bloqueo de prefill.documentType restringen lo que el widget ofrece a un cliente, por lo que en este endpoint el tipo de documento es simplemente el que resulte de las imágenes.

Las diferencias que importan:

La diferencia de reintento se refiere a orientar a un cliente en vivo — no cambia lo que significa su configuración ni cómo se llega a la decisión.

Próximos Pasos

• Verificaciones y Decisiones — el payload de resultado completo
• Revisión Manual — manejo de in_review
• Recepción de Resultados — notificaciones por webhook para cambios posteriores