Vinculação de vendor_data: associe IDs a entidades

vendor_data é o identificador que você informa em cada sessão e transação para vinculá-lo a uma entidade de Usuário ou de Empresa. É 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`

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

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

A Didit procura a entidade na sua aplicação com esse vendor_data.
Se ela existir, o novo objeto é vinculado a essa entidade.
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

# 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

Visão geral de usuários

Aprofunde-se nas entidades de Usuário e nas suas operações.

Visão geral de empresas

Aprofunde-se nas entidades de Empresa e nas suas operações.

Criar sessão

Inicie uma verificação para um vendor_data.

Criar transação

Envie uma transação vinculada a uma entidade.

Visão geral

Preços

Fluxos e verificação

Revisão e operações

Entidades (usuários e empresas)

Configurações e personalização

Segurança e conformidade

Didit Academy

Recursos

Vinculação de vendor_data: associe IDs a entidades

O que é

Como funciona a vinculação

Unicidade e escopo

O que acontece se você omitir `vendor_data`

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

Migração de IDs externos

Regras, convenções e boas práticas

Próximos passos

Visão geral de usuários

Visão geral de empresas

Criar sessão

Criar transação

​O que é

​Como funciona a vinculação

​Unicidade e escopo

​O que acontece se você omitir vendor_data

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

​Migração de IDs externos

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

​Próximos passos

Visão geral de usuários

Visão geral de empresas

Criar sessão

Criar transação

O que é

Como funciona a vinculação

Unicidade e escopo

O que acontece se você omitir `vendor_data`

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

Migração de IDs externos

Regras, convenções e boas práticas

Próximos passos