Verificaciones y decisiones

Toda verificación — por widget o servidor a servidor — se resuelve en el mismo resultado normalizado. Esta página es la referencia para interpretarlo.

El payload de resultado

{
  "session_id": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "user_ref": "user-123",
  "status": "approved",
  "auto_status": "approved",
  "document": {
    "type": "Passport",
    "number": "A12345678",
    "personal_number": null,
    "issuing_state": "USA",
    "issuing_country": "USA",
    "issuing_country_name": "United States",
    "expiration_date": "2033-09-30",
    "date_of_issue": null
  },
  "person": {
    "first_name": "ALEX",
    "last_name": "MORGAN",
    "full_name": "ALEX MORGAN",
    "date_of_birth": "1988-03-04",
    "gender": "F",
    "nationality": "USA",
    "address": null,
    "city": null,
    "region": null,
    "postal_code": null
  },
  "checks": [
    { "name": "document_authentic",   "passed": true, "score": null, "detail": "no screen-recapture signals" },
    { "name": "document_readable",    "passed": true, "score": null, "detail": "all core fields extracted" },
    { "name": "mrz_valid",            "passed": true, "score": null, "detail": "all check digits valid" },
    { "name": "document_not_expired", "passed": true, "score": null, "detail": "expiration_date 2033-09-30" },
    { "name": "document_number_format", "passed": true, "score": null, "detail": "passport:USA — document number matches the USA passport format" },
    { "name": "screen_pattern",       "passed": true, "score": null, "detail": "screen/moiré score 0.42 vs threshold 0.8" },
    { "name": "ai_authenticity",      "passed": true, "score": 95.0, "detail": "genuine document — physical document, consistent printing" },
    { "name": "face_detected",        "passed": true, "score": null, "detail": "eyes_open=True sunglasses=False frontal=True" },
    { "name": "liveness",             "passed": true, "score": 93.2, "detail": "heuristic (selfie mode): face confidence + quality vs threshold 80.0" },
    { "name": "face_match",           "passed": true, "score": 98.7, "detail": "CompareFaces similarity vs threshold 90.0" }
  ],
  "prefill_mismatches": [],
  "prefill_comparison": [],
  "selfie_description": null,
  "provider": "inyo"
}

Campos de nivel superior

Campo	Descripción
`session_id`	El identificador de la verificación. Úselo con `GET /v1/sessions/{session_id}`
`user_ref`	Su identificador, devuelto exactamente como usted lo suministró
`status`	El estado final de la verificación — vea Estados
`auto_status`	Lo que el pipeline decidió antes de cualquier enrutamiento a revisión o decisión humana — vea Revisión Manual
`document`	Datos extraídos del documento
`person`	Datos de identidad extraídos
`checks`	Las verificaciones individuales que produjeron la decisión — vea Cómo leer `checks[]`
`prefill_mismatches`	Nombres de los campos de prefill que no coincidieron con el documento. Vacío a menos que haya enviado prefill
`prefill_comparison`	Detalle de comparación campo por campo — vea Comparación de prefill
`selfie_description`	Descripción estructurada de la apariencia, o `null` a menos que esté habilitada para su tenant
`provider`	`inyo` para una verificación real, `inyo-mock` para una simulada — vea Sandbox
`manual_review`	Presente solo después de una decisión humana. Vea Revisión Manual
`notified_at`	Presente solo en las notificaciones entregadas, no en el resultado almacenado. Úselo para ordenar entregas concurrentes — vea Recepción de Resultados

`document`

Campo	Descripción
`type`	`Passport`, `Driver's License` o `Identity Card`
`number`	Número de documento tal como se leyó del documento
`personal_number`	Identificador nacional secundario cuando el documento lo incluye
`issuing_state`	Autoridad emisora tal como aparece impresa — un estado de EE. UU. para licencias, un código de país en pasaportes
`issuing_country`	País resuelto en formato ISO 3166-1 alpha-3
`issuing_country_name`	Nombre para mostrar de `issuing_country` (por ejemplo `United States`). Recurre al código mismo cuando no es un país reconocido, y es `null` solo cuando `issuing_country` es `null`
`expiration_date`, `date_of_issue`	`YYYY-MM-DD`, o `null` cuando el documento no lo incluye

`person`

first_name, last_name, full_name, date_of_birth, gender, nationality, address, city, region, postal_code.

Cualquier campo que el documento no incluya — o que no pudo leerse — es null. Los campos de dirección suelen ser null en pasaportes y se completan a partir de licencias de conducir. Los nombres llegan tal como están impresos en el documento, lo que en pasaportes significa en mayúsculas.

Estados

`status`	Significado	Qué hacer
`pending`	Creada, aún no completada	Espere. Todavía no existe una decisión
`approved`	Todas las verificaciones pasaron	Continúe con el onboarding
`declined`	Al menos una verificación dura falló	No continúe. El `detail` de la verificación fallida explica el motivo
`in_review`	Un humano decide — no es final	Trátela como pendiente. Vea Revisión Manual
`expired`	El cliente nunca la completó dentro de la vigencia del enlace	Cree una nueva sesión si todavía necesita la verificación

Cómo leer `checks[]`

Cada verificación tiene exactamente cuatro campos: name, passed, score, detail.

Regla	Detalle
`passed` es autoritativo	Es el resultado de la verificación. No lo re-derive a partir de `score` — `score` y `detail` explican el resultado, no lo definen
`score` va de `0-100`, más alto es mejor	Expresa la confianza de que la verificación se cumple. Es `null` cuando la verificación es un simple pasa/falla sin un escalar comparable, que es la mayoría de los casos — solo `liveness`, `face_match` y `ai_authenticity` lo incluyen
`detail` cita el umbral	Cuando una verificación tiene un umbral, `detail` lo menciona. Los umbrales de `liveness` y `face_match` son por tenant, así que léalos aquí en lugar de asumir los valores predeterminados de la plataforma
El conjunto varía	Las verificaciones aparecen solo cuando aplican: `mrz_valid` necesita una zona de lectura mecánica, las verificaciones faciales necesitan una selfie, y varias se habilitan por tenant. Itere el arreglo; no lo indexe posicionalmente ni asuma una longitud fija

Dos verificaciones requieren manejo explícito:

screen_pattern lleva score: null deliberadamente. Su medición subyacente opera en una escala invertida de 0-1 donde un valor más alto significa más parecido a una pantalla, lo que se leería como un cuasi-fallo junto a las biometrías de 0-100. Publicarlo como score confundiría más de lo que informaría, así que el valor bruto y su umbral están en detail. Lea passed.

ai_authenticity lleva un puntaje sobre el que no debe tomar decisiones. El puntaje es la certeza del modelo en su propio veredicto, orientado de modo que más alto significa "más probablemente genuino". Es solo diagnóstico — Inyo lo excluye deliberadamente del enrutamiento a revisión. Eso no hace que la verificación sea inerte: es una verificación dura, y passed: false rechaza la verificación de inmediato sin importar lo que diga el puntaje.

Las verificaciones

Las verificaciones duras hacen fallar la verificación — con que una sola falle el resultado es declined.

Verificación	Falla cuando	Presente
`document_authentic`	Un teléfono, monitor o pantalla es visible en el encuadre — el documento está siendo fotografiado desde una pantalla	Siempre
`screen_pattern`	Patrones de pantalla/moiré indican una recaptura incluso sin un dispositivo en el encuadre	Cuando al menos un lado capturado pudo analizarse
`ai_authenticity`	La revisión del documento identifica una recaptura, impresión, fotocopia o falsificación	Cuando está habilitada para su tenant (activada por defecto)
`document_readable`	Los campos de identidad principales (número, nombre, fecha de nacimiento) no pudieron extraerse en su totalidad	Siempre
`document_not_expired`	La fecha de vencimiento está en el pasado	Cuando el documento incluye una fecha de vencimiento
`jurisdiction_accepted`	El país emisor del documento está fuera de las jurisdicciones que usted acepta para ese tipo de documento	Cuando usted ha configurado jurisdicciones aceptadas
`face_detected`	No hay exactamente un rostro utilizable — ojos cerrados, gafas de sol o una cabeza muy girada	Cuando se capturó una selfie
`liveness`	La confianza de prueba de vida está por debajo de su umbral	Cuando se capturó una selfie
`face_match`	La similitud entre el retrato del documento y la selfie está por debajo de su umbral	Cuando se capturó una selfie

Las verificaciones blandas envían la verificación a in_review en lugar de rechazarla.

Verificación	Falla cuando	Presente
`mrz_valid`	Un dígito de control del MRZ no valida — un error de OCR o manipulación	Cuando el documento tiene una zona de lectura mecánica
`document_number_format`	El número no coincide con el formato conocido para su jurisdicción. Consultiva — las tablas de formato están publicadas pero son imperfectas, por lo que esto nunca rechaza automáticamente	Cuando existe una regla para esa jurisdicción
`dmv_record_match`	Los datos extraídos de una licencia de EE. UU. no coinciden con el registro del DMV emisor	Cuando la verificación con el DMV está habilitada para su tenant (desactivada por defecto)
`data_match`	Los datos que usted envió no coinciden con el documento	Cuando usted establece `data_check: true`

Una verificación adicional aparece solo en el flujo del widget: capture_attempts falla cuando el cliente agotó el límite de reintentos, lo que rechaza la sesión — vea Entrega del Widget.

Comparación de prefill

Cuando usted envía prefill, el resultado reporta cómo coincidió cada campo comparable. prefill_mismatches es la lista corta de nombres de campos que no coincidieron; prefill_comparison incluye el detalle:

"prefill_comparison": [
  { "field": "last_name",     "sent": "Silva",      "received": "SILVA SANTOS", "match": true,  "method": "subset",     "score": 0.95, "threshold": 0.85 },
  { "field": "date_of_birth", "sent": "1988-03-04", "received": "1988-03-04",   "match": true,  "method": "exact",      "score": null, "threshold": null },
  { "field": "issuing_state", "sent": "Florida",    "received": "FL",           "match": true,  "method": "normalized", "score": null, "threshold": null }
]

Campo	Descripción
`field`	Uno de `first_name`, `last_name`, `date_of_birth`, `document_type`, `document_number`, `nationality`, `issuing_state`
`sent` / `received`	Su valor, y el valor leído del documento
`match`	Si se consideran iguales
`method`	Para nombres: `exact`, `subset` (un apellido compuesto que contiene el suyo, con puntaje 0.95), `fuzzy` (puntuación de similitud) o `empty`. Para estados y tipos de documento: `normalized`. En los demás casos `exact`
`score` / `threshold`	Similitud de nombres y el umbral de aceptación, `null` para campos que no son nombres

Los campos ausentes en cualquiera de los dos lados no se comparan, así que nunca aparecen. Los nombres usan coincidencia difusa — acentos eliminados, apellidos compuestos aceptados como coincidencias de subconjunto, errores cercanos de OCR tolerados hasta el umbral — de modo que la variación ortográfica ordinaria no crea falsos desacuerdos. Los estados y tipos de documento se normalizan primero, y por eso Florida coincide con FL.

Un desacuerdo solo afecta la decisión cuando usted establece data_check: true, lo que agrega la verificación blanda data_match. Sin eso, la comparación es informativa.

Descripción de la selfie

null a menos que la descripción de apariencia esté habilitada para su tenant. Cuando está presente, incluye atributos observables de la selfie para una comparación posterior de re-verificación:

"selfie_description": {
  "estimated_age_low": 30,
  "estimated_age_high": 40,
  "skin_tone": "light",
  "eye_color": "brown",
  "hair_color": "dark brown",
  "hair_style": "shoulder length, straight",
  "facial_hair": "none",
  "eyewear": "none",
  "headwear": "none",
  "distinguishing_features": ["small scar above left eyebrow"],
  "notes": null
}

Cualquier atributo que no pueda observarse es null. Estos son datos personales sensibles — vea la nota de cumplimiento en Configuración del Tenant antes de habilitarla.

Cambio de convención de puntajes

Los resultados creados antes de que se implementara la convención de puntajes actual difieren en dos aspectos: screen_pattern.score llevaba una probabilidad bruta de moiré de 0-1 (donde más alto significaba peor), y ai_authenticity.score usaba una escala indefinida. Las filas posteriores al cambio son identificables sin una referencia externa — screen_pattern.score es null, y ninguna verificación lleva campos más allá de los cuatro documentados arriba. Si almacena resultados históricos, base su lectura en eso.

Próximos pasos

Revisión Manual — in_review, auto_status y manual_review
Configuración del Tenant — los umbrales contra los que se comparan estas verificaciones
Recepción de Resultados — cómo le llega este payload