Criar Validação KYC
curl --request POST \
--url http://api.gu1.ai/api/kyc/validations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityId": "<string>",
"entityExternalId": "<string>",
"entityTaxId": "<string>",
"integrationCode": "<string>",
"language": "<string>",
"doubleCheckRenaper": true,
"omitWarnings": [
"<string>"
]
}
'import requests
url = "http://api.gu1.ai/api/kyc/validations"
payload = {
"entityId": "<string>",
"entityExternalId": "<string>",
"entityTaxId": "<string>",
"integrationCode": "<string>",
"language": "<string>",
"doubleCheckRenaper": True,
"omitWarnings": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
entityId: '<string>',
entityExternalId: '<string>',
entityTaxId: '<string>',
integrationCode: '<string>',
language: '<string>',
doubleCheckRenaper: true,
omitWarnings: ['<string>']
})
};
fetch('http://api.gu1.ai/api/kyc/validations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/validations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entityId' => '<string>',
'entityExternalId' => '<string>',
'entityTaxId' => '<string>',
'integrationCode' => '<string>',
'language' => '<string>',
'doubleCheckRenaper' => true,
'omitWarnings' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/validations"
payload := strings.NewReader("{\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"entityTaxId\": \"<string>\",\n \"integrationCode\": \"<string>\",\n \"language\": \"<string>\",\n \"doubleCheckRenaper\": true,\n \"omitWarnings\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/validations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"entityTaxId\": \"<string>\",\n \"integrationCode\": \"<string>\",\n \"language\": \"<string>\",\n \"doubleCheckRenaper\": true,\n \"omitWarnings\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/validations")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"entityTaxId\": \"<string>\",\n \"integrationCode\": \"<string>\",\n \"language\": \"<string>\",\n \"doubleCheckRenaper\": true,\n \"omitWarnings\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"providerSessionUrl": "<string>",
"status": "<string>"
}Validação por sessão
Criar Validação KYC
Iniciar uma sessão de verificação KYC para uma entidade pessoa — na API KYC da gu1 para fluxos de verificação de identidade, com exemplos para create.
POST
/
api
/
kyc
/
validations
Criar Validação KYC
curl --request POST \
--url http://api.gu1.ai/api/kyc/validations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityId": "<string>",
"entityExternalId": "<string>",
"entityTaxId": "<string>",
"integrationCode": "<string>",
"language": "<string>",
"doubleCheckRenaper": true,
"omitWarnings": [
"<string>"
]
}
'import requests
url = "http://api.gu1.ai/api/kyc/validations"
payload = {
"entityId": "<string>",
"entityExternalId": "<string>",
"entityTaxId": "<string>",
"integrationCode": "<string>",
"language": "<string>",
"doubleCheckRenaper": True,
"omitWarnings": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
entityId: '<string>',
entityExternalId: '<string>',
entityTaxId: '<string>',
integrationCode: '<string>',
language: '<string>',
doubleCheckRenaper: true,
omitWarnings: ['<string>']
})
};
fetch('http://api.gu1.ai/api/kyc/validations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/validations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entityId' => '<string>',
'entityExternalId' => '<string>',
'entityTaxId' => '<string>',
'integrationCode' => '<string>',
'language' => '<string>',
'doubleCheckRenaper' => true,
'omitWarnings' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/validations"
payload := strings.NewReader("{\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"entityTaxId\": \"<string>\",\n \"integrationCode\": \"<string>\",\n \"language\": \"<string>\",\n \"doubleCheckRenaper\": true,\n \"omitWarnings\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/validations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"entityTaxId\": \"<string>\",\n \"integrationCode\": \"<string>\",\n \"language\": \"<string>\",\n \"doubleCheckRenaper\": true,\n \"omitWarnings\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/validations")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"entityTaxId\": \"<string>\",\n \"integrationCode\": \"<string>\",\n \"language\": \"<string>\",\n \"doubleCheckRenaper\": true,\n \"omitWarnings\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"providerSessionUrl": "<string>",
"status": "<string>"
}Resumo
Este endpoint cria uma nova sessão de validação KYC para uma entidade pessoa usando um provedor de integração configurado. Após criar a validação, você receberá uma URL de verificação que pode compartilhar com seu cliente para completar a verificação de identidade.Diagrama de Fluxo Completo
Sequência desde a criação da entidade até a validação KYC (fluxo de produção; no sandbox com números de documento de teste o passo do provedor é omitido e a API retorna o resultado mock e os webhooks imediatamente—veja Dados mock no sandbox):Pontos-Chave no Fluxo
Pontos-Chave no Fluxo
1. Entidade e taxId duplicado
- Crie primeiro a entidade pessoa com
POST /api/entities(incluacountryCode). Se otaxIdjá existir na organização, a API retorna 409 e não cria duplicado; use o ID da entidade existente. - Você precisa de um
entityIdexistente para criar uma validação KYC.
global_gueno_validation_kycé o código padrão para KYC completo e funciona no sandbox sem configuração adicional.
- Em produção, a resposta inclui
providerSessionUrl. Envie essa URL ao seu usuário; eles completam o fluxo na página do provedor (documento + selfie). A URL é válida atéexpiresAt. - No sandbox, se o documento da entidade estiver na lista de teste, não há sessão do provedor: a API retorna 201 com status
pendinge momentos depois atualiza a validação e envia os webhooks (ex.:kyc.validation_approvedoukyc.validation_rejected), sem passo do usuário. Importante: Você deve ter um endpoint webhook configurado para receber as respostas - veja Dados mock no sandbox.
- Quando a validação termina, a API envia um webhook à sua URL. O evento é um de:
kyc.validation_approved,kyc.validation_rejected,kyc.validation_abandoned,kyc.validation_expired,kyc.validation_cancelled(não um único evento “completed”). O payload é o objeto de validação completo. - Você também pode fazer polling em
GET /api/kyc/validations/:idpara atualizações de status.
Pré-requisitos
Antes de criar uma validação KYC:- A entidade pessoa deve existir: Crie uma entidade pessoa usando a API de Entidades
- Integração KYC configurada: Sua organização deve ter um provedor de integração KYC ativado (ex:
global_gueno_validation_kyc) - API key válida: Autentique com sua chave API
Sandbox vs Produção: Ambientes sandbox NÃO requerem configuração de perfil ou pré-configuração. Você pode testar validações KYC imediatamente no sandbox com dados de teste. Ambientes de produção requerem:
- Onboarding da organização concluído
- Provedor de integração KYC ativado pela equipe gu1
- Saldo de créditos suficiente para operações KYC
Dados mock (sandbox)
No sandbox, quando o documento da entidade pessoa (taxId) coincide com um dos nossos valores de teste, a API retorna um resultado mock imediato (ex.: aprovado, rejeitado, cancelado) e envia os webhooks correspondentes, sem executar verificação real. O formato do documento não importa (ex.: 99.990.001 e 99990001 funcionam igual).
Para a lista completa de números de documento de teste por formato (Argentina DNI/CUIT, Brasil CPF/CNPJ), resultados esperados e exemplos de resposta, veja Dados mock no sandbox.
Comportamentos Importantes
taxId duplicado (POST /entities)
O que acontece se você chamar POST /entities com um taxId que já existe?A API não cria uma segunda entidade. Retorna 409 Conflict com código de erro
DUPLICATE_TAX_ID e inclui nos detalhes o id, name e type da entidade existente.O que fazer:- Opção A – Consultar antes: Use
GET /api/entities?taxId=12345678(ou o endpoint by-tax-id) antes de criar. Se a entidade existir, use seuentityIdpara KYC. - Opção B – Tratar o 409: Se receber 409, leia
error.details.existingEntityIdna resposta e use esseentityIdpara sua validação KYC. - Reutilizar a mesma entidade: Use uma entidade por pessoa/empresa e crie várias validações KYC sobre esse mesmo
entityIdse precisar de re-verificação ou novas tentativas.
// Verificar se a entidade existe
const existing = await fetch('https://api.gu1.ai/api/entities?taxId=12345678', {
headers: { 'Authorization': 'Bearer SUA_API_KEY' }
});
const data = await existing.json();
let entityId;
if (data.data && data.data.length > 0) {
entityId = data.data[0].id; // Usar entidade existente
} else {
const createRes = await fetch('https://api.gu1.ai/api/entities', {
method: 'POST',
headers: { 'Authorization': 'Bearer SUA_API_KEY', 'Content-Type': 'application/json' },
body: JSON.stringify({ type: 'person', taxId: '12345678', name: 'João Silva', countryCode: 'AR' })
});
const created = await createRes.json();
entityId = created.entity?.id ?? created.data?.id;
}
// Criar validação KYC com o entityId
Múltiplas Validações KYC por Entidade
Você pode criar múltiplas validações KYC para a mesma entidade:- Cada validação recebe um ID e sessão únicos
- Apenas a validação aprovada mais recente é marcada como
isCurrent: true - Casos de uso: Re-verificação, validações expiradas, tentativas falhadas
- Se a entidade já tiver uma validação aberta (
pending,in_progressouin_review), o create retorna409 VALIDATION_IN_PROGRESScomactiveValidationId— cancele essa validação primeiro e só então crie de novo
Contrato aditivo: Clientes que leem apenas
error e message não mudam. activeValidationId é metadata opcional no 409 para evitar lookup extra antes do cancel.Solicitação
Endpoint
POST https://api.gu1.ai/api/kyc/validations
Headers
{
"Authorization": "Bearer SUA_API_KEY",
"Content-Type": "application/json"
}
Parâmetros de Query (opcionais)
boolean
Em
true, ativa a dupla verificação RENAPER para entidades da Argentina. Em estados terminais a API consulta o registro oficial (dados e, quando aplicável, biometria) e armazena o resultado em metadata. Somente se a verificação OCR KYC retornar o estado approved uma falha no cruzamento pode rejeitar automaticamente a validação; em in_review ou rejected o chequeo é informativo (enforcementApplied: false). Requer entidade da Argentina e credenciais RENAPER configuradas na organização.Parâmetros do Body
Informe exatamente um identificador de entidade:string
O UUID da entidade pessoa a verificarTipo:
string (uuid)string
Seu ID externo da entidade (
entities.externalId na Gu1).string
Documento fiscal (CUIT, CPF, DNI, etc.). A Gu1 resolve com match normalizado em
entities.tax_id. A entidade deve existir (404 se não houver linha).No sandbox,
GET /api/entities/by-tax-id/{taxId} pode retornar prévia sintética para números de teste do catálogo (sandboxMock: true) sem linha no DB. POST /validations ainda exige entidade real persistida.string
required
O código do provedor de integração para validação KYCValor Padrão:
global_gueno_validation_kyc (recomendado para a maioria dos casos de uso)Tipo: string (comprimento mínimo: 1)O que é integrationCode?O
integrationCode identifica qual integração de provedor KYC usar para verificação. Pense nisso como selecionar o serviço de verificação.Códigos de Integração Disponíveis:global_gueno_validation_kyc- Recomendado - KYC completo com documento + selfie + comparação facial + liveness- Códigos personalizados podem ser configurados para sua organização (contate o suporte)
- Faça login no Dashboard gu1
- Navegue até Configurações → Integrações → Provedores KYC
- Seu código de integração ativo será listado lá
global_gueno_validation_kyc funciona imediatamente sem configuração.string
Idioma opcional da interface hospedada de verificação, por exemplo
es, en ou pt.
O valor do request prevalece sobre o idioma KYC padrão da organização.
Se nenhum estiver configurado, a interface detecta o idioma pelo dispositivo do usuário final.boolean
Igual ao query param. Em
true ativa a dupla verificação RENAPER para Argentina. Pode ser enviado no body ou como ?doubleCheckRenaper=true. Se ambos forem enviados, o query prevalece.string[]
Lista opcional de códigos de aviso KYC (strings exatos). Fica armazenada na validação como
metadata.omitWarnings. Ao concluir a sessão, se a validação ficaria em in_review, warnings não está vazio e todos os códigos em warnings aparecem nesta lista, a API define o status como approved e mantém os avisos para UI e auditoria. Se algum aviso não estiver em omitWarnings, o status permanece in_review. Se warnings estiver vazio com status in_review, não há autoaprovação. Códigos inválidos no body retornam 400. Quando a regra se aplica, metadata.kycOmitWarningsApplied registra o instante e os avisos correspondentes.Códigos não omitíveis (ex.: GUENO_CROSS_ENTITY_DUPLICATED) são rejeitados neste campo com 400 e sempre impedem autoaprovação por omit mesmo que constem em warnings.Tipo: string[] (cada elemento deve ser um código permitido; duplicados são ignorados)Resposta
Resposta Bem-sucedida (201 Created)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"entityId": "123e4567-e89b-12d3-a456-426614174000",
"organizationId": "org_abc123",
"sessionId": "session_xyz789",
"status": "pending",
"provider": "kyc_provider",
"providerSessionUrl": "https://verify.example.com/session_xyz789",
"isCurrent": true,
"metadata": { "doubleChecks": { "renaper": true } },
"createdAt": "2025-01-15T10:30:00Z"
}
metadata.doubleChecks.renaper: true. Após aprovação e execução do chequeo, é preenchido metadata.responseDoubleChecks.renaper (ver Dupla verificação RENAPER).
Campos de Resposta
string
A URL de verificação para compartilhar com seu cliente
string
Status atual da validação. Valores possíveis:
pending- Validação criada, aguardando o cliente iniciarin_progress- Cliente completando a verificação (preenchendo formulário)in_review- Verificação completa, requer revisão manual da equipe de complianceapproved- Verificação bem-sucedidarejected- Verificação falhouexpired- Sessão de verificação expirada (ex. após 7 dias)abandoned- Cliente iniciou mas não completoucancelled- Validação cancelada manualmente
Após a aprovação, as chaves de mídia aparecem em
decision. Para baixar arquivos (imagens, vídeo), use GET /api/kyc/validations/:id/media?key=... com Authorization: Bearer. Detalhes: Obter mídia da validação KYC.Exemplo de Solicitação
const response = await fetch('https://api.gu1.ai/api/kyc/validations', {
method: 'POST',
headers: {
'Authorization': 'Bearer SUA_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
entityId: '123e4567-e89b-12d3-a456-426614174000',
integrationCode: 'global_gueno_validation_kyc'
})
});
const validation = await response.json();
console.log('URL de verificação:', validation.providerSessionUrl);
import requests
response = requests.post(
'https://api.gu1.ai/api/kyc/validations',
headers={
'Authorization': 'Bearer SUA_API_KEY',
'Content-Type': 'application/json',
},
json={
'entityId': '123e4567-e89b-12d3-a456-426614174000',
'integrationCode': 'global_gueno_validation_kyc'
}
)
validation = response.json()
print('URL de verificação:', validation['providerSessionUrl'])
Respostas de erro
Entidade não encontrada (404)
{
"error": "ENTITY_NOT_FOUND",
"message": "Entity not found"
}
Tipo de entidade inválido (400)
{
"error": "INVALID_ENTITY_TYPE",
"message": "KYC validation is only available for person entities"
}
KYC não configurado (400)
{
"error": "KYC_NOT_CONFIGURED",
"message": "KYC integration is not configured for this organization. Please contact your administrator."
}
Validação em andamento (409)
Quando a entidade já tem uma validação aberta (pending, in_progress ou in_review), a Gu1 sincroniza com a sessão de captura hospedada quando possível e rejeita um segundo create:
{
"error": "VALIDATION_IN_PROGRESS",
"message": "Cannot create new KYC validation. There is already a pending validation for this entity. Please cancel or complete the existing validation first.",
"activeValidationId": "7618e10c-b1b1-408b-b361-1901077ced73"
}
409 → DELETE /api/kyc/validations/{activeValidationId}/cancel → um único POST /api/kyc/validations novo.
Validações terminais (approved, rejected, cancelled, expired, abandoned) não bloqueiam criar outra.
Dupla verificação RENAPER (Argentina)
ComdoubleCheckRenaper: true e entidade da Argentina, em cada estado terminal (approved, rejected, in_review) a API executa verificação cruzada contra o registro oficial (RENAPER) quando há OCR suficiente. Rejeição automática por RENAPER somente se a verificação OCR KYC retornou o estado approved.
Como enviar
- Body:
{ "entityId": "...", "integrationCode": "...", "doubleCheckRenaper": true } - Query:
POST /api/kyc/validations?doubleCheckRenaper=truecom o mesmo body. Se ambos forem enviados, o query prevalece.
Onde o resultado é armazenado
Emmetadata.responseDoubleChecks.renaper. Códigos de mismatch (ex.: trâmite e vencimento) são adicionados a metadata.warnings sem substituir avisos anteriores da verificação OCR KYC. errorCode no objeto renaper mantém a primeira falha por compatibilidade; a UI pode listar todos os códigos em comparisonResults e warnings.
Campos de metadata.responseDoubleChecks.renaper:
| Campo | Tipo | Descrição |
|---|---|---|
verified | boolean | true se o chequeo passou. |
matchResult | string | "match" | "mismatch" | "error". |
verifiedAt | string | Timestamp ISO do chequeo. |
personalNumber | string | Número de trâmite do KYC. |
idTramitePrincipal | string | Número de trâmite do RENAPER. |
renaperData | object | Resposta bruta do RENAPER (ver forma de renaperData). |
comparisonResults | object | Comparação campo a campo entre OCR e registro (quando aplicável). |
renaperBiometric | object | Resultado biométrico ABIS (validate-dni): matchResult, score, renaperData (resposta bruta). |
errorCode | string | Presente se falhou; ver códigos abaixo. |
Forma de renaperData
É o body sem transformação retornado pelo registro via ms-providers (POST …/provider-records/renaper/data). A Gu1 repassa como está em metadata.responseDoubleChecks.renaper.renaperData. Os nomes dos campos estão em snake_case; todos são opcionais conforme o retorno do RENAPER em cada consulta.
Exemplo (dupla verificação bem-sucedida, matchResult: "match"):
{
"id_tramite_principal": "987654321",
"id_tramite_tarjeta_reimpresa": "112233445",
"ejemplar": "A",
"vencimiento": "2030-05-20",
"emision": "2015-05-20",
"apellido": "García",
"nombres": "Juan",
"fecha_nacimiento": "1990-01-15",
"cuil": "20-30123456-9",
"calle": "Av. Corrientes",
"numero": "1234",
"piso": "5",
"departamento": "B",
"codigo_postal": "1043",
"barrio": "San Nicolás",
"monoblock": "",
"ciudad": "Ciudad Autónoma de Buenos Aires",
"municipio": "Comuna 1",
"provincia": "Buenos Aires",
"pais": "Argentina",
"nacionalidad": "Argentina",
"codigo_fallecido": "",
"mensaje_fallecido": "",
"fecha_fallecimiento": "",
"id_ciudadano": "30123456",
"codigo": "",
"mensaje": ""
}
| Situação | renaperData típico |
|---|---|
Erro antes de obter dados (ex.: RENAPER_DNI_MISSING) | {} |
Serviço indisponível (RENAPER_VERIFICATION_UNAVAILABLE) | { "error": "…", "code": "SERVICE_UNAVAILABLE" } |
| Cruzamento falhou com payload parcial do registro | Subconjunto de campos (ex.: id_tramite_principal, apellido, nombres, fecha_nacimiento) |
Forma de comparisonResults
Mapa por campo (dni, tramite, name, ejemplar, dateOfBirth, expirationDate). Cada entrada pode incluir:
| Campo | Tipo | Descrição |
|---|---|---|
compared | boolean | true se a comparação foi tentada; false se omitida por dados faltantes. |
passed | boolean | Resultado quando compared é true. |
skipReason | string | ocr_missing, renaper_missing ou both_missing quando não comparado. |
ocrValue | string | Valor extraído do OCR (se aplicável). |
renaperValue | string | Valor do registro RENAPER (se aplicável). |
similarityPercent | number | Apenas em name: similaridade Levenshtein (0–100). |
threshold | number | Apenas em name: limiar aplicado (ex.: 80). |
errorCode | string | Código de falha do campo (ex.: RENAPER_DNI_NOT_MATCH). |
ejemplar, o valor OCR é extractedData.ejemplar (ver campos de extractedData). A comparação ocorre quando existem ambos os valores OCR e RENAPER.
Exemplo — extractedData numa validação KYC aprovada (Argentina):
"extractedData": {
"documentNumber": "38966181",
"personalNumber": "00460759387",
"taxNumber": "20389661814",
"ejemplar": "C",
"dateOfBirth": "1995-05-22",
"expirationDate": "2031-10-17",
"nationality": "ARG"
}
Forma de renaperBiometric
Objeto aninhado em metadata.responseDoubleChecks.renaper.renaperBiometric quando a org tem credenciais biométricas e a sessão KYC fornece selfie. O Gu1 envia uma selfie a validate-dni; o RENAPER compara com a foto do documento no registro.
| Campo | Tipo | Descrição |
|---|---|---|
verified | boolean | true quando resultado.match do chequeo biométrico ABIS é positivo. |
matchResult | string | "match" | "mismatch" | "error". |
score | number | Pontuação do chequeo biométrico (se aplicável). |
verifiedAt | string | Timestamp ISO do chequeo biométrico. |
renaperData | object | Resposta bruta de validate-dni (inclui resultado.match, resultado.score, etc.). |
submittedSelfieRef | string | Referência da selfie enviada: caminho de armazenamento (kyc/...) ou URL (https://...). |
submittedSelfieRefKind | string | Formato de submittedSelfieRef: s3_key (caminho interno) | url (URL pública). |
submittedSelfiePickedFrom | string | Origem em decision: liveness_reference_image ou face_match_target_image. |
errorCode | string | Se falhar (ex.: RENAPER_BIOMETRIC_NOT_MATCH). |
skipReason | string | Se não executado (ex.: selfie indisponível). |
Exemplo completo de responseDoubleChecks.renaper
{
"verified": true,
"matchResult": "match",
"personalNumber": "00123456789",
"idTramitePrincipal": "987654321",
"verifiedAt": "2026-06-05T14:30:00.000Z",
"enforcementApplied": true,
"renaperData": {
"id_tramite_principal": "987654321",
"apellido": "García",
"nombres": "Juan",
"fecha_nacimiento": "1990-01-15",
"ejemplar": "A",
"vencimiento": "2030-05-20"
},
"comparisonResults": {
"dni": {
"field": "dni",
"compared": true,
"passed": true,
"ocrValue": "30123456",
"renaperValue": "30123456"
},
"tramite": {
"field": "tramite",
"compared": true,
"passed": true,
"ocrValue": "00123456789",
"renaperValue": "987654321"
},
"name": {
"field": "name",
"compared": true,
"passed": true,
"ocrValue": "Juan García",
"renaperValue": "García Juan",
"similarityPercent": 92,
"threshold": 80
},
"ejemplar": {
"field": "ejemplar",
"compared": true,
"passed": true,
"ocrValue": "A",
"renaperValue": "A"
},
"dateOfBirth": {
"field": "dateOfBirth",
"compared": true,
"passed": true,
"ocrValue": "1990-01-15",
"renaperValue": "1990-01-15"
}
},
"renaperBiometric": {
"verified": true,
"matchResult": "match",
"score": 0.91,
"verifiedAt": "2026-06-05T14:30:02.000Z",
"submittedSelfieRef": "kyc/org-id/entity-id/session-id/selfie.jpg",
"submittedSelfieRefKind": "s3_key",
"submittedSelfiePickedFrom": "liveness_reference_image",
"renaperData": {
"resultado": {
"match": true,
"score": 0.91
}
}
}
}
renaperBiometric e entradas em comparisonResults podem ser omitidos conforme credenciais, dados OCR ou disponibilidade de selfie.
Códigos de erro (quando RENAPER falha)
O motivo da rejeição é um código emmetadata.warnings e em metadata.responseDoubleChecks.renaper.errorCode. A UI deve traduzir esses códigos.
| Código | Significado |
|---|---|
RENAPER_DNI_MISSING | Número de documento (DNI) não obtido na verificação. |
RENAPER_GENDER_MISSING | Género (M/F) obrigatório para chamar RENAPER. |
RENAPER_VERIFICATION_UNAVAILABLE | Não foi possível completar a verificação cruzada (ex.: rede). Tente novamente. |
RENAPER_DNI_NOT_MATCH | O número do documento não coincide com o registro oficial. |
RENAPER_TRAMITE_DATA_MISSING | Faltam dados para comparar o número de trâmite. |
RENAPER_TRAMITE_ID_NOT_MATCH | O número de trâmite do documento não coincide com o registro (exemplar antigo, vencido ou reemitido; a pessoa deve verificar novamente com documento vigente). |
RENAPER_NAME_NOT_MATCH | O nome do OCR está abaixo do limiar de 80% de similaridade com o registro RENAPER. |
RENAPER_EJEMPLAR_NOT_MATCH | O exemplar do documento não coincide com o registro RENAPER. |
RENAPER_DOB_NOT_MATCH | A data de nascimento do OCR não coincide com o registro RENAPER. |
RENAPER_EXPIRY_NOT_MATCH | A data de vencimento do OCR não coincide com o registro RENAPER. |
RENAPER_BIOMETRIC_NOT_MATCH | A selfie não coincide com a foto do documento no registro biométrico. |
RENAPER_BIOMETRIC_UNAVAILABLE | Não foi possível completar o chequeo biométrico (rede, credenciais ou serviço). |
Quando o RENAPER aplica enforce (rejeição automática)
| Estado da verificação OCR KYC | RENAPER executa? | Pode rejeitar por RENAPER? |
|---|---|---|
approved (aprovação direta) | Sim | Sim — falha no cruzamento → rejected |
in_review | Sim | Não — informativo; equipe decide na revisão manual |
rejected (verificação OCR ou regras Gu1) | Sim (se houver OCR) | Não — informativo; dados ficam em metadata |
Aprovação manual a partir de in_review (POST …/approve) | Não (reutiliza chequeo salvo) | Não — decisão humana |
metadata.responseDoubleChecks.renaper. Em in_review e rejected, códigos RENAPER com mismatch são adicionados a warnings junto com avisos da verificação OCR.
Próximos Passos
Depois que a validação for approved, leia as chaves emdecision e baixe os arquivos — veja Obter mídia da validação KYC.
Obter URL de KYC
Aprenda como recuperar a URL
Integração Webhook
Configure notificações webhook
Was this page helpful?