Interpretação de respostas

Os campos de primeiro nível

Campo	O que é
`uuid`	O identificador da transação. Registre-o sempre; ele vincula o `/back` e os chamados de suporte.
`info`	A sua referência, devolvida tal como enviada.
`message`	O resultado global. Só `"Operation end successfully."` conta como leitura bem-sucedida.
`id`	O tipo de documento identificado (p. ex. `VU-ARG-ID-04`), ou `"unknown"`.
`front` / `back`	O resultado por lado: extração, rosto recortado, validações.
`crossMatchConfidence`	Consistência entre fontes de dados (MRZ vs VIZ vs código de barras), 0–100 por campo.
`events`	O rastro interno do pipeline, se você o pediu — ou sem pedir, quando a leitura falhou.

Dentro de `front` e `back`

Campo	O que traz
`ocrType`	Como o lado foi lido: `template` (um template conhecido guiou a extração) ou OCR genérico.
`viz`	Os campos da zona visual. Quais campos aparecem depende do template — `GET /{templateId}/details` é autoritativo. Vazio (`{}`) quando nada foi lido.
`mrz`	A zona de leitura mecânica (verso): campos interpretados, as linhas cruas e checksums por campo.
`barcode`	O conteúdo do código de barras. `result` é um array de 1 elemento.
`face`	O retrato recortado do documento, em base64 — a entrada para o Face Analysis.
`hasBackSide`	Se este template espera um verso.

As validações do verso

Campo	Significado
`frontBackTemplateValidation`	`true` = o verso pertence ao mesmo tipo de documento da frente. Parte da regra de decisão.
`backIsTheSameIdTypeThatFront`	O equivalente legado: `1` = não corresponde, `99` = mesmo tipo mas sem dados comparáveis.
`frontBackDataValidation`	Comparação de dados entre os lados. `-1` = não computada.

A armadilha mais cara: um verso trocado não é um erro HTTP. Frente de um documento + verso de outro = 200 / "Operation end successfully." — o OCR funcionou, nas duas imagens; por isso a análise «deu certo». A detecção está em back.frontBackTemplateValidation: false (com backIsTheSameIdTypeThatFront: 1). Um sistema que decide pelo código de status aceita documentos montados com lados de dois documentos diferentes.

{
  "uuid": "4312af20-89ab-42a1-92a1-7bc0fe12de60",
  "message": "Operation end successfully.",
  "id": "VU-ARG-ID-04",
  "back": {
    "frontBackTemplateValidation": false,
    "backIsTheSameIdTypeThatFront": 1
  }
}

O outro 200 que não aprova nada

Uma foto sem documento legível devolve 200 com message: "Cant get document fields", id: "unknown", um viz vazio — e um bloco events não solicitado com o rastro do pipeline:

{
  "uuid": "b89bff81-53ba-4c8f-b02e-0e81f0722cbd",
  "message": "Cant get document fields",
  "id": "unknown",
  "front": { "viz": {} }
}

Trate-o como «peça outra captura ao usuário», nunca como uma aprovação com campos vazios.

`crossMatchConfidence`

Consistência entre fontes de dados, em porcentagens 0–100 por campo:

{
  "crossMatchConfidence": {
    "mrzVersusViz": {
      "documentNumber": 88.9,
      "name": 100,
      "lastName": 100,
      "birthDate": 100
    }
  }
}

Um 88.9 em um campo geralmente significa um caractere de OCR duvidoso. Só com a frente, crossMatchConfidence costuma ser {} — há apenas uma fonte para comparar; isso é normal, não uma falha.

O serviço não impõe limiar. A política de aceitação sobre crossMatchConfidence é sua: um onboarding estrito pode exigir 100 no número do documento e tolerar menos nos nomes.

O antispoofing de documento é informativo

Com antiSpoofingDocument / antiSpoofingFaceInDocument, a resposta adiciona os blocos security.* (recaptura de tela, fotocópia, pontuações de adulteração — p. ex. 94.69, 99) e face.isSpoofing.

Esses vereditos não mudam o código HTTP nem o message: um documento marcado como recapturado continua devolvendo 200 / "Operation end successfully.". Se a sua política rejeita por esses sinais, avalie-os explicitamente. Um bloco security vazio ({}) significa «não avaliado», não «limpo».

Particularidades do desserializador

mrz.expected é tri-estado: true / false / ausente.
Os valores dentro de mrz.extras são strings, mesmo quando parecem numéricos.
barcode.result é um array de 1 elemento, não um objeto.
isNativePersonDocument também é tri-estado.
viz depende do template: nunca fixe o conjunto de campos no código; leia GET /{templateId}/details.
As respostas pesam ~1 MB (imagens base64 embutidas): dimensione os buffers e nunca registre corpos crus.

Próximo: Erros

Códigos, o 422 que ecoa a sua solicitação inteira — imagem incluída — e quais erros podem ser repetidos.

Comece aqui

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

Interpretação de respostas

Os campos de primeiro nível

Dentro de `front` e `back`

As validações do verso

O outro 200 que não aprova nada

`crossMatchConfidence`

O antispoofing de documento é informativo

Particularidades do desserializador

Próximo: Erros

​Os campos de primeiro nível

​Dentro de front e back

​As validações do verso

​O outro 200 que não aprova nada

​crossMatchConfidence

​O antispoofing de documento é informativo

​Particularidades do desserializador

Próximo: Erros

Os campos de primeiro nível

Dentro de `front` e `back`

As validações do verso

O outro 200 que não aprova nada

`crossMatchConfidence`

O antispoofing de documento é informativo

Particularidades do desserializador