ID Analysis

O serviço de ID Analysis lê documentos de identidade. Você envia a foto da frente de um documento e recebe o tipo de documento identificado, os dados extraídos da zona visual (VIZ), o rosto recortado e — se depois enviar o verso — o MRZ, o código de barras e as validações cruzadas entre os dois lados e entre as fontes de dados. O fluxo é sempre o mesmo e não carrega outro estado: POST /front devolve um uuid; esse uuid viaja como relatedUuid em POST /back; a resposta do verso traz as validações cruzadas.

A regra de decisão

Esta é a parte mais importante da integração. Escreva-a na forma positiva:

// Frente: as três condições. Qualquer outra coisa NÃO leu o documento.
const frenteOk = status === 200
  && body.message === "Operation end successfully."
  && body.id !== "unknown";          // o tipo de documento foi identificado

// Verso: além do anterior
const versoOk = body.back.frontBackTemplateValidation === true;
// depois revise body.crossMatchConfidence antes de confiar nos dados

HTTP 200 não significa «dados extraídos». Uma foto sem documento legível também devolve 200 — com message: "Cant get document fields", id: "unknown" e um viz vazio. E um verso que pertence a outro documento também devolve 200 / "Operation end successfully." — o que muda é back.frontBackTemplateValidation: false. Quem decide só pelo código de status aceita leituras vazias e documentos misturados.

Os três identificadores — não os confunda

Campo	O que é
`uuid`	O identificador da transação. É o valor que viaja como `relatedUuid` em `/back` e o que o suporte precisa. Também chega no cabeçalho `x-request-id`.
`id`	O tipo de documento identificado (p. ex. `VU-ARG-ID-04`), ou `"unknown"`.
`info`	A sua referência (2–256 caracteres), devolvida tal como enviada.

Os corpos de erro trazem um uuid gerado na hora que não corresponde a nenhuma transação — só os 200 de /front devolvem um uuid utilizável como relatedUuid.

Endpoints

Método	Caminho	Para que serve
`POST`	`/front`	Analisar a frente. Devolve o `uuid` da transação.
`POST`	`/back`	Analisar o verso, vinculado por `relatedUuid`. Devolve as validações cruzadas.
`GET`	`/listTemplates`	O catálogo de templates de documento suportados.
`GET`	`/listTemplatesByCountry`	O catálogo agrupado por país.
`GET`	`/{templateId}/details`	Quais campos, MRZ, código de barras e rosto esperar de um template.
`GET`	`/{templateId}/images`	Imagens de amostra anonimizadas de um template.
`GET`	`/version`	Verificar conectividade. Avalie o código de status, não o corpo.

A URL base depende do ambiente e é fornecida pela VU junto com a sua api-key. Nos exemplos ela aparece como BASE_URL.

Autenticação

Toda chamada leva o cabeçalho Api-Key com a chave do seu ambiente.

curl -X GET "$BASE_URL/version" \
  -H "Api-Key: $VU_ID_ANALYSIS_API_KEY"

A api-key vive no seu backend. Nunca a embuta em um app móvel nem no front-end: qualquer pessoa consegue extraí-la do binário ou do bundle.

Um exemplo completo

curl -X POST "$BASE_URL/front" \
  -H "Api-Key: $VU_ID_ANALYSIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "info": "onboarding-12345",
    "image": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
  }'

Uma leitura bem-sucedida se parece com isto, reduzida aos campos que importam (documento specimen, pessoa fictícia):

{
  "uuid": "e2084653-7268-4748-9b80-a0da6a22a875",
  "info": "onboarding-12345",
  "message": "Operation end successfully.",
  "id": "VU-ARG-ID-04",
  "front": {
    "ocrType": "template",
    "viz": {
      "name": "NIHAD ELIDUVINA",
      "lastName": "CELDA",
      "documentNumber": "99999999"
    },
    "face": { "image": "/9j/4AAQ..." },
    "hasBackSide": true
  }
}

front.face.image é o rosto recortado do documento — a imagem que você compara com a selfie usando o Face Analysis. hasBackSide: true indica que este template espera um verso.

Ambientes

O ambiente de homologação pode estar à frente da produção. Ele também valida versões pré-produtivas, então pode diferir em tempo de resposta e no resultado da extração. Use-o para certificar a sua integração — o contrato, os códigos, o tratamento de erros —, não como referência de performance.

Continuar

Integração

Prepare as capturas, encadeie frente e verso, use o catálogo de templates e valide antes da produção.

Respostas

Os campos extraídos, as validações cruzadas e os dois 200 que não aprovam nada.

Erros

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

Comece aqui

Face Analysis

Antispoofing Facial

Connection Fingerprint

ID Analysis

A regra de decisão

Os três identificadores — não os confunda

Endpoints

Autenticação

Um exemplo completo

Ambientes

Continuar

Integração

Respostas

Erros

​A regra de decisão

​Os três identificadores — não os confunda

​Endpoints

​Autenticação

​Um exemplo completo

​Ambientes

​Continuar

Integração

Respostas

Erros

A regra de decisão

Os três identificadores — não os confunda

Endpoints

Autenticação

Um exemplo completo

Ambientes

Continuar