Skip to main content

​
O percurso completo

1

Verifique conectividade e credenciais

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

Prepare a imagem

Capture ou receba um JPEG, ajuste-o às dimensões recomendadas e converta-o para base64 sem prefixo.
3

Chame POST /inference

Um único JSON com image, info e logAnonymity.
4

Aplique a regra de decisão

status === 200 && spoofing === false aprova. Todo o resto, não.

​
Requisitos da imagem

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

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

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: Resolva isso em um único lugar e nunca leia info diretamente:
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

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.

Respostas

O próximo passo: o que significa cada campo da resposta e como ler o diagnóstico.
Última modificação em 9 de setembro de 2026