El Ciclo de Vida de la Sesión KYB: Estados y Webhooks (ES)

Una verificación KYB no es una simple respuesta de sí/no, es un proceso con partes móviles. La búsqueda en el registro podría aprobarse instantáneamente mientras la verificación de documentos espera una nueva presentación y el AML de la entidad está en revisión pendiente de un analista. Para integrar KYB de manera limpia, necesitas saber exactamente en qué estado se encuentra cada parte de una verificación, y necesitas que tus propios sistemas se actualicen en el momento en que cualquiera de esos estados cambie. Para eso son el ciclo de vida de la sesión y los webhooks.

La API de Verificación de Negocios de Didit expone la máquina de estados completa: un estado en la sesión general, un estado en cada característica, un conjunto separado de estados para la entidad comercial una vez que está bajo gestión, y webhooks que se disparan con cada cambio. La verificación completa de la empresa cuesta $2.00, y esta guía mapea todo el ciclo de vida — cada estado, cada webhook y la API de gestión que lo une todo.

Puntos clave

• Tres capas de estado. Una verificación KYB tiene un estado de sesión, estados por característica y — una vez gestionada — un estado de entidad comercial.
• Ocho estados de sesión. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.
• Seis estados de característica en cada una de las cuatro características KYB: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.
• Tres estados de entidad bajo gestión: ACTIVE, FLAGGED, BLOCKED.
• Webhooks en todo. status.updated y data.updated (con session_kind: business) para sesiones; business.status.updated y business.data.updated para entidades gestionadas.
• Una API de gestión completa — POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, PATCH .../update-status/.

Qué cubre el ciclo de vida KYB

Una verificación KYB produce estados en tres capas, y cada una responde a una pregunta diferente:

• La sesión responde "¿cómo va la verificación en general?"
• Cada característica responde "¿en qué estado se encuentra el registro / AML de la empresa / documentos / verificación de personas clave?"
• La entidad comercial responde "¿cuál es la situación operativa de esta empresa en nuestro sistema en este momento?"

Lees las tres, y las mantienes sincronizadas con webhooks en lugar de sondear. Una verificación comienza como una sesión, resuelve sus características, llega a un resultado general y luego — una vez que comienzas a gestionar la empresa — lleva un estado de entidad comercial que tú controlas a medida que cambian las circunstancias.

Por qué es importante

Sin un estado granular, la integración de KYB se degrada en conjeturas: una sola bandera de "pendiente" no te dice nada sobre qué verificación está retrasando las cosas o qué acción la desbloquearía. Con los estados por característica, puedes enrutar con precisión — pedir al solicitante que vuelva a enviar un documento, poner en cola una coincidencia de AML de entidad para revisión de un analista, pedir a un UBO que termine su KYC — en lugar de fallar toda la verificación.

Los webhooks son importantes porque KYB es asíncrono. Los datos de registro, el OCR de documentos y los resultados de detección llegan en diferentes momentos, y la revisión humana lleva aún más tiempo. Sondear los cambios es ineficiente y lento; los webhooks envían el cambio en el momento en que ocurre, para que tus registros reflejen la realidad sin que un trabajo cron golpee la API.

Detalles técnicos

Se crea una sesión KYB contra la API unificada /v3/ y reporta su estado del 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"
  }'

Un webhook status.updated lleva el estado de la sesión y los estados por característica:

{
  "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 de sesión. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.

Estados de características. Cada uno de kyb_registry, kyb_company_aml, kyb_documents y kyb_key_people reporta uno de: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, o AWAITING_USER.

Webhooks. Para sesiones: status.updated (cambios de ciclo de vida) y data.updated (datos enriquecidos), ambos llevando session_kind: "business". Para entidades gestionadas: business.status.updated y business.data.updated.

Precio. $2.00 por verificación de empresa.

Gestión de la entidad comercial

Una vez que una empresa es verificada, se convierte en una entidad que gestionas a través de la API de negocios:

• POST /v3/businesses/create/ — registrar una entidad comercial.
• GET /v3/businesses/ — listar negocios gestionados.
• GET /v3/businesses/{vendor_data}/ — obtener un negocio por su referencia vendor_data.
• PATCH .../update-status/ — cambiar el estado de la entidad.

La entidad lleva su propio estado, independiente de la sesión de verificación: ACTIVE (en buen estado), FLAGGED (bajo revisión por una señal de riesgo), o BLOCKED (suspendida). Esta es la capa operativa — una empresa puede completar una sesión APPROVED y luego ser FLAGGED porque la monitorización detectó algo. Los cambios en la entidad emiten business.status.updated y business.data.updated para que los sistemas posteriores se mantengan actualizados.

El ciclo de vida, de principio a fin

Una verificación típica recorre las capas en orden. La sesión se abre en NOT_STARTED, pasa a IN_PROGRESS a medida que se ejecutan las características, y cada característica se resuelve — registro APPROVED, documentos quizás RESUB_REQUESTED hasta que llega una carga limpia, AML de la empresa IN_REVIEW hasta que un analista aprueba una coincidencia, personas clave APPROVED. Cuando todas las características se resuelven, la sesión se establece en APPROVED, DECLINED o IN_REVIEW. A partir de ahí, la empresa entra en gestión como una entidad ACTIVE, y su estado puede pasar más tarde a FLAGGED o BLOCKED según lo dicte la supervisión continua — cada transición se te envía mediante webhook.

Casos de uso

• Los mercados dirigen a los vendedores con precisión: volver a enviar un documento, finalizar el KYC de un UBO o retener una coincidencia de AML de entidad, sin fallar todo el proceso de incorporación.
• Las plataformas Fintech y bancarias mantienen los registros de cuentas corporativas sincronizados con webhooks en lugar de sondeos, y marcan o bloquean entidades a medida que cambia el riesgo.
• Los proveedores de préstamos rastrean el estado de cada verificación de suscripción y actualizan el estado del prestatario a través de la API de gestión.
• Las plataformas Crypto B2B mantienen un ciclo de vida auditable de cada entidad contraparte desde la verificación hasta el estado continuo.

Cómo integrarse con Didit

1. Construye el flujo de trabajo. En la Consola de Negocios, crea un flujo de trabajo KYB con las características que necesites.
2. Crea la sesión. POST /v3/session/ con tu workflow_id de KYB y una referencia vendor_data.
3. Suscríbete a los webhooks. Maneja status.updated y data.updated (session_kind: business) para sesiones, y business.status.updated / business.data.updated para entidades gestionadas.
4. Gestiona entidades. Usa POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/ y PATCH .../update-status/ para mantener cada empresa ACTIVE, FLAGGED o BLOCKED.

Debido a que todo está en la API unificada /v3/, el mismo modelo de ciclo de vida se extiende a KYC, monitoreo y KYB — una máquina de estados consistente para toda la plataforma de identidad y fraude.

Preguntas frecuentes

¿Cuáles son los estados de la sesión KYB?

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

¿Qué estados reportan las características individuales?

Cada uno de kyb_registry, kyb_company_aml, kyb_documents y kyb_key_people reporta NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED o AWAITING_USER.

¿A qué webhooks debo suscribirme?

Para sesiones, status.updated y data.updated (con session_kind: business). Para entidades comerciales gestionadas, business.status.updated y business.data.updated.

¿Cómo cambio el estado de una empresa después de la verificación?

Usa la API de gestión — PATCH .../update-status/ — para establecer la entidad en ACTIVE, FLAGGED o BLOCKED.

¿Cuánto cuesta una verificación KYB?

$2.00 por empresa para la verificación completa — registro, UBO, funcionarios y AML de la entidad.

¿Listo para empezar?

Lee la descripción general de Verificación de Negocios en la documentación, mira cómo encaja con el resto de la plataforma en la página del producto Verificación de Negocios, y consulta los precios transparentes por llamada en la página de precios. Cuando estés listo, empieza gratis — 500 verificaciones KYC gratuitas cada mes y verificación de negocios a $2.00 por empresa.