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

Este guia complementa o início rápido. Aborda a arquitetura, todas as decisões de integração e os padrões operacionais que tornam a KYB fiável em produção.

Arquitetura

Autenticação

Todos os pedidos exigem o cabeçalho x-api-key com a chave de API da sua aplicação. Consulte Autenticação da API para a rotação de chaves, a separação de ambientes e os âmbitos.

Criação de sessão

Endpoint único: POST /v3/session/. O tipo do fluxo determina se a sessão é KYC ou KYB; não é necessário nenhum indicador explícito de “business”. Campos recomendados na criação:

Campo	Finalidade
`workflow_id`	Obrigatório: referencia o seu fluxo KYB.
`vendor_data`	O seu identificador da empresa. Associa a sessão a uma entidade Business.
`callback_url`	Opcional: para onde redirecionar o utilizador após a conclusão.
`expected_details`	Opcional: `{ company_name, registry_country, registration_number }`. Preenche previamente a pesquisa no registo de empresas: o país de constituição é pré-selecionado e bloqueado (`registry_country` como `XX`, ou `XX-YY` para registos a nível dos estados, por exemplo `US-CA`), os campos do nome da empresa e do número de registo são preenchidos, e a pesquisa indicada é executada automaticamente, combinando os dois identificadores quando ambos estão presentes. Apenas preenchimento prévio: as divergências não geram avisos.
`metadata`	Opcional: JSON associado à sessão.

Esquema completo: criar sessão.

Envio da ligação de verificação alojada

O url da resposta é uma ligação de verificação alojada. Opções de envio:

Envie-a por e-mail a partir da sua própria plataforma.
Incorpore-a na sua interface de onboarding como uma ligação.
Abra-a numa webview na aplicação (iOS / Android / React Native).

Pode personalizar a experiência alojada (logótipo, cor, domínio, modelos de e-mail) através da Marca branca.

Polling vs. webhooks

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

Faça polling de GET /v3/session/{id}/decision/ com intervalo de espera exponencial (de 10 s no início, até 60 s).
Pare o polling quando status tiver um dos valores "Approved", "Declined", "In Review".

O polling com frequência elevada pode atingir os limites de pedidos. Em produção, dê sempre preferência aos webhooks.

Tratamento de webhooks

Subscreva os eventos que lhe interessam. Os mesmos eventos abrangem KYC e KYB, com session_kind: "business" no payload para identificar os eventos de sessões de empresa:

status.updated: o estado da sessão foi alterado. Filtre por session_kind === "business" para sessões KYB.
data.updated: um revisor editou dados do registo ou pessoas-chave na consola, ou o registo comunicou uma alteração. Não é enviado quando o candidato carrega um documento ou submete pessoas-chave; nesses casos, siga status.updated. Aplica-se o mesmo filtro de session_kind.
business.status.updated / business.data.updated: a entidade Business associada foi alterada.

Catálogo completo de eventos: webhooks KYB. Verificação da assinatura e comportamento das novas tentativas: referência de webhooks.

Tratamento das 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 os estados KYB para ver a máquina de estados completa, e os avisos KYB para as etiquetas que explicam uma decisão.

Fluxo de reenvio

Quando uma sessão de Verificação de empresas (KYB) passa para Resubmitted (ou quando uma funcionalidade é marcada para reenvio), a empresa tem de carregar os dados corrigidos ou adicionais. Pode:

Reenviar o mesmo url: o fluxo alojado retoma a partir do ponto em que é necessário reenviar.
Reemitir a ligação de uma pessoa-chave inválida: uma parte cuja sessão KYC filha foi eliminada ou expirou antes de a pessoa a iniciar, recebe uma nova sessão com Regenerar sessão KYC de pessoas-chave.
Abrir um caso na Business Console para acompanhar internamente as trocas de informação.

Execute os passos a partir do seu próprio frontend

Os passos de documentos e de pessoas-chave também podem ser executados a partir do seu servidor com a sua chave de API, pelo que mantém a interface de utilizador e a Didit mantém a verificação e a decisão. Cada chamada está limitada à sessão KYB, requer a permissão write:businesses (a leitura das partes extraídas aceita também read:businesses ou read:sessions) e executa as mesmas verificações, faturação e avanço de passo que a página alojada.

Carregue os documentos da empresa enquanto a sessão estiver no passo de documentos KYB.
Leia as partes que os documentos indicam, incluindo acionistas e percentagens de propriedade, e apresente-as ao seu candidato.
Crie, edite e elimine rascunhos de partes. Um rascunho não é declarado e não tem custos.
Submeta os rascunhos. A Didit decide quais as partes que têm de ser verificadas, cria uma sessão KYC para cada uma e devolve o respetivo kyc_session_url para envio ou incorporação.
Leia a decisão consolidada da sessão, tal como no fluxo alojado.

Uma chamada feita enquanto a sessão está noutro passo recebe a resposta 409 kyb_step_mismatch com o passo em que se encontra, e uma sessão concluída recebe 409 kyb_session_not_writable.

Agregação do perfil da empresa

Se enviar vendor_data na criação da sessão, a Didit agrega todas as sessões dessa empresa numa única entidade Business. Use o mapa features da entidade para responder à pergunta «esta empresa está totalmente verificada neste momento?» sem percorrer sessões. Vantagens:

Os fluxos de re-KYB periódicos acrescentam dados ao mesmo perfil.
As transações monitorizadas com o mesmo vendor_data transportam o contexto de risco da empresa.
Os UBOs e os administradores associados a entidades User preenchem as relações entre entidades.

Boas práticas

Prática	Motivo
Envie sempre `vendor_data`	Sem ele, a sessão fica órfã e não pode ser agregada.
Use webhooks em vez de polling	Menor latência e sem pressão sobre o limite de pedidos.
Valide as assinaturas dos webhooks	Evita eventos falsificados.
Guarde o `session_id` do seu lado	Necessário para obter a decisão e gerar PDFs.
Associe `metadata` às sessões	Simplifica a elaboração de relatórios e a depuração.
Configure um fluxo de teste	Use um fluxo em 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. Isto é intencional, uma vez que se espera a reverificação.
País da empresa fora dos países permitidos pelo fluxo	A verificação do registo gera o aviso `KYB_COUNTRY_RESTRICTED`.
Indisponibilidade do fornecedor do registo durante a pesquisa de empresas	`POST /v3/kyb/search/` devolve `502` com `code: "kyb_registry_provider_unavailable"`. Não é cobrado. Tente novamente ou use o `code` para oferecer a introdução manual da empresa. No fluxo alojado da Didit, a empresa é encaminhada automaticamente para a introdução manual, em vez de um erro que apenas permite tentar novamente. Consulte Pesquisa no registo KYB.
Limite de pedidos	`429 Too Many Requests` com o cabeçalho `Retry-After`.

Consulte a referência completa sobre o limite de pedidos.

Próximos passos

Webhooks

Todos os eventos e payloads de KYB.

Estados

Referência da máquina de estados.

Esquema de resposta

Como descodificar a decisão KYB.

Primeiros passos

Funcionalidades

Perfis de empresas

Referência

Consola

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

Arquitetura

Autenticação

Criação de sessão

Envio da ligação de verificação alojada

Polling vs. webhooks

Tratamento de webhooks

Tratamento das decisões

Fluxo de reenvio

Execute os passos a partir do seu próprio frontend

Agregação do perfil da empresa

Boas práticas

Tratamento de erros

Próximos passos

Webhooks

Estados

Esquema de resposta

​Arquitetura

​Autenticação

​Criação de sessão

​Envio da ligação de verificação alojada

​Polling vs. webhooks

​Tratamento de webhooks

​Tratamento das decisões

​Fluxo de reenvio

​Execute os passos a partir do seu próprio frontend

​Agregação do perfil da empresa

​Boas práticas

​Tratamento de erros

​Próximos passos

Webhooks

Estados

Esquema de resposta

Arquitetura

Autenticação

Criação de sessão

Envio da ligação de verificação alojada

Polling vs. webhooks

Tratamento de webhooks

Tratamento das decisões

Fluxo de reenvio

Execute os passos a partir do seu próprio frontend

Agregação do perfil da empresa

Boas práticas

Tratamento de erros

Próximos passos