> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ID Analysis

> API de ID Analysis da VU: envie a frente (e opcionalmente o verso) de um documento de identidade e receba os dados extraídos, o tipo de documento, o rosto recortado e as validações cruzadas.

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:

```js theme={null}
// 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
```

<Warning>
  **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.
</Warning>

## 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. |

<Note>
  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`.
</Note>

## 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.

```bash theme={null}
curl -X GET "$BASE_URL/version" \
  -H "Api-Key: $VU_ID_ANALYSIS_API_KEY"
```

<Warning>
  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.
</Warning>

## Um exemplo completo

```bash theme={null}
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):

```json theme={null}
{
  "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](/pt/vucs/face-analysis/introducao). `hasBackSide: true` indica que este template espera um verso.

## Ambientes

<Note>
  **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.
</Note>

## Continuar

<CardGroup cols={3}>
  <Card title="Integração" icon="code" href="/pt/vucs/id-analysis/integracao">
    Prepare as capturas, encadeie frente e verso, use o catálogo de templates e valide antes da produção.
  </Card>

  <Card title="Respostas" icon="list-check" href="/pt/vucs/id-analysis/respostas">
    Os campos extraídos, as validações cruzadas e os dois 200 que não aprovam nada.
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/pt/vucs/id-analysis/erros">
    Códigos, o 422 que ecoa a sua solicitação inteira e quais erros podem ser repetidos.
  </Card>
</CardGroup>


## Related topics

- [Erros e diagnóstico](/pt/vucs/id-analysis/erros.md)
- [Guia de integração](/pt/vucs/id-analysis/integracao.md)
- [Interpretação de respostas](/pt/vucs/id-analysis/respostas.md)
- [VU Cloud Services](/pt/vucs/introducao.md)
- [Documentação técnica da VU](/pt/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.