Guia de integração

O fluxo em quatro passos

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.

Prepare as imagens

JPEG ou PNG, em base64 sem o prefixo data: e sem quebras de linha. Um rosto por imagem, frontal, bem iluminado.

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.

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.

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:

[Convert]::ToBase64String([IO.File]::ReadAllBytes('C:\caminho\selfie.jpg')) | Set-Clipboard

base64 -w0 selfie.jpg

base64 -i selfie.jpg | pbcopy

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.

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.

As três formas de comparar

// 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 }

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.

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

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

Próximo: Respostas

A matriz biométrica campo a campo, o veredito de qualidade que muda de forma e o antispoofing aninhado.

Comece aqui

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

O fluxo em quatro passos

Requisitos de imagem

O corpo da solicitação

As três formas de comparar

Um lote não tolera falhas parciais

Timeouts e novas tentativas

Antes de ir para a produção

Próximo: Respostas

​O fluxo em quatro passos

​Requisitos de imagem

​O corpo da solicitação

​As três formas de comparar

​Um lote não tolera falhas parciais

​Timeouts e novas tentativas

​Antes de ir para a produção

Próximo: Respostas

O fluxo em quatro passos

Requisitos de imagem

O corpo da solicitação

As três formas de comparar

Um lote não tolera falhas parciais

Timeouts e novas tentativas

Antes de ir para a produção