El cicle de vida de la sessió KYB: estats i webhooks (CA)

Una verificació KYB no és una simple resposta de sí/no, és un procés amb parts mòbils. La consulta al registre pot aprovar-se instantàniament, mentre que la verificació de documents espera una nova presentació i l'AML de l'entitat està en revisió pendent d'un analista. Per integrar KYB de manera neta, necessiteu saber exactament en quin estat es troba cada part d'una verificació, i necessiteu que els vostres propis sistemes s'actualitzin en el moment en què qualsevol d'aquests estats canviï. Per a això serveixen el cicle de vida de la sessió i els webhooks.

L'API de verificació de negocis de Didit exposa la màquina d'estats completa: un estat de la sessió general, un estat de cada funció, un conjunt separat d'estats per a l'entitat empresarial un cop està sota gestió, i webhooks que s'activen amb cada canvi. La verificació completa de l'empresa costa 2,00 $, i aquesta guia descriu tot el cicle de vida — cada estat, cada webhook i l'API de gestió que ho uneix tot.

Aspectes clau

• Tres capes d'estat. Una verificació KYB té un estat de sessió, estats per funció i —un cop gestionada— un estat d'entitat empresarial.
• Vuit estats de sessió. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.
• Sis estats de funció en cadascuna de les quatre funcions KYB: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.
• Tres estats d'entitat sota gestió: ACTIVE, FLAGGED, BLOCKED.
• Webhooks per a tot. status.updated i data.updated (amb session_kind: business) per a sessions; business.status.updated i business.data.updated per a entitats gestionades.
• Una API de gestió completa — POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, PATCH .../update-status/.

Què inclou el cicle de vida KYB

Una verificació KYB produeix estat en tres capes, i cadascuna respon a una pregunta diferent:

• La sessió respon "com va la verificació en general?"
• Cada funció respon "com va el registre / AML de l'empresa / documents / comprovació de persones clau?"
• L'entitat empresarial respon "quin és l'estat operatiu d'aquesta empresa en el nostre sistema ara mateix?"

Llegiu els tres, i els manteniu sincronitzats amb webhooks en lloc de fer sondejos. Una verificació comença com una sessió, resol les seves funcions, arriba a un resultat general i, un cop comenceu a gestionar l'empresa, porta un estat d'entitat empresarial que controleu a mesura que canvien les circumstàncies.

Per què és important

Sense un estat granular, la integració KYB es degrada en conjectures: una única bandera de "pendent" no us diu res sobre quina comprovació està retenint les coses o quina acció la desbloquejaria. Amb estats per funció, podeu encaminar amb precisió — demanar al sol·licitant que torni a enviar un document, posar una coincidència AML d'entitat en cua per a revisió d'analistes, demanar a un UBO que finalitzi el seu KYC — en lloc de fallar tota la verificació.

Els webhooks són importants perquè KYB és asíncron. Les dades del registre, l'OCR de documents i els resultats de la selecció arriben en moments diferents, i la revisió humana encara triga més. Fer sondejos per a canvis és ineficient i lent; els webhooks envien el canvi en el moment en què es produeix, de manera que els vostres registres reflecteixen la realitat sense que una tasca cronometrada estigui bombardejant l'API.

Detalls tècnics

Una sessió KYB es crea contra l'API unificada /v3/ i informa del seu estat de cicle 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"
  }'

Un webhook status.updated porta l'estat de la sessió i els estats per funció:

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

Estats de la sessió. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.

Estats de les funcions. Cadascun de kyb_registry, kyb_company_aml, kyb_documents i kyb_key_people informa un dels següents: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.

Webhooks. Per a sessions: status.updated (canvis de cicle de vida) i data.updated (dades enriquides), ambdós amb session_kind: "business". Per a entitats gestionades: business.status.updated i business.data.updated.

Preu. 2,00 $ per verificació d'empresa.

Gestió de l'entitat empresarial

Un cop verificada una empresa, es converteix en una entitat que gestioneu a través de l'API de negocis:

• POST /v3/businesses/create/ — registrar una entitat empresarial.
• GET /v3/businesses/ — llistar negocis gestionats.
• GET /v3/businesses/{vendor_data}/ — obtenir un negoci pel seu referència vendor_data.
• PATCH .../update-status/ — canviar l'estat de l'entitat.

L'entitat té el seu propi estat, independent de la sessió de verificació: ACTIVE (en bon estat), FLAGGED (en revisió per un senyal de risc) o BLOCKED (suspès). Aquesta és la capa operativa — una empresa pot completar una sessió APPROVED i més tard ser FLAGGED perquè la supervisió va detectar alguna cosa. Els canvis a l'entitat emeten business.status.updated i business.data.updated perquè els sistemes posteriors es mantinguin actualitzats.

El cicle de vida, de principi a fi

Una verificació típica recorre les capes en ordre. La sessió s'obre a NOT_STARTED, passa a IN_PROGRESS a mesura que s'executen les funcions, i cada funció es resol — el registre APPROVED, els documents potser RESUB_REQUESTED fins que arriba una càrrega neta, l'AML de l'empresa IN_REVIEW fins que un analista aprova una coincidència, les persones clau APPROVED. Quan totes les funcions s'estableixen, la sessió acaba en APPROVED, DECLINED o IN_REVIEW. A partir d'aquí, l'empresa entra en gestió com a entitat ACTIVE, i el seu estat pot passar posteriorment a FLAGGED o BLOCKED segons dicti la supervisió continuada — cada transició us és enviada per webhook.

Casos d'ús

• Els marketplaces encaminen els venedors amb precisió: tornar a enviar un document, finalitzar el KYC d'un UBO o retenir una coincidència AML d'una entitat, sense que falli tota la incorporació.
• Les plataformes de fintech i banca mantenen els registres de comptes corporatius sincronitzats amb webhooks en lloc de sondejos, i marquen o bloquegen entitats a mesura que canvia el risc.
• Els proveïdors de préstecs fan un seguiment de l'estat de cada comprovació de subscripció i actualitzen la situació del prestatari mitjançant l'API de gestió.
• Les plataformes Crypto B2B mantenen un cicle de vida auditable de cada entitat contrapart des de la verificació fins a la situació actual.

Com integrar-se amb Didit

1. Construïu el flux de treball. A la Consola de Negocis, creeu un flux de treball KYB amb les funcions que necessiteu.
2. Creeu la sessió. POST /v3/session/ amb el vostre workflow_id de KYB i una referència vendor_data.
3. Subscriviu-vos a webhooks. Gestioneu status.updated i data.updated (session_kind: business) per a sessions, i business.status.updated / business.data.updated per a entitats gestionades.
4. Gestioneu entitats. Utilitzeu POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/ i PATCH .../update-status/ per mantenir cada empresa ACTIVE, FLAGGED o BLOCKED.

Com que tot està a l'API unificada /v3/, el mateix model de cicle de vida s'aplica a KYC, monitorització i KYB — una màquina d'estats coherent per a tota la plataforma d'identitat i frau.

Preguntes freqüents

Quins són els estats de la sessió KYB?

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

Quins estats informen les funcions individuals?

Cadascuna de kyb_registry, kyb_company_aml, kyb_documents i kyb_key_people informa NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED o AWAITING_USER.

A quins webhooks m'he de subscriure?

Per a sessions, status.updated i data.updated (amb session_kind: business). Per a entitats empresarials gestionades, business.status.updated i business.data.updated.

Com canvio la situació d'una empresa després de la verificació?

Utilitzeu l'API de gestió — PATCH .../update-status/ — per establir l'entitat a ACTIVE, FLAGGED o BLOCKED.

Quant costa una verificació KYB?

2,00 $ per empresa per a la verificació completa — registre, UBO, directius i AML d'entitat.

A punt per començar?

Llegiu la visió general de la verificació de negocis a la documentació, vegeu com s'adapta a la resta de la plataforma a la pàgina del producte de verificació de negocis i consulteu els preus transparents per trucada a la pàgina de preus. Quan estigueu a punt, comenceu de franc — 500 comprovacions KYC gratuïtes cada mes i verificació de negocis a 2,00 $ per empresa.