O Ciclo de Vida da Sessão KYB: Estados e Webhooks (PT-PT)

Uma verificação KYB não é uma simples resposta de sim/não — é um processo com várias etapas. A pesquisa de registo pode aprovar instantaneamente, enquanto a verificação de documentos aguarda uma nova submissão e a AML da entidade fica em revisão pendente de um analista. Para integrar o KYB de forma eficiente, precisa de saber exatamente em que estado se encontra cada parte da verificação e precisa que os seus próprios sistemas sejam atualizados no momento em que qualquer um desses estados muda. É para isso que servem o ciclo de vida da sessão e os webhooks.

A API de Verificação de Negócios da Didit expõe a máquina de estados completa: um estado na sessão geral, um estado em cada funcionalidade, um conjunto separado de estados para a entidade comercial assim que esta está sob gestão, e webhooks que são acionados a cada alteração. A verificação completa da empresa custa 2,00 €, e este guia mapeia todo o ciclo de vida — todos os estados, todos os webhooks, e a API de gestão que os une.

Principais conclusões

• Três camadas de estado. Uma verificação KYB tem um estado de sessão, estados por funcionalidade e — uma vez gerida — um estado de entidade comercial.
• Oito estados de sessão. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.
• Seis estados de funcionalidade em cada uma das quatro funcionalidades KYB: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.
• Três estados de entidade sob gestão: ACTIVE, FLAGGED, BLOCKED.
• Webhooks para tudo. status.updated e data.updated (com session_kind: business) para sessões; business.status.updated e business.data.updated para entidades geridas.
• Uma API de gestão completa — POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, PATCH .../update-status/.

O que o ciclo de vida KYB abrange

Uma verificação KYB produz estados em três camadas, e cada uma responde a uma pergunta diferente:

• A sessão responde a “como está a correr a verificação no geral?”
• Cada funcionalidade responde a “qual é o estado da verificação de registo / AML da empresa / documentos / verificação de pessoas chave?”
• A entidade comercial responde a “qual é a situação operacional desta empresa no nosso sistema neste momento?”

Lê as três, e mantém-nas sincronizadas com webhooks em vez de sondagens. Uma verificação começa como uma sessão, resolve as suas funcionalidades, chega a um resultado geral, e depois — assim que começa a gerir a empresa — possui um estado de entidade comercial que controla à medida que as circunstâncias mudam.

Porquê é importante

Sem um estado granular, a integração KYB degenera em suposições: uma única bandeira de “pendente” não lhe diz nada sobre qual verificação está a atrasar as coisas ou que ação a desbloquearia. Com estados por funcionalidade, pode encaminhar com precisão — pedir ao requerente para reenviar um documento, colocar uma correspondência AML de entidade para revisão do analista, solicitar a um UBO que conclua o seu KYC — em vez de falhar toda a verificação.

Os webhooks são importantes porque o KYB é assíncrono. Os dados de registo, OCR de documentos e resultados de triagem chegam em momentos diferentes, e a revisão humana demora ainda mais. Sondar por alterações é um desperdício e lento; os webhooks enviam a alteração no momento em que acontece, para que os seus registos reflitam a realidade sem uma tarefa cron a sobrecarregar a API.

Detalhes técnicos

Uma sessão KYB é criada na API unificada /v3/ e reporta o seu estado de ciclo de vida.

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "your_kyb_workflow_id",
    "vendor_data": "merchant_6601",
    "callback": "https://yourapp.com/kyb/callback"
  }'

Um webhook status.updated contém o estado da sessão e os estados por funcionalidade:

{
  "event": "status.updated",
  "session_kind": "business",
  "session_id": "kyb_3a90f1c2",
  "vendor_data": "merchant_6601",
  "status": "IN_REVIEW",
  "features": {
    "kyb_registry": "APPROVED",
    "kyb_company_aml": "IN_REVIEW",
    "kyb_documents": "RESUB_REQUESTED",
    "kyb_key_people": "APPROVED"
  }
}

Estados da sessão. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.

Estados das funcionalidades. Cada um de kyb_registry, kyb_company_aml, kyb_documents, e kyb_key_people reporta um dos seguintes: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.

Webhooks. Para sessões: status.updated (alterações do ciclo de vida) e data.updated (dados enriquecidos), ambos com session_kind: "business". Para entidades geridas: business.status.updated e business.data.updated.

Preço. 2,00 € por verificação de empresa.

Gerir a entidade comercial

Assim que uma empresa é verificada, torna-se uma entidade que gere através da API de negócios:

• POST /v3/businesses/create/ — registar uma entidade comercial.
• GET /v3/businesses/ — listar negócios geridos.
• GET /v3/businesses/{vendor_data}/ — obter um negócio pela sua referência vendor_data.
• PATCH .../update-status/ — alterar o estado da entidade.

A entidade possui o seu próprio estado, independente da sessão de verificação: ACTIVE (em bom estado), FLAGGED (sob revisão devido a um sinal de risco), ou BLOCKED (suspensa). Esta é a camada operacional — uma empresa pode completar uma sessão APPROVED e mais tarde ser FLAGGED porque a monitorização revelou algo. As alterações à entidade emitem business.status.updated e business.data.updated para que os sistemas a jusante se mantenham atualizados.

O ciclo de vida, de ponta a ponta

Uma verificação típica percorre as camadas por ordem. A sessão abre em NOT_STARTED, passa para IN_PROGRESS à medida que as funcionalidades são executadas, e cada funcionalidade é resolvida — registo APPROVED, documentos talvez RESUB_REQUESTED até que um upload limpo chegue, AML da empresa IN_REVIEW até que um analista limpe uma correspondência, pessoas chave APPROVED. Quando todas as funcionalidades se resolvem, a sessão termina em APPROVED, DECLINED, ou IN_REVIEW. A partir daí, a empresa entra em gestão como uma entidade ACTIVE, e o seu estado pode posteriormente mudar para FLAGGED ou BLOCKED conforme a supervisão contínua ditar — cada transição é-lhe enviada por webhook.

Casos de uso

• Marketplaces encaminham os vendedores com precisão: reenviar um documento, concluir o KYC de um UBO, ou reter uma correspondência AML de entidade — sem falhar todo o processo de integração.
• Plataformas de Fintech e bancárias mantêm os registos de contas corporativas sincronizados com webhooks em vez de sondagens, e sinalizam ou bloqueiam entidades à medida que o risco muda.
• Provedores de empréstimos acompanham o estado de cada verificação de subscrição e atualizam a situação do mutuário através da API de gestão.
• Plataformas Crypto B2B mantêm um ciclo de vida auditável de cada entidade contraparte, desde a verificação até à situação contínua.

Como integrar com a Didit

1. Construa o fluxo de trabalho. Na Consola de Negócios, crie um fluxo de trabalho KYB com as funcionalidades de que necessita.
2. Crie a sessão. POST /v3/session/ com o seu workflow_id KYB e uma referência vendor_data.
3. Subscreva os webhooks. Lide com status.updated e data.updated (session_kind: business) para sessões, e business.status.updated / business.data.updated para entidades geridas.
4. Gira as entidades. Use POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, e PATCH .../update-status/ para manter cada empresa ACTIVE, FLAGGED, ou BLOCKED.

Como tudo está na API unificada /v3/, o mesmo modelo de ciclo de vida aplica-se a KYC, monitorização e KYB — uma máquina de estados consistente para toda a plataforma de identidade e fraude.

Perguntas frequentes

Quais são os estados da sessão KYB?

NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, e EXPIRED.

Que estados reportam as funcionalidades individuais?

Cada um de kyb_registry, kyb_company_aml, kyb_documents, e kyb_key_people reporta NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, ou AWAITING_USER.

A que webhooks devo subscrever?

Para sessões, status.updated e data.updated (com session_kind: business). Para entidades comerciais geridas, business.status.updated e business.data.updated.

Como altero a situação de uma empresa após a verificação?

Use a API de gestão — PATCH .../update-status/ — para definir a entidade como ACTIVE, FLAGGED, ou BLOCKED.

Quanto custa uma verificação KYB?

2,00 € por empresa para a verificação completa — registo, UBO, responsáveis e AML da entidade.

Pronto para começar?

Leia a visão geral da Verificação de Negócios na documentação, veja como se encaixa no resto da plataforma na página do produto Verificação de Negócios e verifique os preços transparentes por chamada na página de preços. Quando estiver pronto, comece gratuitamente — 500 verificações KYC gratuitas todos os meses e verificação de negócios a 2,00 € por empresa.