Criar Validação KYC
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
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):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)
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
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)
- 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.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)
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
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:
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:
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"):
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 emmetadata.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 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