Guía de integración KYB: arquitectura y patrones

Esta guía complementa la guía de inicio rápido. Cubre la arquitectura, cada decisión de integración y los patrones operativos que hacen que KYB sea fiable en producción.

Arquitectura

Autenticación

Todas las solicitudes requieren el encabezado x-api-key con la clave de API de tu aplicación. Consulta Autenticación de la API para la rotación de claves, la separación de entornos y los permisos.

Creación de sesiones

Un único endpoint: POST /v3/session/. El tipo del flujo de verificación (workflow) determina si la sesión es KYC o KYB, así que no hace falta ningún indicador explícito de “empresa”. Campos recomendados al crear la sesión:

Campo	Propósito
`workflow_id`	Obligatorio: hace referencia a tu flujo KYB.
`vendor_data`	Tu identificador de la empresa. Vincula la sesión a una entidad empresarial.
`callback_url`	Opcional: adónde redirigir al usuario al finalizar.
`expected_details`	Opcional: `{ company_name, registry_country, registration_number }`. Rellena de antemano la búsqueda en el registro de empresas: el país de constitución queda preseleccionado y bloqueado (`registry_country` como `XX`, o `XX-YY` para registros estatales, p. ej. `US-CA`), los campos de nombre de la empresa y número de registro se rellenan de antemano y la búsqueda con los datos proporcionados se ejecuta automáticamente, combinando ambos identificadores cuando están presentes los dos. Solo se rellenan previamente los campos: las discrepancias no generan advertencias.
`metadata`	JSON opcional asociado a la sesión.

Esquema completo: crear sesión.

Entrega del enlace alojado

El url de la respuesta es un enlace de verificación alojado. Opciones de entrega:

Envíalo por correo electrónico desde tu propia plataforma.
Insértalo como enlace en tu interfaz de onboarding.
Ábrelo en un webview dentro de la aplicación (iOS / Android / React Native).

Puedes personalizar la experiencia alojada (logotipo, color, dominio, plantillas de correo electrónico) mediante Marca blanca.

Polling frente a webhooks

Los webhooks son el patrón recomendado. Didit envía mediante POST los eventos de finalización a tu endpoint suscrito en cuanto termina el procesamiento. El polling se admite durante el desarrollo o cuando tu endpoint de webhook no es accesible:

Consulta GET /v3/session/{id}/decision/ con backoff exponencial (cada 10 s al principio, hasta 60 s).
Deja de consultar cuando status sea "Approved", "Declined" o "In Review".

Consultar con mucha frecuencia puede superar los límites de solicitudes. En producción, prefiere siempre los webhooks.

Gestión de webhooks

Suscríbete a los eventos que te interesen. Los mismos eventos cubren KYC y KYB, con session_kind: "business" dentro del payload para identificar los eventos de sesiones de empresa:

status.updated: cambió el estado de la sesión. Filtra por session_kind === "business" para las sesiones KYB.
data.updated: un revisor editó los datos del registro o las personas clave en la consola, o el registro notificó un cambio. No se envía cuando el solicitante sube un documento o envía las personas clave: para eso, usa status.updated. Se aplica el mismo filtro de session_kind.
business.status.updated / business.data.updated: cambió la entidad de empresa vinculada.

Catálogo completo de eventos: webhooks de KYB. Verificación de firma y semántica de reintentos: referencia de webhooks.

Gestión de las decisiones

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;
}

Consulta Estados de KYB para la máquina de estados completa y Advertencias de KYB para las etiquetas que explican una decisión.

Flujo de reenvío

Cuando una sesión de Verificación de empresas (KYB) pasa a Resubmitted (o una función se marca para reenvío), la empresa debe subir datos corregidos o adicionales. Puedes:

Volver a enviar el mismo url: el flujo alojado retoma el punto en que se necesita el reenvío.
Reemitir el enlace inactivo de una persona clave: una persona cuya sesión KYC asociada se eliminó, o expiró antes de que la persona la iniciara, recibe una nueva sesión con Regenerar la sesión KYC de personas clave.
Abrir un caso en la Business Console para hacer seguimiento interno de los intercambios.

Ejecuta los pasos desde tu propio front end

Los pasos de documentos y de personas clave también se pueden controlar desde tu servidor con tu clave de API, de modo que tú conservas la interfaz de usuario y Didit se encarga de la verificación y de la decisión. Cada llamada está limitada a la sesión KYB, necesita el permiso write:businesses (leer las partes extraídas también acepta read:businesses o read:sessions) y ejecuta las mismas comprobaciones, la misma facturación y la misma transición entre pasos que la página alojada.

Sube los documentos corporativos mientras la sesión está en el paso de documentos KYB.
Lee las partes que se mencionan en los documentos, incluidos los accionistas y los porcentajes de propiedad, y muéstraselas a tu solicitante.
Crea, edita y elimina borradores de partes. Un borrador no se considera declarado y no cuesta nada.
Envía los borradores. Didit decide qué partes deben verificarse, crea una sesión KYC para cada una y devuelve su kyc_session_url para que lo envíes o lo incrustes.
Lee la decisión consolidada de la sesión, igual que en el flujo alojado.

Una llamada realizada mientras la sesión está en otro paso responde 409 kyb_step_mismatch con el paso en el que se encuentra, y una sesión finalizada responde 409 kyb_session_not_writable.

Agregación del perfil de empresa

Si pasas vendor_data al crear la sesión, Didit agrupa todas las sesiones de esa empresa en una única entidad de empresa. Usa el mapa features de la entidad para responder “¿está esta empresa completamente verificada ahora mismo?” sin recorrer las sesiones. Ventajas:

Los flujos periódicos de re-KYB se añaden al mismo perfil.
Las transacciones monitorizadas con el mismo vendor_data llevan el contexto de riesgo de la empresa.
Los UBO y directivos vinculados a entidades de usuario establecen relaciones entre entidades.

Buenas prácticas

Práctica	Por qué
Envía siempre `vendor_data`	Sin él, la sesión queda huérfana y no se puede agrupar.
Usa webhooks, no polling	Menor latencia y sin presión sobre el límite de solicitudes.
Verifica las firmas de los webhooks	Evita eventos suplantados.
Guarda el `session_id` en tu sistema	Es necesario para recuperar la decisión y generar archivos PDF.
Etiqueta las sesiones con `metadata`	Simplifica los informes y la depuración.
Configura un flujo de verificación (workflow) de prueba	Usa un flujo de sandbox para las pruebas de integración antes de pasar a producción.

Gestión de errores

Escenario	Respuesta
`workflow_id` no válido	`400 Bad Request`
Sesión duplicada con el mismo `vendor_data`	Crea una sesión nueva. Es así por diseño, ya que se espera que haya reverificación.
País de la empresa fuera de los países permitidos del flujo	La consulta al registro genera la advertencia `KYB_COUNTRY_RESTRICTED`.
Caída del proveedor del registro durante la búsqueda de la empresa	`POST /v3/kyb/search/` devuelve `502` con `code: "kyb_registry_provider_unavailable"`. No se factura: reintenta, o crea una rama en función de `code` para ofrecer la introducción manual de los datos de la empresa. En el flujo alojado de Didit, la empresa se dirige automáticamente a la introducción manual de sus datos en lugar de mostrar un error que solo permite reintentar. Consulta Búsqueda en registros KYB.
Límite de solicitudes	`429 Too Many Requests` con el encabezado `Retry-After`.

Referencia completa de límites de solicitudes.

Próximos pasos

Webhooks

Todos los eventos y payloads de KYB.

Estados

Referencia de la máquina de estados.

Esquema de respuesta

Cómo interpretar la decisión de KYB.

Primeros pasos

Funciones

Perfiles de empresa

Referencia

Consola

Guía de integración KYB: arquitectura y patrones

Arquitectura

Autenticación

Creación de sesiones

Entrega del enlace alojado

Polling frente a webhooks

Gestión de webhooks

Gestión de las decisiones

Flujo de reenvío

Ejecuta los pasos desde tu propio front end

Agregación del perfil de empresa

Buenas prácticas

Gestión de errores

Próximos pasos

Webhooks

Estados

Esquema de respuesta

​Arquitectura

​Autenticación

​Creación de sesiones

​Entrega del enlace alojado

​Polling frente a webhooks

​Gestión de webhooks

​Gestión de las decisiones

​Flujo de reenvío

​Ejecuta los pasos desde tu propio front end

​Agregación del perfil de empresa

​Buenas prácticas

​Gestión de errores

​Próximos pasos

Webhooks

Estados

Esquema de respuesta

Arquitectura

Autenticación

Creación de sesiones

Entrega del enlace alojado

Polling frente a webhooks

Gestión de webhooks

Gestión de las decisiones

Flujo de reenvío

Ejecuta los pasos desde tu propio front end

Agregación del perfil de empresa

Buenas prácticas

Gestión de errores

Próximos pasos