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

# Guia de integração

> Como integrar o ID Analysis: prepare as capturas, encadeie frente e verso com relatedUuid, use o catálogo de templates e valide a integração antes da produção.

## O fluxo em cinco passos

<Steps>
  <Step title="Verifique a conectividade">
    `GET /version` com a sua `Api-Key`. Deve devolver `200`. Avalie o código de status, não o corpo. Se falhar, o problema é de URL, rede ou proxy — ainda não há nada para depurar do lado da API.
  </Step>

  <Step title="Prepare a captura">
    Uma foto do documento, bem iluminada, sem reflexos, com as quatro bordas dentro do quadro. Base64 **sem** o prefixo `data:`.
  </Step>

  <Step title="Envie a frente">
    `POST /front` com `info` e `image`. Guarde o `uuid` devolvido: é o identificador da transação e o vínculo com o verso.
  </Step>

  <Step title="Envie o verso (se o template tiver um)">
    Se a frente devolveu `hasBackSide: true`, chame `POST /back` com o mesmo `info`, a imagem do verso e o `uuid` da frente como `relatedUuid`.
  </Step>

  <Step title="Decida com a regra na forma positiva">
    Frente: `200` + `"Operation end successfully."` + `id !== "unknown"`. Verso: adicionalmente `frontBackTemplateValidation === true`, e depois revise `crossMatchConfidence`. Os detalhes estão na [introdução](/pt/vucs/id-analysis/introducao).
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant C as Seu backend
    participant A as ID Analysis
    C->>A: POST /front (info, image)
    A-->>C: 200 · uuid · id · front.viz · hasBackSide
    C->>A: POST /back (info, image, relatedUuid = uuid)
    A-->>C: 200 · back.mrz · validações · crossMatchConfidence
```

## O corpo da solicitação

| Campo | Aplica-se a | O que faz |
| - | - | - |
| `info` | ambos | **Obrigatório.** A sua referência, 2–256 caracteres, devolvida tal como enviada. |
| `image` | ambos | **Obrigatório.** A captura em base64, sem prefixo `data:`. |
| `relatedUuid` | só `/back` | O `uuid` da frente. **Obrigatório em `/back`, proibido em `/front`.** |
| `documentId` | `/front` | Uma pista de template (p. ex. `VU-ARG-ID-04`): inferência mais rápida e restrita. |
| `possibleCountries` | `/front` | Restringe a inferência a uma lista de códigos de país ISO. |
| `antiSpoofingDocument` | `/front` | Adiciona os blocos `security.*`: recaptura de tela, fotocópia, sinais de adulteração no próprio documento. |
| `antiSpoofingFaceInDocument` | `/front` | Adiciona `face.isSpoofing` para o retrato impresso no documento. |
| `strictBorderMode` | `/front` | Rejeita capturas em que as bordas do documento estão cortadas. |
| `logAnonymity` | ambos | Pede ao serviço que não persista dados pessoais nos seus logs. |
| `events` | ambos | Adiciona o rastro interno do pipeline. Só para diagnóstico. |

<Warning>
  **Nunca envie `relatedUuid` em `/front`.** Esse campo pertence exclusivamente a `/back`; incluí-lo em `/front` produz um `500` determinístico. E apesar do que a mensagem de erro de `/back` sugere, `documentId` **não** substitui `relatedUuid` — só `relatedUuid` vincula a transação.
</Warning>

## Requisitos de imagem

| Aspecto | Requisito |
| - | - |
| Resolução mínima | **480 × 480 px** — abaixo disso, `400`. |
| Resolução máxima útil | \~**1920 px** no lado maior — imagens maiores são reduzidas internamente; enviar mais só adiciona tempo de upload. |
| Enquadramento | O documento inteiro, as quatro bordas visíveis, sem dedos sobre os dados. |
| Compressão | JPEG qualidade **≥ 90**. A compressão agressiva degrada o OCR. |
| Codificação | Base64 padrão, sem prefixo `data:`, sem quebras de linha. |

Para converter uma imagem em base64:

<CodeGroup>
  ```powershell Windows (PowerShell) theme={null}
  [Convert]::ToBase64String([IO.File]::ReadAllBytes('C:\caminho\frente.jpg')) | Set-Clipboard
  ```

  ```bash Linux theme={null}
  base64 -w0 frente.jpg
  ```

  ```bash macOS theme={null}
  base64 -i frente.jpg | pbcopy
  ```
</CodeGroup>

## O catálogo de templates

| Endpoint | Devolve |
| - | - |
| `GET /listTemplates` | Um array simples com todos os ids de template suportados. |
| `GET /listTemplatesByCountry` | O mesmo catálogo agrupado por país. |
| `GET /{templateId}/details` | Quais campos VIZ, MRZ, código de barras e rosto aquele template carrega. |
| `GET /{templateId}/images` | Imagens de amostra anonimizadas (`front`/`back` são arrays de 1 elemento). |

Os ids de template seguem `VU-<ISO3>-<TYPE>-<NN>` — `ID` identidade nacional, `IDF` identidade de estrangeiro, `PA` passaporte, `DL` carteira de motorista.

<Tip>
  `GET /{templateId}/details` é a fonte **autoritativa** de quais campos esperar em `viz` — o conjunto varia por template. Programe o seu parser contra os details do template, não contra uma resposta de exemplo.
</Tip>

<Note>
  Um erro `Bad relatedUuid` **imediatamente** depois de uma frente bem-sucedida pode ser atraso de replicação: espere um segundo e repita **uma vez**. Se persistir, o `relatedUuid` está realmente errado.
</Note>

## Timeouts e novas tentativas

| Situação | Política |
| - | - |
| Timeout de leitura | **≥ 30 s** — OCR mais validações levam tempo. |
| `5xx` esporádico | Repetir com backoff, no máximo 2 vezes. |
| `500` determinístico (`relatedUuid` em `/front`) | Não repetir: corrigir a solicitação. |
| `400` / `401` / `404` / `422` | Não repetir: corrigir a captura, a credencial, a rota ou o corpo. |

<Warning>
  **As respostas pesam \~1 MB.** Elas embutem o documento normalizado, o rosto recortado e — com MRZ — a faixa do MRZ, tudo em base64. Dimensione os seus buffers e não registre corpos de resposta crus.
</Warning>

## Antes de ir para a produção

1. `GET /version` devolve `200` a partir da sua conectividade de produção.
2. A sua condição de aceitação exige `200` **e** `message: "Operation end successfully."` **e** `id !== "unknown"` (frente), mais `frontBackTemplateValidation === true` (verso).
3. Você testou um verso trocado e o seu sistema o rejeita.
4. Você testou uma foto sem documento e o seu sistema pede outra captura em vez de aceitar campos vazios.
5. As suas capturas têm ≥ 480 × 480 px e o base64 vai sem prefixo `data:`.
6. `relatedUuid` é enviado só em `/back`, nunca em `/front`.
7. Os seus logs nunca persistem corpos de erro crus (o 422 ecoa a sua solicitação, imagem incluída) nem as imagens das respostas.
8. Timeout de leitura ≥ 30 s; novas tentativas só para `5xx` esporádicos, com backoff.
9. O seu parser lê os campos declarados por `GET /{templateId}/details` para cada template que você aceita.
10. Você envia um `info` próprio por operação e registra o `uuid` de cada resposta.

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


## Related topics

- [Guia de integração](/pt/vucs/face-analysis/integracao.md)
- [Identity Link API: Guia de Integração Completo](/pt/identity-link/introducao.md)
- [Changelog da Identity Link API](/pt/identity-link/changelog.md)
- [Antispoofing Facial](/pt/vucs/antispoofing-facial/introducao.md)
- [Webhooks do Identity Link: Eventos do Ciclo de Verificação](/pt/identity-link/webhooks.md)


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