Pular para o conteúdo principal
Version: 1.6.0

API de KYC

Abra dossiês de KYC (conhecimento do cliente) a partir de um CPF ou CNPJ, acompanhe o processamento e leia o resultado, por HTTP e JSON.

Como funciona​

  1. Crie um dossiê com POST /kyc/v1/dossiers. A consulta aos birôs é assíncrona: a resposta é 202 com o dossiê em processing.
  2. Consulte o resultado com GET /kyc/v1/dossiers/{dossier_id} até o status deixar de ser processing. O evento onboarding.kyc.completed, por webhook, também avisa quando o processamento termina; use a consulta como conferência.
  3. Liste os dossiês do workspace com GET /kyc/v1/dossiers, ou veja se já existe um KYC válido para um documento com POST /kyc/v1/current-dossier/lookup.

Cada consulta gera um dossiê com id próprio: consultar o mesmo documento de novo gera outro dossiê.

Autenticação​

Todas as rotas, exceto a de saúde do serviço, exigem o header x-api-key. Você mesmo gera a chave, na tela de Chaves de API do workspace; o valor completo aparece uma única vez, na criação. Revogar uma chave pode levar até 300 segundos para valer.

Restrição por IP de origem (opcional)​

Cada chave pode ter uma lista de IPs ou faixas (CIDR) de origem permitidos. Sem lista, a chave vale de qualquer origem; com lista, requisições vindas de fora dela recebem 403 ip_not_allowed. Configure a lista na tela de Chaves de API, ao gerar a chave ou depois.

  • As alterações valem em até 5 minutos.
  • A Zabit considera o IP de origem visto pelo balanceador. Um X-Forwarded-For enviado por você é ignorado.
  • A verificação vem antes de qualquer outra regra: com a origem não autorizada, a resposta é sempre 403, mesmo que o corpo da requisição esteja inválido.

Cota e limites​

Criar um dossiê dispara uma consulta paga, então é limitado:

  • cada chave tem um teto diário de criações (volta a valer no dia seguinte, em UTC). Chave sem teto configurado não cria dossiê (403 quota_not_configured);
  • o workspace também tem limites de criação, diário e mensal, que somam todos os canais (429 kyc_creation_limit_reached);
  • o plano de API do workspace define quais rotas estão disponíveis (403 route_not_in_plan).

Consultar, listar e checar o KYC vigente não consomem cota.

Repetir um pedido com segurança​

Em POST /kyc/v1/dossiers, o header opcional Idempotency-Key evita abrir dois dossiês quando você precisa repetir um pedido. Veja os detalhes na operação Criar dossiê.

Erros​

Os erros seguem o formato {"error": {"code": "...", "message": "..."}}. Use code para decidir o que fazer; message é para leitura humana e pode mudar.

Authentication​

Chave de API do workspace, enviada no header x-api-key. Você gera a chave na tela de Chaves de API; o valor completo aparece uma única vez, na criação. Se perder o valor, gere outra chave. Cada chave tem permissões próprias e um teto diário de criações de dossiê. Revogar uma chave pode levar até 300 segundos para valer.

Security Scheme Type:

apiKey

Header parameter name:

x-api-key