Skip to main content
POST
http://api.gu1.ai
/
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>"
}
'
{
  "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

Entendendo a sequência completa desde a criação da entidade até a validação KYC:
1. ID da Entidade do POST /entities
  • Sim, o entityId vem da criação de uma entidade pessoa primeiro via POST /api/entities
  • Você não pode criar uma validação KYC sem uma entidade existente
  • Armazene o entityId após a criação da entidade para usar na requisição de validação KYC
2. Código de Integração
  • global_gueno_validation_kyc é o código padrão para verificação KYC completa
  • Este código deve corresponder a uma integração configurada para sua organização
  • No sandbox, este código funciona imediatamente sem configuração
3. URL de Verificação
  • O providerSessionUrl na resposta é o que você envia ao seu usuário
  • Esta URL normalmente é válida por 30 dias (verifique o campo expiresAt)
  • Os usuários completam todo o fluxo de verificação na página hospedada do provedor
4. Webhook vs Polling
  • Webhooks fornecem notificação instantânea quando a verificação é concluída
  • Você também pode fazer polling GET /api/kyc/validations/:id para atualizações de status
  • Melhor prática: Use webhooks + polling como fallback

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

​
Comportamentos Importantes

​
Tratamento de Entidades Duplicadas

O que acontece se você chamar POST /entities várias vezes com o mesmo taxId?A API criará entidades duplicadas com UUIDs diferentes. Isso é por design para suportar casos de uso como:
  • Manutenção de registros históricos
  • Múltiplas tentativas de verificação
  • Diferentes contextos de entidade (ex: mesma pessoa em papéis diferentes)
Melhor Prática para Evitar Duplicatas:
  1. Verifique se a entidade existe primeiro: Use GET /api/entities?taxId=12345678 antes de criar
  2. Armazene entityId em seu banco de dados: Mapeie seu ID de usuário para o entityId da gu1
  3. Use entityId existente: Reutilize a mesma entidade para múltiplas validações KYC
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' }
});

let entityId;
if (existing.data && existing.data.length > 0) {
  entityId = existing.data[0].id; // Usar entidade existente
} else {
  // Criar nova entidade
  const newEntity = 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' })
  });
  entityId = newEntity.data.id;
}

// Agora 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 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.

​
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,
  "createdAt": "2025-01-15T10:30:00Z"
}

​
Campos de Resposta

​
providerSessionUrl
string
A URL de verificação para compartilhar com seu cliente
​
status
string
Status atual: pending, in_progress, approved, rejected, expired, abandoned

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

​
Próximos Passos

Obter URL de KYC

Aprenda como recuperar a URL

Integração Webhook

Configure notificações webhook