ID Verification (Frente/Verso do documento)
ID Verification
ID Verification (Frente/Verso do documento)
Verificar documento de identidade (frente e opcional verso), extrair MRZ e dados, obter Aprovado ou Recusado em uma única chamada. Consulte o esquema do.
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:- Integração ID Verification ativada: Sua organização deve ter a integração KYC ID Verification ativada (por exemplo no Marketplace / Integrações).
- 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
Apenasmultipart/form-data é aceito. Você pode enviar as imagens de duas formas (ou misturar):
- Como arquivos: anexar imagens nos campos do form
documentFronte (opcional)documentBack. - Como base64: enviar os mesmos nomes de campo com a imagem em base64 (com ou sem prefixo
data:image/...;base64,).
Headers
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
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.Imagem do verso (opcional; obrigatória para documentos de duas faces como RG). Igual a
documentFront: arquivo ou base64.UUID opcional da entidade pessoa a associar a esta verificação. Usado para auditoria e para listar verificações por entidade.
Referência opcional (por exemplo seu ID de usuário) para rastreamento. Armazenada no registro de auditoria.
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.Igual ao query param
doubleCheckRenaper.Se realizar liveness do documento (detectar tela/cópia). Padrão
false. Enviar como string "true" ou "false" no form.Idade mínima (1–120); abaixo disso é recusado. Opcional. Enviar como string no form.
"NO_ACTION" ou "DECLINE" quando a data de validade não é detectada. Opcional."NO_ACTION" ou "DECLINE" quando o MRZ é inválido. Opcional."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 emextractedData 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 quefullNameemextractedDataquando 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 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 emid_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
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
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:
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_validationse 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 emkyc_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