Verificação de empresas (KYB): início rápido em 10 min

Este guia mostra como concluir uma verificação KYB completa em menos de 10 minutos. Vai criar um fluxo, iniciar uma sessão, enviar a ligação de verificação alojada ao seu contacto na empresa, aguardar o webhook e obter a decisão final.

Pré-requisitos

Uma aplicação Didit com KYB ativado. Crie uma em business.didit.me, se necessário.
Uma chave de API em Developer Settings → API Keys.
Um endpoint de webhook acessível a partir da Internet (para o webhook de decisão).

Passos

Crie um fluxo KYB na consola

Aceda a Workflows → Create workflow. Escolha Verificação de empresas como tipo de fluxo.Ative as funcionalidades de que precisa:

Consulta ao registo de empresas (obrigatório)
AML da Empresa (recomendado)
Pessoas-chave (obrigatório para a maioria dos setores regulados)
Documentos (opcional: escolha os tipos de documento que vai exigir)

Guarde e copie o workflow_id; vai usá-lo no passo seguinte.

Crie uma sessão de Verificação de empresas (KYB) através da API

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "YOUR_KYB_WORKFLOW_ID",
    "vendor_data": "biz-acme-001"
  }'

A resposta contém o session_id, o session_number e o url, a ligação de verificação alojada que entrega ao contacto na empresa. O tipo de fluxo (KYB) marca automaticamente a sessão como sessão de empresa.

Envie a ligação ao seu contacto na empresa

Envie o url ao administrador da empresa através do seu próprio e-mail ou chat. Este abre a ligação, preenche os dados do registo, adiciona pessoas-chave e UBOs e carrega os documentos.Pode personalizar a experiência alojada com identidade visual, logótipo e domínio; consulte Marca branca.

Receba o webhook de estado

Quando a empresa concluir o fluxo e o processamento KYB atingir um estado final, o Didit envia um POST com um evento status.updated para o seu endpoint de webhook. Os eventos de sessões de empresa incluem session_kind: "business" dentro de data; filtre por esse campo para encaminhar o evento para o seu processador KYB.Verifique a assinatura HMAC X-Signature-V2 antes de confiar no evento (consulte webhooks) e só depois acione a sua lógica a jusante. Guarde o secret_shared_key do destino (devolvido ao registar o webhook) como DIDIT_WEBHOOK_SECRET no seu .env.Exemplo de payload:

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "vendor_data": "biz-acme-001",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "decision": { "...": "full KYB decision" }
}

Obtenha a decisão (opcional)

O payload do webhook status.updated já contém a decisão completa. Só precisa de chamar este endpoint se não tiver subscrito os webhooks ou se quiser obter a decisão mais tarde, a pedido.

curl https://verification.didit.me/v3/session/bs_01H.../decision/ \
  -H "x-api-key: YOUR_API_KEY"

A decisão inclui os dados do registo, as pessoas-chave (UBOs, acionistas, administradores e representantes), as correspondências AML, os documentos e os resultados por funcionalidade. Consulte o esquema de resposta para a referência completa do payload.

Aja de acordo com a decisão

Com base em status:

"Approved": faça o onboarding da empresa.
"Declined": recuse a empresa e registe as etiquetas de warnings[] da decisão.
"In Review": aguarde a decisão do analista; receberá outro webhook quando for concluída.

Exemplo em Node.js

import fetch from 'node-fetch';

const API_KEY = process.env.DIDIT_API_KEY!;
const WORKFLOW_ID = process.env.DIDIT_KYB_WORKFLOW_ID!;
const BASE_URL = 'https://verification.didit.me';

async function startKybVerification(vendorData: string) {
  const res = await fetch(`${BASE_URL}/v3/session/`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ workflow_id: WORKFLOW_ID, vendor_data: vendorData }),
  });
  if (!res.ok) throw new Error(`Session create failed: ${res.status}`);
  return res.json();
}

async function getDecision(sessionId: string) {
  const res = await fetch(`${BASE_URL}/v3/session/${sessionId}/decision/`, {
    headers: { 'x-api-key': API_KEY },
  });
  return res.json();
}

// Kick off the flow
const { session_id, url } = await startKybVerification('biz-acme-001');
console.log('Deliver this URL to your contact:', url);

// ... later, after the webhook confirms completion:
const decision = await getDecision(session_id);
console.log('KYB status:', decision.status);

O que acontece automaticamente

Consulta ao registo de empresas em 190+ jurisdições.
Extração de UBO e de administradores a partir dos dados do registo.
Triagem AML ao nível da empresa (sanções, PEP, notícias adversas).
Triagem AML ao nível da pessoa para cada pessoa identificada.
OCR de documentos e cruzamento de informação.
Criação e agregação de Perfil de empresa com base em vendor_data.

Próximos passos

Guia de integração

Arquitetura de ponta a ponta, consulta periódica vs webhooks, lógica de novas tentativas.

Webhooks KYB

Todos os eventos KYB e a estrutura dos payloads.

Estados

Referência dos estados de sessão, de funcionalidade e de registo.

Esquema de resposta

O payload completo da decisão KYB.

Entidades empresariais

Como os perfis são agregados entre sessões.

Primeiros passos

Funcionalidades

Perfis de empresas

Referência

Consola

Verificação de empresas (KYB): início rápido em 10 min

Pré-requisitos

Passos

Exemplo em Node.js

O que acontece automaticamente

Próximos passos

Guia de integração

Webhooks KYB

Estados

Esquema de resposta

Entidades empresariais

​Pré-requisitos

​Passos

​Exemplo em Node.js

​O que acontece automaticamente

​Próximos passos

Guia de integração

Webhooks KYB

Estados

Esquema de resposta

Entidades empresariais

Pré-requisitos

Passos

Exemplo em Node.js

O que acontece automaticamente

Próximos passos