Vinculación de vendor_data: asocia IDs a entidades

vendor_data es el identificador que proporcionas en cada sesión y transacción para vincular cada una a una entidad de usuario o de empresa. Es el campo más importante para la agregación de entidades: si lo configuras bien, todas las funciones posteriores (historial del perfil, monitorización de transacciones, aplicación de la lista de bloqueo, AML continuo) funcionan sin problemas.

Qué es

vendor_data es una cadena que eliges tú. Didit lo trata como un identificador opaco y no interpreta su contenido. Valores habituales:

Tu sistema	Valores adecuados de `vendor_data`
Base de datos interna de usuarios	`user_1234`, `uuid-v4` del usuario
ID visible para el cliente	`CUST-2026-00042`, correo electrónico con hash
SaaS multiinquilino	`tenant_acme:user_1234`
Plataforma B2B	`company-hq-global`, `tax-id-US-123456789`

No incluyas datos personales identificables (correos electrónicos, números de teléfono, identificaciones fiscales sin procesar) directamente en vendor_data. Aplícales un hash o un prefijo. vendor_data aparece en los payloads de webhook y se conserva indefinidamente mientras exista la entidad.

Cómo vincula los elementos

Cuando envías una sesión o una transacción con un valor de vendor_data:

Didit busca en tu aplicación la entidad con ese vendor_data.
Si existe, el nuevo objeto se vincula a esa entidad.
Si no existe, Didit crea la entidad (con status: ACTIVE) y vincula el nuevo objeto.

Esto se aplica a:

POST /v3/session/: sesiones de KYC y de verificación de empresas (KYB)
POST /v3/transactions/: transacciones (tanto para el solicitante como para la contraparte)
Los campos applicant.vendor_data / counterparty.vendor_data dentro de los payloads de transacciones

Unicidad y ámbito

vendor_data es único por aplicación, no de forma global en todo Didit:

Ámbito	Garantía de unicidad
Dentro de una aplicación	`vendor_data` es único por tipo de entidad (usuario y empresa son espacios de nombres independientes)
Entre aplicaciones de tu organización	`vendor_data` no se comparte: el mismo valor en dos aplicaciones se refiere a dos entidades distintas
Entre organizaciones	No se comparte: cada organización tiene sus propias tablas de entidades

Esto significa que puedes usar el mismo vendor_data en una aplicación de staging y en una de producción sin colisiones, y que puedes tener un usuario user-42 y una empresa user-42 sin colisión (aunque no se recomienda por motivos de claridad).

Qué ocurre si omites `vendor_data`

Puedes crear una sesión sin vendor_data. En ese caso:

No se crea ninguna entidad para la sesión.
La sesión queda huérfana: no aparecerá en ningún perfil de usuario ni de empresa.
Más adelante no podrás buscar la sesión por vendor_data, solo por session_id.

Usa este patrón solo para verificaciones anónimas o puntuales en las que no se necesite agregación de entidades. En cualquier integración que implique reverificación, transacciones o monitorización continua, proporciona siempre vendor_data.

Ejemplo: crear una entidad por adelantado y después ejecutar sesiones

# 1. Pre-create the User with initial metadata
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_date": "2026-04-01" }
  }'

# 2. Create a User Verification (KYC) session for the same user
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_kyc_standard",
    "vendor_data": "user-42"
  }'

# 3. Later, submit a transaction tied to the same user
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "tx-0001",
    "direction": "OUTBOUND",
    "amount": "500.00",
    "currency": "EUR",
    "applicant": { "vendor_data": "user-42" },
    "counterparty": { "name": "Acme Corp" }
  }'

Las tres llamadas quedan vinculadas a la misma entidad de usuario. Cuando más adelante ejecutes GET /v3/users/user-42/, verás el número de sesiones, los contadores de aprobadas y rechazadas, las transacciones vinculadas y los datos de perfil más recientes.

Migración de ID externos de usuarios

Si adoptas Didit después de haber usado otro proveedor de KYC, pasa tus ID de usuario estables existentes como vendor_data desde el primer día. Así te resultará fácil:

Conciliar los datos de Didit con tu base de datos interna.
Cargar de forma masiva usuarios históricos mediante la importación CSV de la consola antes de ejecutar cualquier sesión.
Conservar las relaciones cuando más adelante migres a Didit para la monitorización de transacciones.

Reglas, convenciones y buenas prácticas

Regla	Motivo
Elige un identificador canónico por entidad y no lo cambies nunca	Los cambios crean una entidad nueva y dejan huérfano el historial
Añade a los valores de `vendor_data` un prefijo según el tipo de entidad (`user_...`, `biz_...`)	Evita colisiones accidentales entre espacios de nombres en tu propio código
Mantén estable el uso de mayúsculas y minúsculas en `vendor_data`	Didit no normaliza mayúsculas y minúsculas
Mantén la longitud de `vendor_data` por debajo de 128 caracteres	Cabe holgadamente en los índices de base de datos
No expongas nunca datos personales identificables sin procesar	`vendor_data` aparece en webhooks, registros de auditoría y respuestas de la API

Próximos pasos

Visión general de usuarios

Análisis detallado de las entidades de usuario y sus operaciones.

Visión general de empresas

Análisis detallado de las entidades de empresa y sus operaciones.

Crear sesión

Inicia una verificación para un dato de proveedor.

Crear transacción

Envía una transacción vinculada a una entidad.

Visión general

Precios

Flujos y verificación

Revisión y operaciones

Entidades (usuarios y empresas)

Ajustes y personalización

Seguridad y cumplimiento

Didit Academy

Recursos

Vinculación de vendor_data: asocia IDs a entidades

Qué es

Cómo vincula los elementos

Unicidad y ámbito

Qué ocurre si omites `vendor_data`

Ejemplo: crear una entidad por adelantado y después ejecutar sesiones

Migración de ID externos de usuarios

Reglas, convenciones y buenas prácticas

Próximos pasos

Visión general de usuarios

Visión general de empresas

Crear sesión

Crear transacción

​Qué es

​Cómo vincula los elementos

​Unicidad y ámbito

​Qué ocurre si omites vendor_data

​Ejemplo: crear una entidad por adelantado y después ejecutar sesiones

​Migración de ID externos de usuarios

​Reglas, convenciones y buenas prácticas

​Próximos pasos

Visión general de usuarios

Visión general de empresas

Crear sesión

Crear transacción

Qué es

Cómo vincula los elementos

Unicidad y ámbito

Qué ocurre si omites `vendor_data`

Ejemplo: crear una entidad por adelantado y después ejecutar sesiones

Migración de ID externos de usuarios

Reglas, convenciones y buenas prácticas

Próximos pasos