Guia de integração KYB: arquitetura e padrões

Este guia complementa o guia de início rápido. Ele aborda a arquitetura, cada decisão de integração e os padrões operacionais que tornam o KYB confiável em produção.

Arquitetura

Autenticação

Todas as requisições exigem o cabeçalho x-api-key com a chave de API da sua aplicação. Consulte Autenticação da API para rotação de chaves, separação de ambientes e escopos.

Criação de sessão

Um único endpoint: POST /v3/session/. O tipo do fluxo de verificação (workflow) determina se a sessão é de KYC ou de KYB, sem necessidade de uma flag “business” explícita. Campos recomendados na criação:

Campo	Finalidade
`workflow_id`	Obrigatório: referencia o seu fluxo de KYB.
`vendor_data`	O seu identificador para a empresa. Vincula a sessão a uma entidade empresarial.
`callback_url`	Opcional: para onde redirecionar o usuário após a conclusão.
`expected_details`	Opcional: `{ company_name, registry_country, registration_number }`. Preenche previamente a busca no registro de empresas: o país de constituição fica pré-selecionado e bloqueado (`registry_country` como `XX`, ou `XX-YY` para registros estaduais, por exemplo `US-CA`), os campos de nome da empresa e número de registro ficam preenchidos e a busca informada é executada automaticamente, combinando os dois identificadores quando ambos estão presentes. Serve apenas para preenchimento prévio: divergências não geram avisos.
`metadata`	JSON opcional anexado à sessão.

Esquema completo: criar sessão.

Entrega do link hospedado

O url da resposta é um link de verificação hospedado. Opções de entrega:

Envie-o por e-mail a partir da sua própria plataforma.
Incorpore-o como link na interface de onboarding.
Abra-o em uma webview dentro do app (iOS / Android / React Native).

Você pode personalizar a experiência hospedada (logotipo, cor, domínio, modelos de e-mail) por meio da Marca própria.

Polling vs. webhooks

Os webhooks são o padrão recomendado. A Didit envia eventos de conclusão via POST para o endpoint cadastrado assim que o processamento termina. O polling é suportado para desenvolvimento ou quando o seu endpoint de webhook está inacessível:

Faça polling em GET /v3/session/{id}/decision/ com backoff exponencial (a cada 10s inicialmente, até 60s).
Interrompa o polling quando status for um dos seguintes: "Approved", "Declined", "In Review".

Fazer polling em alta frequência pode atingir os limites de requisições. Em produção, prefira sempre webhooks.

Tratamento de webhooks

Inscreva-se nos eventos que interessam a você. Os mesmos eventos cobrem KYC e KYB, com session_kind: "business" no payload para identificar eventos de sessões empresariais:

status.updated: o status da sessão mudou. Filtre por session_kind === "business" para sessões de KYB.
data.updated: um revisor editou dados do registro de empresas ou as pessoas-chave no console, ou o registro de empresas informou uma alteração. Esse evento não é enviado quando o solicitante faz upload de um documento ou envia as Pessoas-chave: para isso, acompanhe status.updated. O mesmo filtro de session_kind se aplica.
business.status.updated / business.data.updated: a entidade empresarial vinculada mudou.

Catálogo completo de eventos: webhooks de KYB. Verificação de assinatura e semântica de novas tentativas: referência de webhooks.

Tratamento de decisões

switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}

Consulte status de KYB para a máquina de estados completa e avisos de KYB para as tags que explicam uma decisão.

Fluxo de reenvio

Quando uma sessão de Verificação de empresas (KYB) passa para Resubmitted (ou um recurso é marcado para reenvio), a empresa precisa enviar dados corrigidos ou adicionais. Você pode:

Reenviar o mesmo url: o fluxo hospedado retoma a partir do ponto em que o reenvio é necessário.
Reemitir um link inválido de pessoa-chave: uma pessoa cuja sessão de KYC vinculada foi excluída ou expirou antes de a pessoa iniciá-la recebe uma nova sessão com Regenerate Key People KYC Session.
Abrir um caso no Business Console para acompanhar internamente as idas e vindas.

Execute as etapas a partir do seu próprio front-end

As etapas de documentos e de Pessoas-chave também podem ser conduzidas a partir do seu servidor com a sua chave de API, de modo que você mantém a interface do usuário e a Didit mantém a verificação e a decisão. Cada chamada é restrita à sessão de KYB, exige a permissão write:businesses (a leitura das partes extraídas também aceita read:businesses ou read:sessions) e executa as mesmas verificações, o mesmo faturamento e o mesmo avanço de etapa que ocorre na página hospedada.

Envie os documentos societários enquanto a sessão estiver na etapa KYB Documents.
Leia as partes mencionadas nos documentos, incluindo acionistas e percentuais de propriedade, e mostre-as ao seu solicitante.
Crie, edite e exclua rascunhos de partes. Um rascunho não é declarado e não tem custo.
Envie os rascunhos. A Didit decide quais partes devem ser verificadas, cria uma sessão de KYC para cada uma e retorna o kyc_session_url correspondente para você enviar ou incorporar.
Leia a decisão consolidada na sessão, como no fluxo hospedado.

Uma chamada feita enquanto a sessão está em outra etapa responde 409 kyb_step_mismatch com a etapa em que ela está, e uma sessão finalizada responde 409 kyb_session_not_writable.

Agregação do perfil da empresa

Se você informar vendor_data na criação da sessão, a Didit agrega todas as sessões dessa empresa em uma única entidade empresarial. Use o mapa features da entidade para responder “esta empresa está totalmente verificada neste momento?” sem percorrer as sessões. Benefícios:

Fluxos periódicos de re-KYB são adicionados ao mesmo perfil.
As transações monitoradas com o mesmo vendor_data carregam o contexto de risco da empresa.
UBOs e administradores vinculados a entidades User geram relações entre entidades.

Boas práticas

Prática	Por quê
Sempre envie `vendor_data`	Sem ele, a sessão fica órfã e não pode ser agregada.
Use webhooks, não polling	Menor latência e nenhuma pressão sobre o limite de requisições.
Verifique as assinaturas dos webhooks	Evita eventos falsificados.
Armazene o `session_id` no seu sistema	É necessário para recuperar a decisão e gerar PDFs.
Marque as sessões com `metadata`	Simplifica relatórios e depuração.
Configure um fluxo de teste	Use um fluxo de sandbox para testar a integração antes da produção.

Tratamento de erros

Cenário	Resposta
`workflow_id` inválido	`400 Bad Request`
Sessão duplicada com o mesmo `vendor_data`	Cria uma nova sessão. Isso é intencional, já que a reverificação é esperada.
País da empresa fora dos países permitidos no fluxo	A verificação no registro gera o aviso `KYB_COUNTRY_RESTRICTED`.
Indisponibilidade do provedor de registro durante a busca de empresas	`POST /v3/kyb/search/` retorna `502` com `code: "kyb_registry_provider_unavailable"`. Não há cobrança: tente novamente ou crie uma ramificação com base em `code` para oferecer o cadastro manual da empresa. No fluxo hospedado da Didit, a empresa é encaminhada automaticamente para o cadastro manual, em vez de receber um erro que exige apenas uma nova tentativa. Consulte Busca no registro KYB.
Limite de requisições	`429 Too Many Requests` com o cabeçalho `Retry-After`.

Referência completa de limite de requisições.

Próximos passos

Webhooks

Todos os eventos e payloads de KYB.

Status

Referência da máquina de estados.

Esquema de resposta

Como interpretar a decisão de KYB.

Primeiros passos

Recursos

Perfis de empresas

Referência

Console

Guia de integração KYB: arquitetura e padrões

Arquitetura

Autenticação

Criação de sessão

Entrega do link hospedado

Polling vs. webhooks

Tratamento de webhooks

Tratamento de decisões

Fluxo de reenvio

Execute as etapas a partir do seu próprio front-end

Agregação do perfil da empresa

Boas práticas

Tratamento de erros

Próximos passos

Webhooks

Status

Esquema de resposta

​Arquitetura

​Autenticação

​Criação de sessão

​Entrega do link hospedado

​Polling vs. webhooks

​Tratamento de webhooks

​Tratamento de decisões

​Fluxo de reenvio

​Execute as etapas a partir do seu próprio front-end

​Agregação do perfil da empresa

​Boas práticas

​Tratamento de erros

​Próximos passos

Webhooks

Status

Esquema de resposta

Arquitetura

Autenticação

Criação de sessão

Entrega do link hospedado

Polling vs. webhooks

Tratamento de webhooks

Tratamento de decisões

Fluxo de reenvio

Execute as etapas a partir do seu próprio front-end

Agregação do perfil da empresa

Boas práticas

Tratamento de erros

Próximos passos