Skip to main content
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>",
  "integrationCode": "<string>",
  "doubleCheckRenaper": true
}
'
{
  "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):
1. Entidade e taxId duplicado
  • Crie primeiro a entidade pessoa com POST /api/entities (inclua countryCode). Se o taxId já existir na organização, a API retorna 409 e não cria duplicado; use o ID da entidade existente.
  • Você precisa de um entityId existente para criar uma validação KYC.
2. Código de integração
  • global_gueno_validation_kyc é o código padrão para KYC completo e funciona no sandbox sem configuração adicional.
3. URL de verificação
  • 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 pending e momentos depois atualiza a validação e envia os webhooks (ex.: kyc.validation_approved ou kyc.validation_rejected), sem passo do usuário. Importante: Você deve ter um endpoint webhook configurado para receber as respostas - veja Dados mock no sandbox.
4. Eventos de webhook
  • 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/:id para atualizações de status.

​
Pré-requisitos

Antes de criar uma validação KYC:
  1. A entidade pessoa deve existir: Crie uma entidade pessoa usando a API de Entidades
  2. Integração KYC configurada: Sua organização deve ter um provedor de integração KYC ativado (ex: global_gueno_validation_kyc)
  3. 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
Para começar no sandbox, simplesmente use sua chave de API do sandbox - nenhuma configuração adicional é necessária.

​
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:
  1. 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 seu entityId para KYC.
  2. Opção B – Tratar o 409: Se receber 409, leia error.details.existingEntityId na resposta e use esse entityId para sua validação KYC.
  3. Reutilizar a mesma entidade: Use uma entidade por pessoa/empresa e crie várias validações KYC sobre esse mesmo entityId se precisar de re-verificação ou novas tentativas.
Exemplo – Verificar antes de criar:
// 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

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

​
doubleCheckRenaper
boolean
Em true, ativa a dupla verificação RENAPER para entidades da Argentina. Após aprovação do provedor KYC, a API valida o documento no registro oficial (RENAPER). Se falhar, a validação fica rejected e o motivo é armazenado como código em metadata.warnings e em metadata.responseDoubleChecks.renaper.errorCode. Requer entidade da Argentina e credenciais RENAPER configuradas na organização.

​
Parâmetros do Body

​
entityId
string
required
O UUID da entidade pessoa a verificarTipo: string (uuid)
​
integrationCode
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)
Como encontrar seu código de integração:
  1. Faça login no Dashboard gu1
  2. Navegue até Configurações → Integrações → Provedores KYC
  3. Seu código de integração ativo será listado lá
Em ambientes sandbox, global_gueno_validation_kyc funciona imediatamente sem configuração.
​
doubleCheckRenaper
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.

​
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"
}
Com dupla verificação RENAPER ativa, em criação é definido 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

​
providerSessionUrl
string
A URL de verificação para compartilhar com seu cliente
​
status
string
Status atual da validação. Valores possíveis:
  • pending - Validação criada, aguardando o cliente iniciar
  • in_progress - Cliente completando a verificação (preenchendo formulário)
  • in_review - Verificação completa, requer revisão manual da equipe de compliance
  • approved - Verificação bem-sucedida
  • rejected - Verificação falhou
  • expired - Sessão de verificação expirada (ex. após 7 dias)
  • abandoned - Cliente iniciou mas não completou
  • cancelled - Validação cancelada manualmente

​
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);

​
Dupla verificação RENAPER (Argentina)

Com doubleCheckRenaper: true e entidade da Argentina, após aprovação do provedor KYC a API executa uma verificação cruzada contra o registro oficial (RENAPER). Se falhar, a validação fica rejected e o motivo é armazenado em metadata.

​
Como enviar

  • Body: { "entityId": "...", "integrationCode": "...", "doubleCheckRenaper": true }
  • Query: POST /api/kyc/validations?doubleCheckRenaper=true com o mesmo body. Se ambos forem enviados, o query prevalece.

​
Onde o resultado é armazenado

Em metadata.responseDoubleChecks.renaper. Em caso de falha, um código também é adicionado a metadata.warnings. Campos de metadata.responseDoubleChecks.renaper:
CampoTipoDescrição
verifiedbooleantrue se o chequeo passou.
matchResultstring"match" | "mismatch" | "error".
verifiedAtstringTimestamp ISO do chequeo.
personalNumberstringNúmero de trâmite do KYC.
idTramitePrincipalstringNúmero de trâmite do RENAPER.
renaperDataobjectResposta bruta do RENAPER.
errorCodestringPresente se falhou; ver códigos abaixo.

​
Códigos de erro (quando RENAPER falha)

O motivo da rejeição é um código em metadata.warnings e em metadata.responseDoubleChecks.renaper.errorCode. A UI deve traduzir esses códigos.
CódigoSignificado
RENAPER_DNI_MISSINGNúmero de documento (DNI) não obtido na verificação.
RENAPER_GENDER_MISSINGGénero (M/F) obrigatório para chamar RENAPER.
RENAPER_VERIFICATION_UNAVAILABLENão foi possível completar a verificação cruzada (ex.: rede). Tente novamente.
RENAPER_DNI_NOT_MATCHO número do documento não coincide com o registro oficial.
RENAPER_TRAMITE_DATA_MISSINGFaltam dados para comparar o número de trâmite.
RENAPER_TRAMITE_ID_NOT_MATCHO 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).

​
Próximos Passos

Obter URL de KYC

Aprenda como recuperar a URL

Integração Webhook

Configure notificações webhook