Checagens e Decisões

Toda verificação — via widget ou servidor-a-servidor — resolve para o mesmo resultado normalizado. Esta página é a referência para interpretá-lo.

O 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 Nível Superior

document

person

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

Qualquer campo que o documento não traga — ou que não pôde ser lido — é null. Campos de endereço são comumente null em passaportes e preenchidos a partir de carteiras de motorista. Os nomes chegam como impressos no documento, o que em passaportes significa letras maiúsculas.

Status

Lendo checks[]

Toda checagem tem exatamente quatro campos: name, status, group, detail.

Hoje sanctions_clear é a única checagem que publica indeterminate — uma coincidência de nome de sanções não confirmada, veja Triagem de Sanções — mas trate o status de forma genérica em vez de tratar o nome como caso especial: qualquer checagem indeterminate significa que um humano decide.

document_authentic mescla todos os lados analisados em uma única linha. É uma checagem hard — uma linha failed recusa a verificação de imediato. Em uma carteira, a frente e um verso enviado são ambos analisados e mesclados nesta única linha: qualquer lado que falhe a reprova, e o detail traz o veredito de cada lado como classificação — o que o examinador observou, prefixado pelo lado quando mais de um lado foi analisado ("front: genuine — …; back: photocopy — …") e sem prefixo quando apenas um foi. A análise falha aberta por lado — um lado que não pôde ser julgado simplesmente sai do cálculo, e se nenhum lado produziu veredito a linha está ausente.

age_match só é publicada quando a descrição de aparência está habilitada para o seu tenant e o documento revelou uma data de nascimento. Ela passa quando a idade derivada do documento no momento da captura cai dentro da faixa de idade estimada pela descrição da selfie, alargada por uma tolerância que a Inyo configura para o seu tenant (5 anos por padrão, indicada no detail como ±5), e falha caso contrário. A tolerância absorve a imprecisão de uma estimativa de idade; com 0, a comparação é exatamente contra a faixa estimada. Como uma estimativa de idade é um indício, não uma prova, uma falha nunca recusa — é uma checagem soft que encaminha para in_review. Está ausente sempre que a descrição de aparência está desligada, o documento não trouxe data de nascimento, ou a própria descrição falhou aberta (uma indisponibilidade nunca bloqueia a verificação) — nada disso é, por si só, um indício.

As Checagens

Checagens hard reprovam a verificação — a falha de qualquer uma delas resulta em declined.

Checagens soft encaminham a verificação para in_review em vez de recusá-la.

Uma checagem adicional aparece apenas no fluxo do widget: capture_attempts (grupo policy) falha quando o cliente esgotou o limite de tentativas, o que recusa a sessão — veja Entrega via Widget.

Comparação de Prefill

Quando você envia prefill, o resultado relata como cada campo comparável se alinhou. prefillMismatches é a lista curta de nomes de campos que divergiram; prefillComparison traz o detalhe:

"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 }
]

Campos ausentes em qualquer um dos lados não são comparados, então nunca aparecem. Nomes usam correspondência fuzzy — acentos removidos, sobrenomes compostos aceitos como correspondências de subconjunto, erros próximos de OCR tolerados até o limiar — de modo que variações comuns de grafia não criam falsas divergências. Estados e tipos de documento são normalizados primeiro, e é por isso que Florida corresponde a FL.

Uma divergência só afeta a decisão quando você define dataCheck: true, o que adiciona a checagem soft document_data_match. Sem isso, a comparação é apenas informativa.

Descrição da Selfie

null a menos que a descrição de aparência esteja habilitada para o seu tenant. Quando presente, traz atributos observáveis da selfie para comparação em reverificações futuras:

"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
}

Qualquer atributo que não possa ser observado é null.

Descrições de aparência são dados pessoais sensíveis. Elas carregam exposição a GDPR e a leis de privacidade biométrica (por exemplo, BIPA), e a selfie é processada por um serviço de visão externo. Confirme que você tem base legal, um acordo de processamento de dados em vigor e uma justificativa de retenção documentada antes de nos pedir para ativar isso.

Triagem de Sanções

Desligada por padrão, e habilitada por tenant pela Inyo quando solicitado. Quando ativa, o nome extraído do documento é triado contra a lista OFAC de Nacionais Especialmente Designados (SDN).

Um nome que coincide não é uma pessoa

Dois tokens de nome comuns aparecem em muitos nomes listados, então uma coincidência de nome por si só nunca recusa. A confirmação é pela data de nascimento, e o resultado é o status da única checagem sanctions_clear:

Nada ambíguo é resolvido em direção à aprovação: uma coincidência não confirmável vai para um humano, não adiante. Baseie decisões em status. O limiar de aceitação é configurado por tenant — pergunte ao seu contato na Inyo qual é o seu.

O bloco screening

Presente apenas quando houve uma coincidência entregue — ou seja, junto de um sanctions_clear que está failed (coincidência confirmada) ou indeterminate (não confirmada). Está ausente quando a triagem sai limpa, portanto sua presença significa "há algo a adjudicar", não "a triagem foi executada".

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

No máximo cinco coincidências são entregues — o suficiente para distinguir uma coincidência única plausível de um agrupamento óbvio de colisões. Apenas candidatos no seu limiar ou acima aparecem.

Uma peculiaridade que vale saber na adjudicação: a OFAC publica datas imprecisas colapsadas em 1º de janeiro, então um candidato listado nesse dia é comparado apenas pelo ano. Para quem nasceu genuinamente em 1º de janeiro isso afrouxa a correspondência, na direção da recusa.

Seu cliente nunca é informado de que uma coincidência de sanções foi o que o rejeitou. A resposta de recusa é idêntica byte a byte a qualquer outra falha sem nova tentativa.

Se a triagem estiver indisponível

A triagem falha aberta: uma indisponibilidade do provedor pula a checagem em vez de bloquear ou recusar a verificação. Nada no resultado entregue distingue uma sessão que seguiu sem triagem de uma que foi triada e saiu limpa — nesse caso simplesmente não existe nenhuma linha sanctions_clear. Se você precisa de evidência positiva de que toda verificação foi triada, verifique a presença dessa checagem, não a ausência de coincidência.

Próximos Passos

• Revisão Manual — in_review, autoStatus e manualReview
• Recebendo Resultados — como esse payload chega até você