> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Vinculació de vendor_data: enllaça IDs amb entitats

> Didit vincula el vendor_data del teu sistema amb sessions, transaccions i entitats d'usuari o empresa. Pagament per crida.

Prompt de vinculació de vendor\_data
Copia el prompt al porta-retalls

<pre>
  \`\`\`\`# Goal — link every session, transaction, and entity together using `vendor_data`

  `vendor_data` is the string identifier you choose and pass on every API call to bind it to a persistent [User](https://docs.didit.me/entities/users/overview.md) or [Business](https://docs.didit.me/entities/businesses/overview.md) entity. Get this right once and you never have to re-key history afterwards.

  ## Rules

  * `vendor_data` is **opaque** to Didit. Use your stable internal customer id.
  * Choose one canonical id per entity and never change it. Changing it orphans history under a new entity.
  * Prefix by entity type when convenient (`user_...`, `biz_...`) to avoid collisions in your own code.
  * Keep it under 128 chars, case-sensitive stable. Hard limit is 2000 bytes (UTF-8 encoded) - anything over that is rejected with a 400 rather than accepted.
  * **Never put raw PII in it** — it surfaces in webhooks, logs, and API responses.
  * Uniqueness is per application × entity type. User `user-42` and Business `user-42` are different entities (but don't do this).

  ## Where it goes

  | API | Field |
  | - | - |
  | `POST /v3/session/` | top-level `vendor_data` (KYC and KYB) |
  | `POST /v3/transactions/` | top-level `vendor_data` and `applicant.vendor_data` / `counterparty.vendor_data` |
  | `POST /v3/users/create/` / `POST /v3/businesses/create/` | `vendor_data` |
  | `GET /v3/sessions?vendor_data=...` | query param to retrieve history |
  | `GET /v3/users/{vendor_data}/` / `GET /v3/businesses/{vendor_data}/` | path param |

  ## Pattern — pre-create the entity, then run a session

  ```bash
  # 1) Seed the entity with metadata before any session
  curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: $DIDIT_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) Run a KYC session linked to the same entity
  curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "workflow_id": "$WORKFLOW_ID",
  "vendor_data": "user-42",
  "callback": "https://myapp.com/return"
  }'

  # 3) Later, retrieve every session for the entity
  curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  --data-urlencode "vendor_data=user-42"
  ```

  ## Auto-create semantics

  If you create a session with a new `vendor_data` and no entity exists, Didit creates the entity automatically with `status: ACTIVE` and links the session.

  ## Failure modes

  * Missing `vendor_data` on session create → session is orphaned, won't appear in any entity profile, cannot be filtered by `vendor_data` later (only by `session_id`).
  * Different case (`User-42` vs `user-42`) → two separate entities. Pick a casing convention and stick to it.
  * Same `vendor_data` across staging and prod apps → no collision; `vendor_data` is scoped per application.

  ## Sources of truth

  * /entities/users/operations — full User CRUD
  * /entities/businesses/operations — full Business CRUD
  * /sessions-api/create-session — session body shape
  * /integration/integration-prompt — canonical end-to-end prompt\`\`\`\`
</pre>

Enganxa a

`vendor_data` és l'identificador que proporciones en cada sessió i transacció per vincular-les a una entitat [Usuari](https://docs.didit.me/ca/entities/users/overview.md) o [Empresa](https://docs.didit.me/ca/entities/businesses/overview.md). És el camp més important per a l'agregació d'entitats: si el fas bé, totes les funcionalitats posteriors (historial del perfil, monitoratge de transaccions, aplicació de la llista de bloqueig, AML continu) funcionen sense problemes.

## Què és

`vendor_data` és una **cadena** que tries tu. Didit el tracta com un identificador opac i no interpreta el contingut. Valors típics:

| El teu sistema | Valors recomanats de `vendor_data` |
| - | - |
| Base de dades interna d'usuaris | `user_1234`, `uuid-v4` de l'usuari |
| Identificador visible per al client | `CUST-2026-00042`, correu electrònic amb hash |
| SaaS multiinquilí | `tenant_acme:user_1234` |
| Plataforma B2B | `company-hq-global`, `tax-id-US-123456789` |

> [!WARNING]
>
> **No** posis dades personals (correus electrònics, números de telèfon, NIF o identificadors fiscals en brut) directament a `vendor_data`. Aplica-hi un hash o un prefix. `vendor_data` apareix als payloads dels webhooks i es conserva indefinidament mentre existeixi l'entitat.

## Com vincula les coses

```mermaid theme={null}
flowchart TD
    subgraph YourSystem["Your system"]
      Customer["Customer record: user-42"]
    end
    subgraph Didit["Didit platform"]
      Entity["User entity (vendor_data = user-42)"]
      S1[Session #1]
      S2[Session #2]
      T1[Transaction #1]
      T2[Transaction #2]
      F[Face biometric]
    end
    Customer -.vendor_data.-> Entity
    S1 --> Entity
    S2 --> Entity
    T1 --> Entity
    T2 --> Entity
    F --> Entity
```

Quan envies una sessió o una transacció amb un valor de `vendor_data`:

1. Didit busca a la teva aplicació l'entitat amb aquest `vendor_data`.
2. Si existeix, el nou objecte es vincula a aquesta entitat.
3. Si no existeix, Didit crea l'entitat (amb `status: ACTIVE`) i vincula el nou objecte.

Això és vàlid per a:

* `POST /v3/session/`: sessions de verificació KYC i de verificació d'empreses (KYB)
* `POST /v3/transactions/`: transaccions (tant per al sol·licitant com per a la contrapart)
* Els camps `applicant.vendor_data` i `counterparty.vendor_data` dels payloads de transaccions

## Unicitat i àmbit

`vendor_data` és **únic per aplicació**, no a tot Didit:

| Àmbit | Garantia d'unicitat |
| - | - |
| Dins d'una aplicació | `vendor_data` és únic per tipus d'entitat (Usuari i Empresa són espais de noms separats) |
| Entre aplicacions de la teva organització | `vendor_data` **no** es comparteix: el mateix valor en dues aplicacions fa referència a dues entitats diferents |
| Entre organitzacions | No es comparteix: cada organització té les seves pròpies taules d'entitats |

Això vol dir que pots fer servir el mateix `vendor_data` en una aplicació de preproducció i en una de producció sense col·lisions, i que pots tenir un Usuari `user-42` i una Empresa `user-42` sense col·lisió (tot i que es desaconsella per claredat).

## Què passa si omets `vendor_data`

Pots crear una sessió sense `vendor_data`. En aquest cas:

* No es crea cap entitat per a la sessió.
* La sessió queda òrfena: no apareixerà al perfil de cap Usuari ni d'Empresa.
* No pots buscar la sessió més endavant per `vendor_data`, només per `session_id`.

Fes servir aquest patró només per a verificacions anònimes o puntuals en què no calgui l'agregació d'entitats. Per a qualsevol integració que impliqui reverificació, transaccions o monitoratge continu, proporciona sempre `vendor_data`.

## Exemple: crear una entitat per avançat i després executar sessions

```bash theme={null}
# 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" }
  }'
```

Les tres crides estan vinculades a la mateixa entitat Usuari. Quan després facis `GET /v3/users/user-42/`, veuràs el nombre de sessions, els comptadors d'aprovades i rebutjades, les transaccions vinculades i les dades més recents del perfil.

## Migració d'identificadors externs

Si adoptes Didit després d'un proveïdor KYC existent, passa els teus identificadors d'usuari estables actuals com a `vendor_data` des del primer dia. Així és més fàcil:

* Conciliar les dades de Didit amb la teva base de dades interna.
* Carregar en bloc els usuaris històrics mitjançant la importació CSV de la consola abans d'executar cap sessió.
* Preservar les relacions quan més endavant migris a Didit per al monitoratge de transaccions.

## Regles, convencions i bones pràctiques

| Regla | Motiu |
| - | - |
| Tria un únic identificador canònic per entitat i no el canviïs mai | Els canvis creen una entitat nova i deixen l'historial orfe |
| Posa un prefix als valors de `vendor_data` segons el tipus d'entitat (`user_...`, `biz_...`) | Evita col·lisions accidentals entre espais de noms al teu propi codi |
| Mantén els valors de `vendor_data` estables i sensibles a majúscules i minúscules | Didit no normalitza les majúscules i minúscules |
| Mantén la longitud de `vendor_data` per sota de 128 caràcters | Encaixa bé en els índexs de la base de dades |
| No exposis mai dades personals en brut | `vendor_data` apareix als webhooks, als registres d'auditoria i a les respostes de l'API |

## Següents passos

> [card] [Visió general dels usuaris](https://docs.didit.me/ca/entities/users/overview.md)
>
> Anàlisi detallada de les entitats Usuari i de les seves operacions.

> [card] [Visió general de les empreses](https://docs.didit.me/ca/entities/businesses/overview.md)
>
> Anàlisi detallada de les entitats Empresa i de les seves operacions.

> [card] [Crear sessió](https://docs.didit.me/ca/sessions-api/create-session.md)
>
> Inicia una verificació per a un vendor\_data.

> [card] [Crear transacció](https://docs.didit.me/ca/management-api/transactions/create.md)
>
> Envia una transacció vinculada a una entitat.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.