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" \
  --form user_ref=user-123 \
  --form [email protected] \
  --form [email protected] \
  --form [email protected]

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

Campos del Formulario

Campo	Tipo	Requerido	Descripción
`user_ref`	texto	Sí	Su identificador de la persona que se está verificando
`front_image`	archivo	Sí	Frente del documento — la página con foto de un pasaporte, el frente de una tarjeta
`back_image`	archivo	No	Reverso del documento. Para licencias y documentos de identidad estatales de EE. UU., contiene el código de barras
`selfie_image`	archivo	No	Omítalo para ejecutar solo las verificaciones de documento — vea Verificación solo de documento
`data_check`	texto	No	`true` compara los datos extraídos contra `prefill`
`prefill`	texto	No	Una cadena JSON con el mismo esquema que el prefill de sesión

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

  --form 'prefill={"first_name":"Ana","last_name":"Silva","date_of_birth":"1988-03-04"}' \
  --form data_check=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 front_image solo es suficiente para ellos.

Verificación Solo de Documento

Omita selfie_image 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:

Canal	Comportamiento
Webhook	Con una `webhook_url` configurada, el resultado decidido se envía mediante `POST` como cualquier otro resultado — vea Notificaciones de resultados
Sondeo (polling)	`GET /v1/sessions/{session_id}` devuelve el `status` y el `result` en vivo, actualizados en el lugar, con `result.manual_review` indicando quién decidió y por qué

Use session_id 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

Estado	Causa	Cómo manejarlo
`401` / `403`	Token faltante o inválido, o un token sin el scope `verifications`	Vea Autenticación
`422`	`prefill` no es JSON válido o viola el esquema de prefill (incluido el formato del número de documento)	Corrija el payload — el `detail` indica el problema
`422`	`data_check=true` sin `prefill`	Proporcione un payload de prefill contra el cual comparar
`502`	El servicio de verificación no estaba disponible	Transitorio — reintente. Es una falla de infraestructura, no un rechazo. No lo trate como un resultado negativo para el cliente

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.document_type 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:

	Widget alojado	Server-to-server
Calidad de captura	Guiada, con encuadre en vivo y retroalimentación de reflejos	Bajo su control
Captura fallida	El cliente recibe orientación y reintenta	Devuelve un resultado; reintentar es su decisión
Entrega del resultado	Webhook o redirección firmada	El cuerpo de la respuesta, más cambios posteriores por webhook
Defensa contra ataques de presentación	Las mismas verificaciones	Las mismas verificaciones, pero sin contexto de captura en vivo del cual apoyarse
Evidencia de cumplimiento	Inyo retiene la captura guiada y el video opcional de la selfie	Solo las imágenes que usted envía

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