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

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "userRef": "user-123",
  "status": "approved",
  "autoStatus": "approved",
  "document": {
    "type": "passport",
    "number": "A12345678",
    "personalNumber": null,
    "issuingState": "USA",
    "issuingCountry": "USA",
    "issuingCountryName": "United States",
    "expirationDate": "2033-09-30",
    "dateOfIssue": null
  },
  "person": {
    "firstName": "ALEX",
    "lastName": "MORGAN",
    "fullName": "ALEX MORGAN",
    "dateOfBirth": "1988-03-04",
    "gender": "F",
    "nationality": "USA",
    "address": null,
    "city": null,
    "region": null,
    "postalCode": null
  },
  "checks": [
    { "name": "document_scene_clear",  "status": "passed", "group": "document", "detail": "no screen-recapture signals" },
    { "name": "document_readable",     "status": "passed", "group": "document", "detail": "all core fields extracted" },
    { "name": "document_number_valid", "status": "passed", "group": "document", "detail": "passport:USA — document number matches the USA passport format" },
    { "name": "document_mrz_valid",    "status": "passed", "group": "document", "detail": "all check digits valid" },
    { "name": "document_not_expired",  "status": "passed", "group": "document", "detail": "expirationDate 2033-09-30" },
    { "name": "document_authentic",    "status": "passed", "group": "document", "detail": "genuine — laminate sheen, crisp typography, natural depth" },
    { "name": "face_detected",         "status": "passed", "group": "selfie",   "detail": "eyes_open=True sunglasses=False frontal=True" },
    { "name": "liveness",              "status": "passed", "group": "selfie",   "detail": "heuristic (selfie mode): face confidence + quality vs threshold 80.0" },
    { "name": "face_match",            "status": "passed", "group": "selfie",   "detail": "CompareFaces similarity vs threshold 90.0" }
  ],
  "prefillMismatches": [],
  "prefillComparison": [],
  "provider": "inyo"
}

Campos de nivel superior

document

person

firstName, lastName, fullName, dateOfBirth, gender, nationality, address, city, region, postalCode.

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

Cómo leer checks[]

Cada verificación tiene exactamente cuatro campos: name, status, group, detail.

Hoy sanctions_clear es la única verificación que publica indeterminate — una coincidencia de nombre de sanciones sin confirmar, vea Cribado de sanciones — pero maneje el estado de forma genérica en lugar de tratar el nombre como caso especial: cualquier verificación indeterminate significa que un humano decide.

document_authentic fusiona todos los lados revisados en una única fila. Es una verificación dura — una fila failed rechaza la verificación de inmediato. En una tarjeta, el frente y un reverso enviado se revisan ambos y se fusionan en esta única fila: cualquier lado que falle la hace fallar, y el detail lleva el veredicto de cada lado como clasificación — lo que observó el examinador, con el lado como prefijo cuando se revisó más de un lado ("front: genuine — …; back: photocopy — …") y sin prefijo cuando solo se revisó uno. La revisión falla abierta por lado — un lado que no pudo juzgarse simplemente queda fuera, y si ningún lado produjo un veredicto la fila está ausente.

age_match solo se publica cuando la descripción de apariencia está habilitada para su tenant y el documento arrojó una fecha de nacimiento. Pasa cuando la edad derivada del documento en el momento de la captura cae dentro del rango de edad estimado por la descripción de la selfie, ampliado por una tolerancia que Inyo configura para su tenant (5 años por defecto, indicada en detail como ±5), y falla en caso contrario. La tolerancia absorbe la imprecisión de una estimación de edad; con 0, la comparación es exactamente contra el rango estimado. Como una estimación de edad es un indicio, no una prueba, un fallo nunca rechaza — es una verificación blanda que envía la verificación a in_review. Está ausente siempre que la descripción de apariencia esté desactivada, el documento no incluya fecha de nacimiento, o la propia descripción falle abierta (una interrupción nunca bloquea la verificación) — nada de eso es, en sí mismo, un indicio.

Las verificaciones

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

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

Una verificación adicional aparece solo en el flujo del widget: capture_attempts (grupo policy) 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. prefillMismatches es la lista corta de nombres de campos que no coincidieron; prefillComparison incluye el detalle:

"prefillComparison": [
  { "field": "lastName",     "sent": "Silva",      "received": "SILVA SANTOS", "match": true,  "method": "subset",     "score": 0.95, "threshold": 0.85 },
  { "field": "dateOfBirth", "sent": "1988-03-04", "received": "1988-03-04",   "match": true,  "method": "exact",      "score": null, "threshold": null },
  { "field": "issuingState", "sent": "Florida",    "received": "FL",           "match": true,  "method": "normalized", "score": null, "threshold": null }
]

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 dataCheck: true, lo que agrega la verificación blanda document_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:

"selfieDescription": {
  "estimatedAgeLow": 30,
  "estimatedAgeHigh": 40,
  "skinTone": "light",
  "eyeColor": "brown",
  "hairColor": "dark brown",
  "hairStyle": "shoulder length, straight",
  "facialHair": "none",
  "eyewear": "none",
  "headwear": "none",
  "distinguishingFeatures": ["small scar above left eyebrow"],
  "notes": null
}

Cualquier atributo que no pueda observarse es null.

Las descripciones de apariencia son datos personales sensibles. Conllevan exposición bajo el RGPD y leyes de privacidad biométrica (por ejemplo BIPA), y la selfie es procesada por un servicio de visión externo. Confirme que tiene una base legal, un acuerdo de procesamiento de datos vigente y una justificación de retención documentada antes de pedirnos habilitar esto.

Cribado de sanciones

Desactivado por defecto, y habilitado por tenant por Inyo cuando se solicita. Cuando está activo, el nombre extraído del documento se criba contra la lista OFAC de Nacionales Especialmente Designados (SDN).

Un nombre que coincide no es una persona

Dos tokens de nombre comunes aparecen en muchos nombres listados, así que una coincidencia de nombre por sí sola nunca rechaza. La confirmación es por fecha de nacimiento, y el resultado es el status de la única verificación sanctions_clear:

Nada ambiguo se resuelve hacia la aprobación: una coincidencia no confirmable pasa a un humano, no adelante. Base sus decisiones en status. El umbral de aceptación se configura por tenant — consulte a su contacto en Inyo cuál es el suyo.

El bloque screening

Presente solo cuando se entregó una coincidencia — es decir, junto a un sanctions_clear que está failed (coincidencia confirmada) o indeterminate (sin confirmar). Está ausente cuando el cribado sale limpio, por lo que su presencia significa "hay algo que adjudicar", no "el cribado se ejecutó".

"screening": {
  "matches": [
    {
      "name": "SAMPLE, Ali Hassan",
      "sourceList": "us_ofac",
      "programs": ["SDGT"],
      "entityId": "12345",
      "score": 91.5,
      "dobAgrees": true
    }
  ]
}

Se entregan como máximo cinco coincidencias — suficientes para distinguir una coincidencia única plausible de un grupo obvio de colisiones. Solo aparecen candidatos en su umbral o por encima.

Una particularidad que conviene saber al adjudicar: OFAC publica fechas imprecisas colapsadas al 1 de enero, así que un candidato listado en ese día se compara solo por año. Para quien nació genuinamente el 1 de enero eso afloja la correspondencia, en dirección al rechazo.

Su cliente nunca sabe que una coincidencia de sanciones fue lo que lo rechazó. La respuesta de rechazo es idéntica byte a byte a cualquier otro fallo sin reintento.

Si el cribado no está disponible

El cribado falla abierto: una caída del proveedor omite la verificación en vez de bloquear o rechazar. Nada en el resultado entregado distingue una sesión que se entregó sin cribar de una que se cribó y salió limpia — en ese caso simplemente no existe ninguna fila sanctions_clear. Si necesita evidencia positiva de que toda verificación fue cribada, compruebe la presencia de esa verificación, no la ausencia de coincidencia.

Próximos pasos

• Revisión Manual — in_review, autoStatus y manualReview
• Recepción de Resultados — cómo le llega este payload