> ## 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.

# Vinculação de vendor_data: associe IDs a entidades

> O identificador vendor_data vincula seu sistema à Didit, unindo sessões, transações e entidades User/Business em um perfil. Pagamento por chamada.

Prompt de vinculação com vendor\_data
Copiar o prompt para a área de transferência

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

Colar em

`vendor_data` é o identificador que você informa em cada sessão e transação para vinculá-lo a uma entidade de [Usuário](https://docs.didit.me/pt-br/entities/users/overview.md) ou de [Empresa](https://docs.didit.me/pt-br/entities/businesses/overview.md). É o campo mais importante para a agregação de entidades: configure-o corretamente e todos os recursos que dependem dele (histórico de perfil, monitoramento de transações, aplicação da lista de bloqueio, AML contínuo) funcionam sem atrito.

## O que é

`vendor_data` é uma **string** escolhida por você. A Didit o trata como um identificador opaco e não interpreta o seu conteúdo. Valores típicos:

| Seu sistema | Bons valores de `vendor_data` |
| - | - |
| Banco de dados interno de usuários | `user_1234`, `uuid-v4` do usuário |
| ID exibido ao cliente | `CUST-2026-00042`, e-mail com hash |
| SaaS multi-tenant | `tenant_acme:user_1234` |
| Plataforma B2B | `company-hq-global`, `tax-id-US-123456789` |

> [!WARNING]
>
> **Não** coloque dados pessoais (e-mails, números de telefone, identificações fiscais em texto puro) diretamente em `vendor_data`. Aplique hash ou um prefixo. O `vendor_data` aparece nos payloads de webhook e fica armazenado por tempo indeterminado enquanto a entidade existir.

## Como funciona a vinculação

```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
```

Quando você envia uma sessão ou transação com um valor de `vendor_data`:

1. A Didit procura a entidade na sua aplicação com esse `vendor_data`.
2. Se ela existir, o novo objeto é vinculado a essa entidade.
3. Se ela não existir, a Didit cria a entidade (com `status: ACTIVE`) e vincula o novo objeto.

Isso vale para:

* `POST /v3/session/`: sessões de KYC e de Verificação de empresas (KYB)
* `POST /v3/transactions/`: transações (tanto para o requerente quanto para a contraparte)
* Os campos `applicant.vendor_data` / `counterparty.vendor_data` dentro dos payloads de transação

## Unicidade e escopo

`vendor_data` é **único por aplicação**, e não globalmente em toda a Didit:

| Escopo | Garantia de unicidade |
| - | - |
| Dentro de uma aplicação | `vendor_data` é único por tipo de entidade (Usuário e Empresa são espaços de nomes separados) |
| Entre aplicações da sua organização | `vendor_data` **não** é compartilhado: o mesmo valor em duas aplicações se refere a duas entidades diferentes |
| Entre organizações | Não é compartilhado: cada organização tem as suas próprias tabelas de entidades |

Isso significa que você pode usar o mesmo `vendor_data` em uma aplicação de staging e em uma de produção sem colisões, e pode ter um Usuário `user-42` e uma Empresa `user-42` sem colisão (embora isso não seja recomendado, por clareza).

## O que acontece se você omitir `vendor_data`

Você pode criar uma sessão sem `vendor_data`. Nesse caso:

* Nenhuma entidade é criada para a sessão.
* A sessão fica órfã: ela não aparece em nenhum perfil de Usuário ou de Empresa.
* Depois, você não consegue buscar a sessão por `vendor_data`, apenas por `session_id`.

Use esse padrão somente para verificações anônimas ou pontuais, em que não há necessidade de agregação de entidades. Em toda integração que envolva reverificação, transações ou monitoramento contínuo, sempre informe `vendor_data`.

## Exemplo: criar previamente uma entidade e, depois, executar sessões

```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" }
  }'
```

As três chamadas ficam vinculadas à mesma entidade de usuário. Quando você fizer `GET /v3/users/user-42/`, você verá a contagem de sessões, os contadores de sessões aprovadas/recusadas, as transações vinculadas e os dados mais recentes do perfil.

## Migração de IDs externos

Se você está adotando a Didit depois de usar outro fornecedor de KYC, envie os IDs de usuário estáveis que você já tem como `vendor_data` desde o primeiro dia. Isso facilita:

* Conciliar os dados da Didit com o seu banco de dados interno.
* Carregar em massa os usuários históricos pela importação de CSV no console antes de executar qualquer sessão.
* Preservar os relacionamentos quando mais tarde você também migrar para a Didit no monitoramento de transações.

## Regras, convenções e boas práticas

| Regra | Por quê |
| - | - |
| Escolha um identificador canônico por entidade e nunca o altere | Alterações criam uma nova entidade e deixam o histórico órfão |
| Use prefixos nos valores de `vendor_data` por tipo de entidade (`user_...`, `biz_...`) | Evita colisões acidentais entre namespaces no seu próprio código |
| Mantenha `vendor_data` estável, inclusive em maiúsculas e minúsculas | A Didit não normaliza maiúsculas e minúsculas |
| Mantenha `vendor_data` com menos de 128 caracteres | Cabe com folga em índices de banco de dados |
| Nunca exponha dados pessoais brutos | `vendor_data` aparece em webhooks, registros de auditoria e respostas da API |

## Próximos passos

> [card] [Visão geral de usuários](https://docs.didit.me/pt-br/entities/users/overview.md)
>
> Aprofunde-se nas entidades de Usuário e nas suas operações.

> [card] [Visão geral de empresas](https://docs.didit.me/pt-br/entities/businesses/overview.md)
>
> Aprofunde-se nas entidades de Empresa e nas suas operações.

> [card] [Criar sessão](https://docs.didit.me/pt-br/sessions-api/create-session.md)
>
> Inicie uma verificação para um vendor\_data.

> [card] [Criar transação](https://docs.didit.me/pt-br/management-api/transactions/create.md)
>
> Envie uma transação vinculada a uma entidade.


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