> ## 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 Face Analysis: prepare as imagens, alinhe operations com images, monte a chamada e valide a integração antes da produção.

## O fluxo em quatro passos

<Steps>
  <Step title="Verifique a conectividade">
    `GET /version` com a sua `Api-Key` (ele não a exige, mas assim você testa o cabeçalho completo). Deve devolver `200`. Avalie o código de status, não o corpo: o formato do corpo não faz parte do contrato. Se falhar, o problema é de URL, rede ou proxy — ainda não há nada para depurar do lado da API.
  </Step>

  <Step title="Prepare as imagens">
    JPEG ou PNG, em base64 **sem** o prefixo `data:` e sem quebras de linha. Um rosto por imagem, frontal, bem iluminado.
  </Step>

  <Step title="Declare as operações">
    `operations` é uma **lista de listas alinhada com `images`**: `operations[i]` aplica-se a `images[i]`. Se você a omitir, cada imagem roda `biometric` por padrão.
  </Step>

  <Step title="Decida com a regra na forma positiva">
    `status === 200 && biometric["0"]["1"] >= 70` confirma; qualquer outra coisa não confirma. Os detalhes do limiar estão na [introdução](/pt/vucs/face-analysis/introducao).
  </Step>
</Steps>

## Requisitos de imagem

| Aspecto | Requisito |
| - | - |
| Resolução mínima rígida | **160 × 160 px** — abaixo disso, o serviço devolve `400`. |
| Resolução recomendada | **≥ 360 × 360 px** — abaixo de 360, o veredito de qualidade é degradado automaticamente para `low`, mesmo com o HTTP em `200`. |
| Rosto | Um só por imagem, frontal, olhos visíveis. |
| Compressão | JPEG qualidade **≥ 90**. A compressão agressiva degrada os atributos e a pontuação biométrica. |
| 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\selfie.jpg')) | Set-Clipboard
  ```

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

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

## O corpo da solicitação

| Campo | Tipo | O que faz |
| - | - | - |
| `info` | string, **obrigatório** | A sua referência da operação, de 2 a 256 caracteres. Devolvida tal como enviada. |
| `images` | string\[], **obrigatório** | As imagens em base64. |
| `operations` | string\[]\[] | As operações por imagem, alinhadas com `images`. Omitida ⇒ `biometric` para todas. |
| `faceVectors` | number\[]\[] | Vetores biométricos guardados (512 valores) para comparar com as imagens. Continuam a numeração depois das imagens. |
| `distanceMethodology` | string | `vu_v4` (padrão), `cosine` ou `euclidean_l2`. Muda a **escala** da pontuação. |
| `returnFaceVector` | boolean | Devolve o vetor de 512 valores de cada rosto, para guardar e comparar depois sem a foto. |
| `returnFaceImage` | boolean | Devolve o recorte alinhado do rosto em base64. |
| `events` | boolean | Adiciona o rastro interno de execução. Só para diagnóstico. |

<Warning>
  **Um `operations` desalinhado não é um `400` arrumado.** Uma lista `operations` mais curta que `images` produz um `500` com corpo em **texto puro** (`Internal Server Error`), e omitir `images` também. Valide o alinhamento antes de chamar; esses erros são da sua solicitação e repeti-los devolve exatamente a mesma coisa.
</Warning>

## As três formas de comparar

```json theme={null}
// 1. Selfie vs foto do documento: duas imagens
{ "info": "op-1", "images": ["<selfie>", "<docFace>"], "operations": [["biometric"], ["biometric"]] }

// 2. Selfie vs vetor guardado: uma imagem + um faceVector
//    O vetor continua a numeração: a selfie é "0", o vetor é "1".
{ "info": "op-2", "images": ["<selfie>"], "faceVectors": [[0.031, -0.114, "...512 valores"]] }

// 3. Cadastrar: pedir o vetor para guardá-lo
{ "info": "op-3", "images": ["<selfie>"], "returnFaceVector": true }
```

<Note>
  Se você guarda vetores para comparar depois, guarde também **com qual metodologia** foram gerados e compare sempre com a mesma. Um vetor `vu_v4` comparado com `euclidean_l2` dá pontuações de outra escala e o seu limiar deixa de valer.
</Note>

## Um lote não tolera falhas parciais

Se você envia 4 imagens e a terceira não tem rosto, não recebe 3 resultados e um erro: recebe **um único `400`** com `imageNumber: 2` (base 0) e nenhum resultado. Não há resultados parciais. Se o seu fluxo tolera falhas por imagem, envie uma solicitação por imagem.

## Timeouts e novas tentativas

| Situação | Política |
| - | - |
| Timeout de leitura | **30 s** — cada imagem do lote soma tempo de processamento. |
| `500` esporádico | Repetir com backoff, no máximo 2 vezes. |
| `500` que volta idêntico | É a sua solicitação (`images` ausente ou `operations` desalinhado). Não repetir: corrigir. |
| No-match ou `spoofing: true` | **Nunca** repetir com a mesma imagem: o resultado é determinístico. |
| `400` / `401` / `422` | Não repetir: corrigir a solicitação ou a credencial. |

## 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 verificação exige `200` **e** pontuação ≥ 70 sobre `biometric["0"]["1"]`, e uma resposta inesperada não aprova por exclusão.
3. Se você mudou `distanceMethodology`, calibrou o seu próprio limiar e não reutilizou o 70.
4. O seu desserializador indexa os resultados por **string** (`"0"`, `"1"`) e tolera `inferenceConfidence` com ou sem `code`/`confidence`.
5. O seu cliente HTTP tolera corpos de erro **que não são JSON** (os `500` em texto puro).
6. `operations` tem exatamente uma entrada por imagem.
7. As imagens têm pelo menos 360 × 360 e o JPEG vai em qualidade ≥ 90.
8. Você nunca repete um no-match nem um `spoofing: true` com a mesma imagem.
9. A api-key vive no seu backend, nunca no app móvel nem no front-end.
10. Você envia um `info` próprio por operação e registra o `id` de cada resposta.
11. `events` fica desabilitado em produção: o rastro é para diagnóstico.

<Card title="Próximo: Respostas" icon="list-check" href="/pt/vucs/face-analysis/respostas">
  A matriz biométrica campo a campo, o veredito de qualidade que muda de forma e o antispoofing aninhado.
</Card>


## Related topics

- [Guia de integração](/pt/vucs/id-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.