Skip to main content

​
O fluxo em cinco passos

1

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

Prepare a captura

Uma foto do documento, bem iluminada, sem reflexos, com as quatro bordas dentro do quadro. Base64 sem o prefixo data:.
3

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

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

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.

​
O corpo da solicitação

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.

​
Requisitos de imagem

Para converter uma imagem em base64:

​
O catálogo de templates

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

​
Timeouts e novas tentativas

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.

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

Próximo: Respostas

Os campos extraídos, as validações entre frente e verso e os dois 200 que não aprovam nada.
Última modificação em 9 de setembro de 2026