Skip to main content
POST
ID Verification (Frente/Verso do documento)

Resumo

ID Verification é um serviço de verificação da Gu1 que valida um documento de identidade enviando a imagem da frente (obrigatória) e opcionalmente a imagem do verso (para documentos de duas faces como RG). A API retorna Aprovado ou Recusado, dados extraídos (nome, número do documento, data de nascimento, endereço, MRZ, etc.) e avisos opcionais. Não há sessão hospedada: você envia as imagens e recebe o resultado em uma chamada.
Quando usar cada um
  • KYC por sessão (POST /api/kyc/validations): Fluxo completo com URL hospedada, selfie ao vivo, liveness e captura de documento. Ideal para onboarding e fluxos regulados.
  • Face Match (POST /api/kyc/face-match): Comparar duas imagens (foto do documento + selfie) para verificar se são a mesma pessoa; retorna correspondência + pontuação.
  • ID Verification (POST /api/kyc/id-verification): Enviar frente (e opcional verso) do documento; obter validação do documento, dados extraídos (MRZ, nome, endereço, etc.) e Aprovado/Recusado. Ideal quando você já tem as imagens do documento e só precisa de extração + validação.

Pré-requisitos

Antes de usar o ID Verification:
  1. Integração ID Verification ativada: Sua organização deve ter a integração KYC ID Verification ativada (por exemplo no Marketplace / Integrações).
  2. Credenciais configuradas: A API key da integração ID Verification deve estar configurada nas configurações KYC da organização (definido pelo administrador da Gu1). Apenas a API key é necessária (sem webhook secret para este endpoint).
ID Verification é um serviço da Gu1. Toda a verificação é feita na infraestrutura da Gu1.

Solicitação

Endpoint

Content-Type

Apenas multipart/form-data é aceito. Você pode enviar as imagens de duas formas (ou misturar):
  1. Como arquivos: anexar imagens nos campos do form documentFront e (opcional) documentBack.
  2. Como base64: enviar os mesmos nomes de campo com a imagem em base64 (com ou sem prefixo data:image/...;base64,).
documentFront é obrigatório: é preciso enviar arquivo ou base64. Se não enviar nenhum, a API retorna 400. documentBack é opcional. Se enviar arquivo e base64 para o mesmo campo, o arquivo é usado.

Headers

Não defina Content-Type manualmente ao usar FormData; o cliente define com o boundary correto. Se sua conta usa escopo por organização, inclua:

Campos do form

documentFront
file | string
required
Imagem da frente do documento. Enviar como arquivo (recomendado) ou como string (base64, com ou sem prefixo data:image/...;base64,). Formatos: JPEG, PNG, WebP, TIFF, PDF. Máx. 5MB.
documentBack
file | string
Imagem do verso (opcional; obrigatória para documentos de duas faces como RG). Igual a documentFront: arquivo ou base64.
entityId
string
UUID opcional da entidade pessoa a associar a esta verificação. Usado para auditoria e para listar verificações por entidade.
vendorData
string
Referência opcional (por exemplo seu ID de usuário) para rastreamento. Armazenada no registro de auditoria.
doubleCheckRenaper
boolean
Com true, após approved do documento executa chequeo RENAPER de dados (DNI + gênero + trâmite do OCR vs renaper/data). Requer credenciais RENAPER. Query prevalece sobre o body.
doubleCheckRenaper
boolean
Igual ao query param doubleCheckRenaper.
performDocumentLiveness
boolean
Se realizar liveness do documento (detectar tela/cópia). Padrão false. Enviar como string "true" ou "false" no form.
minimumAge
number
Idade mínima (1–120); abaixo disso é recusado. Opcional. Enviar como string no form.
expirationDateNotDetectedAction
string
"NO_ACTION" ou "DECLINE" quando a data de validade não é detectada. Opcional.
invalidMrzAction
string
"NO_ACTION" ou "DECLINE" quando o MRZ é inválido. Opcional.
inconsistentDataAction
string
"NO_ACTION" ou "DECLINE" quando os dados visuais não batem com o MRZ. Opcional.

Resposta

Resposta de sucesso (200 OK)

Se RENAPER falhar após aprovação OCR, status vira "declined" e códigos RENAPER entram em warnings.

Campos de extractedData

Os seguintes campos são devolvidos em extractedData e gravados em id_verification_verifications.extracted_data (listar/obter auditoria). Campos vazios são omitidos. Identidade e documento (comuns): Complementares (aninhados; podem estar vazios):
Campos promovidos vs. extensão
  • Identificadores frequentes (taxNumber, firstSurname, secondSurname, firstIssueDate, ejemplar, etc.) são elevados ao mesmo nível que fullName em extractedData quando o OCR os devolve.
  • Outras chaves do documento ficam em extractedData.extraFields (mesmo objeto no POST e na listagem/detalhe de auditoria).
Não incluído nas respostas API nem no JSON de auditoria
  • URLs temporárias de imagens do fluxo de verificação — usar imagens armazenadas (document-front-image / document-back-image) do que enviou à Gu1.
  • Corpo bruto completo da verificação (não exposto em APIs de produção).
Exemplo (aprovado):
Exemplo (recusado com avisos e campos extra LATAM):
Exemplo (DNI argentino):

Exemplo de solicitação

Respostas de erro

Códigos de erro comuns:

Auditoria e listagem de verificações

Cada solicitação de ID Verification (sucesso ou falha) é armazenada em id_verification_verifications para auditoria e conformidade. A resposta inclui verificationId (ID do registro de auditoria) quando a persistência tem sucesso. Todos os endpoints abaixo são da API Gu1.

Obter uma verificação

Retorna um registro de auditoria por ID. Path: id — UUID da verificação (o verificationId da resposta do POST ou da listagem). Resposta (200): Mesmo formato de um item da listagem: id, organizationId, entityId, status, requestId, vendorData, errorMessage, warnings, extractedData, createdAt, documentFrontStoragePath, documentBackStoragePath, storageProvider, etc.
404 se não existir ou não pertencer à sua organização.

Listar registros de auditoria

Parâmetros de query: Resposta: { "verifications": [ ... ], "pagination": { "limit", "offset", "total" } }. Cada verificação inclui id, entityId, status, requestId, extractedData, warnings, errorMessage, createdAt e caminhos de armazenamento quando as imagens foram salvas.

Obter imagens do documento armazenadas

Se a verificação tiver imagens salvas (documentFrontStoragePath / documentBackStoragePath), você pode obtê-las com:
Path: id — UUID da verificação. Resposta: bytes da imagem (ex.: Content-Type: image/jpeg). 404 se a verificação não existir ou esse lado não foi armazenado.

Convivência com outros fluxos KYC

  • Fluxo por sessão cria um registro em kyc_validations e usa uma URL hospedada; a decisão armazenada pode incluir documento, liveness e face match da sessão ao vivo.
  • Face Match compara foto do documento + selfie e retorna correspondência + pontuação; auditoria em face_match_verifications.
  • ID Verification valida o documento (frente/verso), extrai dados e retorna Aprovado/Recusado; auditoria em id_verification_verifications. Não cria registro em kyc_validations. Use quando precisar apenas de validação e extração do documento sem sessão hospedada.

Próximos passos

Face Match (Documento + Selfie)

Comparar documento e selfie

Criar validação KYC

Verificação por sessão com URL hospedada