> ## Documentation Index > Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## 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 ``` POST https://api.gu1.ai/api/kyc/id-verification ``` ### 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 ``` Authorization: Bearer SUA_API_KEY Content-Type: multipart/form-data; boundary=----... ``` 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: ``` X-Organization-Id: SEU_ORGANIZATION_ID ``` ### 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) | Campo | Tipo | Descrição | | ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `status` | string | `"approved"` \| `"declined"`. | | `verificationId` | string (opcional) | ID do registro de auditoria em `id_verification_verifications` (suporte e listagem). | | `requestId` | string (opcional) | ID interno da solicitação (suporte). | | `extractedData` | object (opcional) | OCR e metadados de verificação do serviço ID Verification da Gu1, normalizados e persistidos na auditoria. Ver [campos de extractedData](#campos-de-extracteddata) abaixo. | | `warnings` | string\[] (opcional) | Array de **códigos de risco** da verificação (ex.: `DOCUMENT_EXPIRED`, `POSSIBLE_DUPLICATED_USER`). Usar para exibição ou i18n. Veja [Códigos de risco em avisos](/pt/use-cases/kyc/warning-risk-codes) para todos os valores. | | `debugProviderResponse` | object (opcional) | **Apenas não produção** (API Gu1 com `NODE_ENV=development`). Resposta completa de verificação sanitizada para depuração (sem imagens/base64). Não usar em integrações de produção. | | `doubleCheckRenaper` | boolean (opcional) | `true` se dupla verificação RENAPER foi solicitada. | | `responseDoubleChecks` | object (opcional) | Com `doubleCheckRenaper=true`: `renaper` com resultado dados/trâmite. Ver [KYC validations RENAPER](/pt/use-cases/kyc/create-validation#dupla-verificação-renaper-argentina). | 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):** | Campo | Tipo | Descrição | | ------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `providerStatus` | string | Detalhe do estado da verificação do documento (ex.: `Approved`, `Declined`). O `status` de nível superior é `approved` / `declined`. | | `fullName`, `firstName`, `lastName` | string | Nome via OCR. | | `firstSurname`, `secondSurname` | string | Quando vêm em campos complementares (ex.: alguns documentos LATAM). | | `documentNumber`, `personalNumber` | string | Número do documento e número pessoal/nacional se aplicável. | | `documentType` | string | ex.: `Driver's License`, BI. | | `taxNumber` | string | ID fiscal se aplicável (ex.: CUIT/CUIL na Argentina, CPF no Brasil). | | `ejemplar` | string | Letra de exemplar do DNI argentino (`A`–`D`), quando o OCR a devolve. Usado no cruzamento RENAPER se ativo. Com auto-preenchimento KYC (ou sync de campos vazios), também grava em `entityData.person.ejemplar` se esse campo estiver vazio. | | `dateOfBirth`, `age` | string / number | Data de nascimento e idade calculada. | | `expirationDate`, `dateOfIssue`, `firstIssueDate` | string | Datas do documento (ISO `YYYY-MM-DD` quando aplicável). | | `nationality`, `gender` | string | País e género quando o OCR devolve. | | `placeOfBirth`, `maritalStatus` | string | Local de nascimento e estado civil se aplicável. | | `address`, `formattedAddress` | string | Morada quando presente. | | `issuingState`, `issuingStateName` | string | Jurisdição emissora (ex.: `BRA`, `Brazil`). | **Complementares (aninhados; podem estar vazios):** | Campo | Tipo | Descrição | | ------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `extraFields` | object | Chaves do documento **não promovidas** a campos de primeiro nível (ex.: categoria da carta, códigos regionais). Ponto de extensão para campos futuros do OCR. | | `warningMeta` | object | Metadados de avisos: `duplicatedSessionId`, `duplicatedSessionNumber`, `duplicatedApiService` com `POSSIBLE_DUPLICATED_USER`. | | `frontImageQualityScore`, `backImageQualityScore` | object | Pontuações de qualidade OCR quando existem. | | `mrz` | object | Campos MRZ parseados se não vazios. | | `parsedAddress` | object | Morada estruturada quando a verificação a devolve. | | `barcodes` | array | Leituras de códigos de barras se aplicável. | **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](/pt/use-cases/kyc/id-verification-images) (`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):** ```json theme={null} { "status": "approved", "verificationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "requestId": "req_abc", "extractedData": { "providerStatus": "Approved", "fullName": "Elena Martínez Sánchez", "firstName": "Elena", "lastName": "Martínez Sánchez", "documentNumber": "YZA123456", "documentType": "National ID", "dateOfBirth": "1985-03-15", "expirationDate": "2030-08-21", "nationality": "ESP", "address": "Calle Mayor 10, 4B, Madrid", "issuingState": "ESP", "issuingStateName": "Spain", "personalNumber": "AAA123456", "dateOfIssue": "2020-01-10", "gender": "F", "parsedAddress": { "street": "Calle Mayor", "city": "Madrid", "country": "ESP", "formatted_address": "Calle Mayor 10, 4B, Madrid" }, "frontImageQualityScore": { "overall_score": 97.5, "focus_score": 100, "is_document_fully_visible": true }, "backImageQualityScore": { "overall_score": 96.0, "focus_score": 99 } }, "warnings": [] } ``` **Exemplo (recusado com avisos e campos extra LATAM):** ```json theme={null} { "status": "declined", "verificationId": "c3d4e5f6-a7b8-9012-cdef-345678901234", "requestId": "4e2bf9fb-d75b-4b26-9362-e51436cfe1eb", "extractedData": { "providerStatus": "Declined", "fullName": "Breno Henrique Ferreira Silva", "firstName": "Breno Henrique", "lastName": "Ferreira Silva", "firstSurname": "Ferreira", "secondSurname": "Silva", "documentNumber": "08585626509", "personalNumber": "2156732124SSPBA", "documentType": "Driver's License", "taxNumber": "10584158599", "dateOfBirth": "2004-08-29", "age": 21, "expirationDate": "2025-03-07", "dateOfIssue": "2024-03-08", "firstIssueDate": "2024-03-08", "nationality": "BRA", "gender": "U", "placeOfBirth": "Barreiras/Ba", "maritalStatus": "UNKNOWN", "issuingState": "BRA", "issuingStateName": "Brazil", "warningMeta": { "duplicatedSessionId": "a4bfeef8-6d6e-4e9b-8fcb-44950912b2b4", "duplicatedSessionNumber": 2834, "duplicatedApiService": "ID_VERIFICATION" }, "frontImageQualityScore": { "overall_score": 98.2, "focus_score": 100, "brightness_score": 94, "is_document_fully_visible": true }, "formattedAddress": null, "extraFields": { "license_category": "AB", "restrictions": "01" }, "mrz": { "line1": "IDBRA085856265<<<<<<<<<<<<<<<", "line2": "0408299M2503077BRA<<<<<<<<<<<6", "line3": "SILVA< ```javascript Node.js (arquivos) theme={null} const form = new FormData(); form.append('documentFront', documentFrontFile); // File object if (documentBackFile) form.append('documentBack', documentBackFile); form.append('entityId', '123e4567-e89b-12d3-a456-426614174000'); const response = await fetch('https://api.gu1.ai/api/kyc/id-verification', { method: 'POST', headers: { 'Authorization': 'Bearer SUA_API_KEY' }, body: form, }); const result = await response.json(); console.log('Status:', result.status, 'Data:', result.extractedData); ``` ```javascript Node.js (base64 nos campos) theme={null} const form = new FormData(); form.append('documentFront', 'data:image/jpeg;base64,/9j/4AAQ...'); form.append('documentBack', 'data:image/jpeg;base64,/9j/4AAQ...'); form.append('entityId', '123e4567-e89b-12d3-a456-426614174000'); const response = await fetch('https://api.gu1.ai/api/kyc/id-verification', { method: 'POST', headers: { 'Authorization': 'Bearer SUA_API_KEY' }, body: form, }); const result = await response.json(); ``` ```python Python (arquivos) theme={null} import requests with open('frente.jpg', 'rb') as front: files = {'documentFront': ('frente.jpg', front, 'image/jpeg')} data = {'entityId': '123e4567-e89b-12d3-a456-426614174000'} # opcional: files['documentBack'] = ('verso.jpg', open('verso.jpg', 'rb'), 'image/jpeg') response = requests.post( 'https://api.gu1.ai/api/kyc/id-verification', headers={'Authorization': 'Bearer SUA_API_KEY'}, files=files, data=data, ) result = response.json() print('Status:', result['status'], 'Data:', result.get('extractedData')) ``` ```python Python (base64 nos campos) theme={null} import requests import base64 with open('frente.jpg', 'rb') as f: front_b64 = 'data:image/jpeg;base64,' + base64.b64encode(f.read()).decode() response = requests.post( 'https://api.gu1.ai/api/kyc/id-verification', headers={'Authorization': 'Bearer SUA_API_KEY'}, data={ 'documentFront': front_b64, 'entityId': '123e4567-e89b-12d3-a456-426614174000', }, ) result = response.json() ``` ```curl cURL (arquivos) theme={null} curl -X POST https://api.gu1.ai/api/kyc/id-verification \ -H "Authorization: Bearer SUA_API_KEY" \ -F "documentFront=@frente.jpg" \ -F "documentBack=@verso.jpg" \ -F "entityId=123e4567-e89b-12d3-a456-426614174000" ``` ```curl cURL (base64) theme={null} curl -X POST https://api.gu1.ai/api/kyc/id-verification \ -H "Authorization: Bearer SUA_API_KEY" \ -F "documentFront=data:image/jpeg;base64,/9j/4AAQ..." \ -F "documentBack=data:image/jpeg;base64,/9j/4AAQ..." \ -F "entityId=123e4567-e89b-12d3-a456-426614174000" ``` ## Respostas de erro Códigos de erro comuns: | Código | HTTP | Significado | | --------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | | `NOT_CONFIGURED` | 403 | Credenciais do ID Verification (API key) não configuradas na organização. | | `NOT_ENABLED` | 403 | Integração ID Verification não ativada para esta organização. | | `INVALID_REQUEST` | 400 | Content-Type não é multipart/form-data, ou frente do documento faltando/inválida (sem arquivo nem base64, ou formato/tamanho). | | `FORBIDDEN` | 403 | Não foi possível concluir a verificação (ex.: créditos). | | `VERIFICATION_FAILED` | 500 | Não foi possível concluir a verificação; tentar novamente ou outro documento. | ## 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 ``` GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id ``` 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 ``` GET https://api.gu1.ai/api/kyc/id-verification/verifications?entityId={entityId}&limit=50&offset=0 ``` **Parâmetros de query:** | Parâmetro | Tipo | Descrição | | --------------- | ------------- | --------------------------------------------------------------------------------------------------------------- | | `entityId` | string (UUID) | Opcional. Filtrar por entidade pessoa. | | `withoutEntity` | boolean | Se `true`, retorna apenas verificações sem entidade associada (ex.: aba «ID Verification sem entidade» no KYC). | | `status` | string | Opcional. Filtrar por status (`approved`, `declined`, `failed`). | | `limit` | number | Máximo de itens (padrão 50, máx. 100). | | `offset` | number | Deslocamento da paginação. | **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: ``` GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id/document-front-image GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id/document-back-image ``` **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 Comparar documento e selfie Verificação por sessão com URL hospedada