Skip to main content
POST
Criar Validação KYC

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:

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_progress ou in_review), o create retorna 409 VALIDATION_IN_PROGRESS com activeValidationId — 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

Headers

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

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

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

Respostas de erro

Entidade não encontrada (404)

Tipo de entidade inválido (400)

KYC não configurado (400)

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:
Recuperação: 409DELETE /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)

Com doubleCheckRenaper: 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=true com o mesmo body. Se ambos forem enviados, o query prevalece.

Onde o resultado é armazenado

Em metadata.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:

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"):
Outros casos comuns: No sandbox, os mesmos valores mock aparecem em Dados mock de KYC (sandbox).

Forma de comparisonResults

Mapa por campo (dni, tramite, name, ejemplar, dateOfBirth, expirationDate). Cada entrada pode incluir: Para 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):

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.

Exemplo completo de responseDoubleChecks.renaper

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 em metadata.warnings e em metadata.responseDoubleChecks.renaper.errorCode. A UI deve traduzir esses códigos.

Quando o RENAPER aplica enforce (rejeição automática)

Em todos os casos com consulta ativa, dados e biometria ficam em 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 em decision 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