Ligação de vendor_data: associar IDs a entidades

vendor_data é o identificador que fornece em cada sessão e transação para as ligar a uma entidade Utilizador ou Empresa. É o campo mais importante para a agregação de entidades: se estiver correto, todas as funcionalidades a jusante (histórico do perfil, monitorização de transações, aplicação de listas de bloqueio, monitorização AML contínua) funcionam sem falhas.

O que é

vendor_data é uma string que escolhe. A Didit trata-o como um identificador opaco e não interpreta o seu conteúdo. Valores típicos:

O seu sistema	Bons valores de `vendor_data`
Base de dados interna de utilizadores	`user_1234`, `uuid-v4` do utilizador
ID voltado para o cliente	`CUST-2026-00042`, e-mail com hash
SaaS multi-inquilino	`tenant_acme:user_1234`
Plataforma B2B	`company-hq-global`, `tax-id-US-123456789`

Não coloque dados pessoais (e-mails, números de telefone, números de identificação fiscal em bruto) diretamente em vendor_data. Aplique-lhes hash ou adicione-lhes um prefixo. O vendor_data aparece nos payloads dos webhooks e fica armazenado indefinidamente enquanto a entidade existir.

Como liga as coisas entre si

Quando submete uma sessão ou transação com um valor de vendor_data:

A Didit procura na sua aplicação a entidade com esse vendor_data.
Se existir, o novo objeto fica ligado a essa entidade.
Se não existir, a Didit cria a entidade (com status: ACTIVE) e liga o novo objeto.

Isto aplica-se a:

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

Unicidade e âmbito

vendor_data é único por aplicação, e não globalmente na Didit:

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

Isto significa que pode usar o mesmo vendor_data numa aplicação de testes e numa aplicação de produção sem colisões, e pode ter um Utilizador user-42 e uma Empresa user-42 sem colisão (embora isso seja desaconselhado por clareza).

O que acontece se omitir `vendor_data`

Pode criar uma sessão sem vendor_data. Nesse caso:

Não é criada nenhuma entidade para a sessão.
A sessão fica órfã: não aparece no perfil de nenhum Utilizador ou Empresa.
Não é possível procurar a sessão mais tarde por vendor_data, apenas por session_id.

Use este padrão apenas para verificações anónimas ou pontuais em que não seja necessária agregação de entidades. Em qualquer integração que envolva reverificação, transações ou monitorização contínua, forneça sempre vendor_data.

Exemplo: pré-criar 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 ligadas à mesma entidade Utilizador. Quando depois fizer GET /v3/users/user-42/, verá a contagem de sessões, os contadores de aprovações e recusas, as transações ligadas e os dados de perfil mais recentes.

Migrar IDs externos

Se estiver a adotar a Didit depois de um fornecedor de KYC existente, passe os seus IDs de utilizador estáveis como vendor_data desde o primeiro dia. Isto facilita:

Reconciliar os dados da Didit com a sua base de dados interna.
Carregar em massa utilizadores históricos através da importação por CSV na consola, antes de executar quaisquer sessões.
Preservar as relações quando mais tarde migrar para a Didit para monitorização de transações.

Regras, convenções e boas práticas

Regra	Motivo
Escolha um identificador canónico por entidade e nunca o altere	As alterações criam uma nova entidade e deixam o histórico órfão
Prefixe os valores de `vendor_data` pelo tipo de entidade (`user_...`, `biz_...`)	Evita colisões acidentais entre espaços de nomes no seu próprio código
Mantenha o `vendor_data` estável e sensível a maiúsculas e minúsculas	A Didit não normaliza maiúsculas e minúsculas
Mantenha os valores de `vendor_data` com menos de 128 caracteres	Cabem confortavelmente nos índices da base de dados
Nunca exponha dados pessoais em bruto	O `vendor_data` aparece em webhooks, registos de auditoria e respostas da API

Próximos passos

Visão geral dos utilizadores

Análise detalhada das entidades Utilizador e das suas operações.

Visão geral das empresas

Análise detalhada das entidades Empresa e das suas operações.

Criar sessão

Inicie uma verificação para um vendor_data.

Criar transação

Submeta uma transação ligada a uma entidade.

Visão geral

Preços

Fluxos e verificação

Revisão e operações

Entidades (utilizadores e empresas)

Definições e personalização

Segurança e conformidade

Didit Academy

Recursos

Ligação de vendor_data: associar IDs a entidades

O que é

Como liga as coisas entre si

Unicidade e âmbito

O que acontece se omitir `vendor_data`

Exemplo: pré-criar uma entidade e depois executar sessões

Migrar IDs externos

Regras, convenções e boas práticas

Próximos passos

Visão geral dos utilizadores

Visão geral das empresas

Criar sessão

Criar transação

​O que é

​Como liga as coisas entre si

​Unicidade e âmbito

​O que acontece se omitir vendor_data

​Exemplo: pré-criar uma entidade e depois executar sessões

​Migrar IDs externos

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

​Próximos passos

Visão geral dos utilizadores

Visão geral das empresas

Criar sessão

Criar transação

O que é

Como liga as coisas entre si

Unicidade e âmbito

O que acontece se omitir `vendor_data`

Exemplo: pré-criar uma entidade e depois executar sessões

Migrar IDs externos

Regras, convenções e boas práticas

Próximos passos