Blog · 21 de maio de 2026

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

Acompanhe uma verificação KYB de ponta a ponta: status da sessão, status por recurso, status da entidade comercial e os webhooks que mantêm seus registros sincronizados. Tudo isso por apenas US$ 2,00 por empresa.

Por Didit21 de maio de 2026Atualizado 21 de mai. de 2026

Uma verificação KYB não é uma simples resposta de sim/não — é um processo com várias etapas. A consulta de registro pode aprovar instantaneamente, enquanto a verificação de documentos aguarda um reenvio e a AML da entidade fica em revisão pendente de um analista. Para integrar o KYB de forma eficiente, você precisa saber exatamente o estado de cada parte da verificação, e seus próprios sistemas precisam ser 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 status na sessão geral, um status em cada recurso, um conjunto separado de status para a entidade comercial uma vez que ela está sob gerenciamento, e webhooks que disparam a cada mudança. A verificação completa da empresa custa US$ 2,00, e este guia mapeia todo o ciclo de vida — cada status, cada webhook e a API de gerenciamento que os conecta.

Principais pontos

Três camadas de estado. Uma verificação KYB possui um status de sessão, status por recurso e — uma vez gerenciada — um status de entidade comercial.
Oito status de sessão. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.
Seis status de recurso em cada um dos quatro recursos KYB: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.
Três status de entidade sob gerenciamento: ACTIVE, FLAGGED, BLOCKED.
Webhooks em tudo. status.updated e data.updated (com session_kind: business) para sessões; business.status.updated e business.data.updated para entidades gerenciadas.
Uma API de gerenciamento 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 estado em três camadas, e cada uma responde a uma pergunta diferente:

A sessão responde "como está a verificação no geral?"
Cada recurso responde "qual é o status do registro / AML da empresa / documentos / verificação de pessoas-chave?"
A entidade comercial responde "qual é a situação operacional desta empresa em nosso sistema agora?"

Você lê todos os três e os mantém sincronizados com webhooks, em vez de fazer polling. Uma verificação começa como uma sessão, resolve seus recursos, chega a um resultado geral e, então — uma vez que você começa a gerenciar a empresa — carrega um status de entidade comercial que você controla conforme as circunstâncias mudam.

Por que é importante

Sem um estado granular, a integração KYB se degrada em suposições: uma única bandeira "pendente" não diz nada sobre qual verificação está causando o atraso ou qual ação a desbloquearia. Com status por recurso, você pode rotear precisamente — pedir ao solicitante para reenviar um documento, colocar uma correspondência AML de entidade em fila para revisão do analista, solicitar que um UBO finalize seu KYC — em vez de reprovar toda a verificação.

Webhooks são importantes porque o KYB é assíncrono. Dados de registro, OCR de documentos e resultados de triagem chegam em momentos diferentes, e a revisão humana leva ainda mais tempo. Fazer polling para mudanças é ineficiente e lento; webhooks enviam a mudança no momento em que ela acontece, para que seus registros reflitam a realidade sem um trabalho cron sobrecarregando a API.

Detalhes técnicos

Uma sessão KYB é criada contra a API unificada /v3/ e reporta 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 carrega o status da sessão e os status por recurso:

{
  "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"
  }
}

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

Status do recurso. 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, ou AWAITING_USER.

Webhooks. Para sessões: status.updated (mudanças de ciclo de vida) e data.updated (dados enriquecidos), ambos carregando session_kind: "business". Para entidades gerenciadas: business.status.updated e business.data.updated.

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

Gerenciando a entidade comercial

Uma vez que uma empresa é verificada, ela se torna uma entidade que você gerencia através da API de negócios:

POST /v3/businesses/create/ — registra uma entidade comercial.
GET /v3/businesses/ — lista negócios gerenciados.
GET /v3/businesses/{vendor_data}/ — busca um negócio por sua referência vendor_data.
PATCH .../update-status/ — altera o status da entidade.

A entidade possui seu próprio status, independente da sessão de verificação: ACTIVE (em boa situação), 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 posteriormente ser FLAGGED porque o monitoramento apontou algo. Mudanças na entidade emitem business.status.updated e business.data.updated para que os sistemas downstream permaneçam atualizados.

O ciclo de vida, de ponta a ponta

Uma verificação típica percorre as camadas em ordem. A sessão se inicia com NOT_STARTED, passa para IN_PROGRESS conforme os recursos são executados, e cada recurso é resolvido — registro APPROVED, documentos talvez RESUB_REQUESTED até que um upload limpo chegue, AML da empresa IN_REVIEW até que um analista libere uma correspondência, pessoas-chave APPROVED. Quando todos os recursos são resolvidos, a sessão finaliza como APPROVED, DECLINED ou IN_REVIEW. A partir daí, a empresa entra em gerenciamento como uma entidade ACTIVE, e seu status pode posteriormente mudar para FLAGGED ou BLOCKED conforme a supervisão contínua ditar — cada transição é enviada a você por webhook.

Casos de uso

Marketplaces roteiam vendedores com precisão: reenviar um documento, finalizar o KYC de um UBO ou reter uma correspondência AML de entidade — sem reprovar todo o processo de onboarding.
Plataformas Fintech e bancárias mantêm registros de contas corporativas sincronizados com webhooks em vez de polling, e sinalizam ou bloqueiam entidades conforme o risco muda.
Provedores de empréstimos acompanham o status de cada verificação de subscrição e atualizam a situação do mutuário através da API de gerenciamento.
Plataformas Crypto B2B mantêm um ciclo de vida auditável de cada entidade contraparte, desde a verificação até a situação atual.

Como integrar com a Didit

Construa o fluxo de trabalho. No Business Console, crie um fluxo de trabalho KYB com os recursos de que você precisa.
Crie a sessão. POST /v3/session/ com seu workflow_id KYB e uma referência vendor_data.
Assine os webhooks. Lide com status.updated e data.updated (session_kind: business) para sessões, e business.status.updated / business.data.updated para entidades comerciais gerenciadas.
Gerencie 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 se aplica a KYC, monitoramento e KYB — uma máquina de estados consistente para toda a plataforma de identidade e fraude.

Perguntas frequentes

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

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

Quais status os recursos individuais reportam?

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 quais webhooks devo me inscrever?

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

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

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

Qual o custo de uma verificação KYB?

US$ 2,00 por empresa para a verificação completa — registro, UBO, diretores e AML da entidade.

Pronto para começar?

Leia a visão geral da Verificação de Negócios na documentação, veja como ela se encaixa no restante 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 por mês e verificação de negócios por US$ 2,00 por empresa.