> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Guia de integração KYB com a Didit: arquitetura, sessões, webhooks, polling e decisões. Desde $2.00 por verificação, por país e nível.



Prompt de integração KYB
        Copiar o prompt para a área de transferência



      
      

\<pre>

\````# Goal — ship a production-ready KYB (business verification) integration

KYB runs through the same `/v3/session/` endpoint as KYC. The session's workflow determines whether it's a KYC or KYB session — pass a KYB workflow id and Didit creates a business session automatically (`session_kind: "business"`).

\## End-to-end flow

\```
You: POST /v3/session/ (KYB workflow_id, vendor_data) → session_id, url, session_token
You: deliver url to the business contact (email / your UI / iframe)
Biz: completes the hosted flow (registry confirm → Key People → documents → AML)
Didit → Webhook: status.updated with session_kind: "business"
You: GET /v3/session/{session_id}/decision/ → full KYB decision
You: branch on decision.status ("Approved" / "Declined" / "In Review" / "Resubmitted")
\```

\## Create a KYB session

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "$KYB_WORKFLOW_ID",
"vendor_data": "biz-acme",
"callback": "https://myapp.com/kyb/return",
"metadata": {"plan": "growth", "country": "GBR"}
}'
\```

Recommended fields:

\- `workflow_id` — references your KYB workflow.
\- `vendor_data` — your business id; binds the session to a [Business entity](/entities/businesses/overview).
\- `callback` — where to redirect the user after completion.
\- `metadata` — JSON attached to the session for your own reporting.

\## Webhook events for KYB

\| Event | Trigger |
\|---|---|
\| `status.updated` (with `session_kind === "business"`) | KYB session status changed. Follow this event for progress. |
\| `data.updated` (with `session_kind === "business"`) | A reviewer edited registry data or Key People in the console, or the registry reported a change (registry monitoring). Not sent for document uploads or Key People submissions. |
\| `business.status.updated` | Linked Business entity status changed |
\| `business.data.updated` | Linked Business entity profile / counters changed |

Subscribe via `POST /v3/webhook/destinations/` with `webhook_version: "v3"`. Verify the `X-Signature-V2` header (HMAC-SHA256 of canonical JSON). De-dupe on `event_id`. Respond within 5 seconds.

\## KYB decision shape (V3 plural arrays)

\```bash
curl https://verification.didit.me/v3/session/$SESSION_ID/decision/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

Key V3 arrays you'll iterate:

\| Array | Holds |
\|---|---|
\| `key_people_checks[]` | UBOs, shareholders, directors, officers — bucketed into `registry` (from the registry lookup) and `submitted` (what the business confirmed). Plus a `ubo_kyc_summary` rollup. |
\| `document_verifications[]` | Each item has `status`, `node_id`, `items[]` (signed `file_url` + OCR extract), `groups`, `required_groups`. |
\| `aml_screenings[]` | Company AML and per-person AML hits. |

The KYB-specific features are `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`. Statuses are the exact labels `"Not Finished"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Resub Requested"`.

\## Apply-decision logic

\```ts
switch (decision.status) {
case "Approved":   await onboardBusiness(decision); break;
case "Declined":   await logRejection(collectWarnings(decision), decision); break; // warnings[] tags on each feature array
case "In Review":  await markPending(decision); break; // wait for next webhook
case "Resubmitted":await notifyBusiness(decision); break; // business needs to re-upload
case "Awaiting User": await pingChildPersonForKyc(decision); break; // child Key People KYC pending
}
\```

See /business-verification/statuses for the full state machine.

\## Resubmission flow

When a session transitions to `Resubmitted` (or a feature to `Resub Requested`, or a feature is marked for resubmission), re-deliver the same `url` — the hosted flow resumes at the resubmission step. To re-verify a specific Key Person, resubmit that person's child KYC session; the parent `kyb_key_people` re-aggregates automatically.

\## Key People child KYC

If your KYB workflow has KYC required for some roles, each person triggers a child KYC session automatically. While any child is in progress, the parent's `kyb_key_people` status is `Awaiting User`. Configure per-role required/skippable behaviour at *Workflows → [KYB workflow] → Key People*. A child session expires after the session expiration time of the KYC workflow its role is mapped to, not the KYB session's. A party whose session was deleted, or whose link expired before the person started it, is reissued with `POST /v3/session/{session_id}/kyb/parties/{party_uuid}/regenerate/`.

\## Failure modes

\| Scenario | Response |
\|---|---|
\| Invalid `workflow_id` | `400 Bad Request` |
\| Wrong workflow type (KYC instead of KYB) | Session is created but runs KYC steps — verify the workflow's `workflow_type` is `"kyb"` |
\| Duplicate `vendor_data` | A new session is created — that's by design for re-KYB |
\| Company country outside the workflow's allowed countries | The registry check raises the `KYB_COUNTRY_RESTRICTED` warning |
\| Registry provider outage during company search | `502` with `code: "kyb_registry_provider_unavailable"`. Not billed. In Didit's hosted flow, the business is automatically offered manual company entry instead of a retry-only error. |
\| Rate limit | `429` with `Retry-After` header |

\## Sources of truth

\- /sessions-api/create-session — request body schema
\- /business-verification/response-schema — KYB decision payload
\- /business-verification/statuses — feature state machine
\- /business-verification/webhooks — KYB-specific event catalog
\- /entities/businesses/data-model — Business entity schema
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Colar em

Este guia complementa o [início rápido](https://docs.didit.me/pt/business-verification/quickstart.md). 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```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Biz as Business contact
    participant Webhook as Your webhook endpoint

    You->>Didit: POST /v3/session/ (workflow_id, vendor_data)
    Didit-->>You: session_id, url, token
    You->>Biz: Deliver hosted verification URL (your email/flow)
    Biz->>Didit: Completes KYB hosted flow
    Didit->>Didit: Registry lookup, AML screening, OCR
    Didit->>Webhook: status.updated (session_kind: business)
    You->>Didit: GET /v3/session/{id}/decision/
    Didit-->>You: Full KYB decision payload
    You->>You: Onboard / reject / escalate based on status
```## AutenticaçãoTodos os pedidos exigem o cabeçalho `x-api-key` com a chave de API da sua aplicação. Consulte [Autenticação da API](https://docs.didit.me/pt/getting-started/api-authentication.md) para a rotação de chaves, a separação de ambientes e os âmbitos.## Criação de sessãoEndpoint ú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](https://docs.didit.me/pt/entities/businesses/overview.md). |
| `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](https://docs.didit.me/pt/sessions-api/create-session.md).## Envio da ligação de verificação alojadaO `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](https://docs.didit.me/pt/console/white-label.md).## Polling vs. webhooksOs 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"`.> [!WARNING]
>
> O polling com frequência elevada pode atingir os [limites de pedidos](https://docs.didit.me/pt/integration/rate-limiting.md). Em produção, dê sempre preferência aos webhooks.## Tratamento de webhooksSubscreva 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](https://docs.didit.me/pt/entities/businesses/overview.md) associada foi alterada.Catálogo completo de eventos: [webhooks KYB](https://docs.didit.me/pt/business-verification/webhooks.md). Verificação da assinatura e comportamento das novas tentativas: [referência de webhooks](https://docs.didit.me/pt/integration/webhooks.md).## Tratamento das decisões```typescript theme={null}
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](https://docs.didit.me/pt/business-verification/statuses.md) para ver a máquina de estados completa, e os [avisos KYB](https://docs.didit.me/pt/business-verification/warnings.md) para as etiquetas que explicam uma decisão.## Fluxo de reenvioQuando 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](https://docs.didit.me/pt/sessions-api/regenerate-kyb-party.md).
- **Abrir um [caso](https://docs.didit.me/pt/transaction-monitoring/cases.md)** na Business Console para acompanhar internamente as trocas de informação.## Execute os passos a partir do seu próprio frontendOs 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.1) [Carregue os documentos da empresa](https://docs.didit.me/pt/sessions-api/kyb-upload-documents.md) enquanto a sessão estiver no passo de documentos KYB.
2) [Leia as partes que os documentos indicam](https://docs.didit.me/pt/sessions-api/kyb-extracted-parties.md), incluindo acionistas e percentagens de propriedade, e apresente-as ao seu candidato.
3) [Crie](https://docs.didit.me/pt/sessions-api/kyb-create-party-draft.md), [edite](https://docs.didit.me/pt/sessions-api/kyb-update-party-draft.md) e [elimine](https://docs.didit.me/pt/sessions-api/kyb-delete-party-draft.md) [rascunhos de partes](https://docs.didit.me/pt/sessions-api/kyb-list-party-drafts.md). Um rascunho não é declarado e não tem custos.
4) [Submeta os rascunhos](https://docs.didit.me/pt/sessions-api/kyb-submit-parties.md). 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.
5) 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 empresaSe enviar `vendor_data` na criação da sessão, a Didit agrega todas as sessões dessa empresa numa única [entidade Business](https://docs.didit.me/pt/entities/businesses/overview.md). 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](https://docs.didit.me/pt/standalone-apis/kyb-registry-search.md#tratar-indisponibilidades-do-registo). |
| Limite de pedidos | `429 Too Many Requests` com o cabeçalho `Retry-After`. |Consulte a referência completa sobre o [limite de pedidos](https://docs.didit.me/pt/integration/rate-limiting.md).## Próximos passos> [card] [Webhooks](https://docs.didit.me/pt/business-verification/webhooks.md)
>
> Todos os eventos e payloads de KYB.> [card] [Estados](https://docs.didit.me/pt/business-verification/statuses.md)
>
> Referência da máquina de estados.> [card] [Esquema de resposta](https://docs.didit.me/pt/business-verification/response-schema.md)
>
> Como descodificar a decisão KYB.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.