> ## 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.
# Integrar o Antispoofing Facial
> Como preparar a imagem, montar a chamada a /inference, tratar o campo info e validar a integração antes da produção.
## O percurso completo
```bash theme={null}
curl -i -X GET "$BASE_URL/version" -H "Api-Key: $VU_AS_FACE_API_KEY"
```
Um `200` confirma que a URL base e a api-key estão corretas. Um `401` significa chave inválida ou ambiente errado. Avalie o código de status, não o corpo: os números de versão mudam e não fazem parte do seu contrato.
Capture ou receba um JPEG, ajuste-o às dimensões recomendadas e converta-o para base64 sem prefixo.
Um único JSON com `image`, `info` e `logAnonymity`.
`status === 200 && spoofing === false` aprova. Todo o resto, não.
## Requisitos da imagem
| Aspecto | Valor | O que acontece se não for cumprido |
| - | - | - |
| Resolução recomendada | 640 × 480 (ou 480 × 640 na vertical) | É o tamanho com o qual o serviço foi calibrado. |
| Mínimo rígido | 224 × 224 | Abaixo disso: `400` com `Image should be larger than [224, 224]`. |
| Formato | JPEG, qualidade ≥ 95 | A compressão agressiva apaga os sinais que o serviço procura. |
| Codificação | base64 sem prefixo `data:` e sem quebras de linha | O serviço rejeita a carga ou falha ao decodificá-la. |
**Entre 224 × 224 e 640 × 480 não há erro, mas há menos detecção.** Várias camadas de análise precisam de resolução para funcionar. Uma imagem pequena passa na validação, é processada e devolve `200` — com menos camadas olhando. É a falha silenciosa mais cara desta integração: você não vai vê-la nos logs, vai vê-la na fraude.
Se o seu app móvel já captura em resolução maior, redimensione no servidor antes de enviar. Enviar 4 000 × 3 000 pixels não melhora a detecção e multiplica o tempo de resposta e o tamanho do payload.
### Converter para base64
```powershell Windows theme={null}
[Convert]::ToBase64String([IO.File]::ReadAllBytes("selfie.jpg")) | Set-Content -NoNewline selfie.b64
```
```bash Linux theme={null}
base64 -w 0 selfie.jpg > selfie.b64
```
```bash macOS theme={null}
base64 -i selfie.jpg -o selfie.b64
```
No Linux, `-w 0` evita as quebras de linha que o `base64` insere a cada 76 caracteres. Sem essa flag a cadeia chega partida e o serviço não consegue decodificá-la.
## Corpo da requisição
```json theme={null}
{
"info": "onboarding-12345",
"logAnonymity": true,
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD...v9Un0ooqDE//2Q=="
}
```
| Campo | Tipo | Descrição |
| - | - | - |
| `image` | string | A selfie em base64, sem prefixo. Obrigatório. |
| `info` | string | Sua referência de negócio. **Precisa ser uma cadeia**: se você enviar um objeto, recebe `422` com `Input should be a valid string`. |
| `logAnonymity` | boolean | Controla o nível de anonimização com que a VU registra a transação. Combine o valor com a VU conforme a sua política de dados. |
**Envie sempre um `info` não vazio** com um identificador que permita reconstruir o caso: número do processo, id da sessão de onboarding, o que o seu negócio usar. Ele volta na resposta e é o que conecta uma transação da VU a um usuário no seu sistema quando algo precisa ser investigado.
## O campo `info` na resposta
É aqui que mais integrações quebram. `info` **nem sempre é do mesmo tipo**:
| O que você envia | O que volta em `info` | Onde fica a sua referência |
| - | - | - |
| Um `info` e há diagnóstico anexado | Um **objeto** | Em `info.info` (pode ser `null`) |
| Um `info` sem diagnóstico anexado | Uma **string** (o eco do que você enviou) | Em `info` |
| Nada | **`null`** | Não há |
Resolva isso em um único lugar e nunca leia `info` diretamente:
```js theme={null}
function referencia(body) {
const i = body?.info;
return i == null ? null
: typeof i === "string" ? i
: i.info ?? null;
}
```
**Em Java, tipe `info` como `Object`, nunca como `String`.** É a causa número um de falhas de integração: o mapeamento funciona em todos os testes — onde `info` volta como cadeia — e explode em produção na primeira vez que um caso traz diagnóstico e `info` chega como objeto. O mesmo vale para qualquer desserializador estrito.
## Timeouts e novas tentativas
| Parâmetro | Valor | Motivo |
| - | - | - |
| Timeout | 30 s | A análise típica leva centenas de milissegundos, mas deixe margem. |
| Novas tentativas | No máximo 2, com backoff | Mais tentativas não melhoram o resultado e multiplicam a carga. |
| O que repetir | `499` e os `500` que **não** mencionam a imagem nem o payload | São falhas transitórias do serviço. |
| O que **não** repetir | `400`, `401`, `422` e qualquer `500` determinístico | O problema está na sua requisição; repetir devolve o mesmo erro. |
**Nunca repita uma resposta com `spoofing: true`.** É um veredito, não um erro. Repetir até obter outro resultado transforma o seu controle antifraude em um gerador de falsas aprovações.
## Antes de ir para produção
Uma integração está pronta quando você consegue responder sim a tudo isto:
1. A decisão está escrita na forma positiva: `status === 200 && spoofing === false`.
2. Nenhuma ramificação decide com base em `errorCode`, `values`, `confidence` ou `info`.
3. `info` é lido por meio de um único resolvedor que contempla objeto, string e `null`.
4. Em linguagens tipadas, `info` está declarado como tipo dinâmico ou `Object`.
5. `imageQuality` e seus subcampos são lidos como opcionais; nenhuma chave é presumida presente.
6. As imagens saem em 640 × 480 com qualidade JPEG ≥ 95.
7. Existe uma validação prévia que descarta imagens menores que 224 × 224 antes de gastar uma chamada.
8. O base64 é gerado sem prefixo `data:` e sem quebras de linha.
9. O timeout está em 30 s.
10. As novas tentativas estão limitadas a 2 e apenas para `499` e `500` não determinísticos.
11. O `id` de cada transação fica no seu log, junto com o ambiente e o carimbo de tempo.
12. A api-key vive somente no backend e está em um gerenciador de segredos, não no código.
13. O time sabe que `422 No Face Detected` é um problema de captura e que `422 Bad request` é um problema de código.
O próximo passo: o que significa cada campo da resposta e como ler o diagnóstico.
## Related topics
- [Antispoofing Facial](/pt/vucs/antispoofing-facial/introducao.md)
- [Integrar o Connection Fingerprint](/pt/vucs/connection-fingerprint/integracao.md)
- [Erros e diagnóstico](/pt/vucs/antispoofing-facial/erros.md)
- [Prova de Vida e Biometria Facial no Identity Link](/pt/identity-link/prova-de-vida.md)
- [Interpretação de respostas](/pt/vucs/face-analysis/respostas.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.