Collegamento vendor_data: unire ID ed entità

vendor_data è l’identificatore che fornisci in ogni sessione e transazione per collegare la sessione o la transazione a un’entità Utente o Azienda. È il campo più importante per l’aggregazione delle entità: se lo imposti correttamente, ogni funzionalità a valle (cronologia del profilo, monitoraggio delle transazioni, applicazione delle blocklist e monitoraggio AML continuo) funziona senza intoppi.

Cos’è

vendor_data è una stringa che scegli tu. Didit la tratta come un identificatore opaco e non ne interpreta il contenuto. Valori tipici:

Il tuo sistema	Valori `vendor_data` adatti
Database utenti interno	`user_1234`, `uuid-v4` dell’utente
ID rivolto al cliente	`CUST-2026-00042`, email con hash
SaaS multi-tenant	`tenant_acme:user_1234`
Piattaforma B2B	`company-hq-global`, `tax-id-US-123456789`

Non inserire dati personali (email, numeri di telefono, identificativi fiscali in chiaro) direttamente in vendor_data. Applica un hash o un prefisso. vendor_data compare nei payload dei webhook e viene conservato a tempo indeterminato finché l’entità esiste.

Come collega gli elementi

Quando invii una sessione o una transazione con un valore vendor_data:

Didit cerca nella tua applicazione l’entità con quel vendor_data.
Se esiste, il nuovo oggetto viene collegato a quell’entità.
Se non esiste, Didit crea l’entità (con status: ACTIVE) e collega il nuovo oggetto.

Questo vale per:

POST /v3/session/: sessioni KYC e di Verifica aziendale (KYB)
POST /v3/transactions/: transazioni (sia per il richiedente sia per la controparte)
I campi applicant.vendor_data / counterparty.vendor_data all’interno dei payload delle transazioni

Unicità e ambito

vendor_data è univoco per applicazione, non in modo globale all’interno di Didit:

Ambito	Garanzia di unicità
All’interno di una stessa applicazione	`vendor_data` è univoco per tipo di entità (Utente e Azienda sono namespace separati)
Tra applicazioni della tua organizzazione	`vendor_data` non è condiviso: lo stesso valore in due app si riferisce a due entità diverse
Tra organizzazioni	Non condiviso: ogni organizzazione ha le proprie tabelle di entità

Ciò significa che puoi usare lo stesso vendor_data in un’app di staging e in un’app di produzione senza collisioni, e puoi avere un Utente user-42 e un’Azienda user-42 senza collisioni (anche se, per chiarezza, è sconsigliato).

Cosa succede se ometti `vendor_data`

Puoi creare una sessione senza vendor_data. In questo caso:

Non viene creata alcuna entità per la sessione.
La sessione è orfana: non compare nel profilo di nessun Utente o Azienda.
Non puoi cercare in seguito la sessione tramite vendor_data, ma solo tramite session_id.

Usa questo schema solo per verifiche anonime o una tantum in cui non serve alcuna aggregazione delle entità. Per ogni integrazione che prevede una nuova verifica, transazioni o monitoraggio continuo, fornisci sempre vendor_data.

Esempio: crea prima un’entità, poi avvia le sessioni

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

Tutte e tre le chiamate sono collegate alla stessa entità Utente. Quando in seguito esegui GET /v3/users/user-42/, vedi il numero di sessioni, i contatori delle sessioni approvate/rifiutate, le transazioni collegate e gli ultimi dati del profilo.

Migrazione degli ID esterni

Se adotti Didit dopo aver utilizzato un fornitore KYC esistente, passa fin dal primo giorno i tuoi ID utente stabili esistenti come vendor_data. Così puoi facilmente:

Riconciliare i dati di Didit con il tuo database interno.
Caricare in blocco gli utenti storici tramite import CSV dalla console prima di avviare qualsiasi sessione.
Preservare le relazioni quando in seguito passi a Didit per il monitoraggio delle transazioni.

Regole, convenzioni e buone pratiche

Regola	Perché
Scegli un unico identificatore canonico per ogni entità e non cambiarlo mai	Le modifiche creano una nuova entità e lasciano orfana la cronologia
Prefissa i valori `vendor_data` in base al tipo di entità (`user_...`, `biz_...`)	Evita collisioni accidentali tra namespace nel tuo codice
Mantieni `vendor_data` stabile e sensibile alle maiuscole	Didit non normalizza le maiuscole
Mantieni la lunghezza di `vendor_data` sotto i 128 caratteri	Rientra comodamente negli indici del database
Non esporre mai dati personali in chiaro	`vendor_data` compare nei webhook, nei registri di audit e nelle risposte API

Passi successivi

Panoramica degli utenti

Approfondimento sulle entità Utente e sulle relative operazioni.

Panoramica delle aziende

Approfondimento sulle entità Azienda e sulle relative operazioni.

Crea sessione

Avvia una verifica per un vendor_data.

Crea transazione

Invia una transazione collegata a un’entità.

Panoramica

Prezzi

Workflow e verifica

Revisione e operazioni

Entità (utenti e aziende)

Impostazioni e personalizzazione

Sicurezza e compliance

Didit Academy

Risorse

Collegamento vendor_data: unire ID ed entità

Cos’è

Come collega gli elementi

Unicità e ambito

Cosa succede se ometti `vendor_data`

Esempio: crea prima un’entità, poi avvia le sessioni

Migrazione degli ID esterni

Regole, convenzioni e buone pratiche

Passi successivi

Panoramica degli utenti

Panoramica delle aziende

Crea sessione

Crea transazione

​Cos’è

​Come collega gli elementi

​Unicità e ambito

​Cosa succede se ometti vendor_data

​Esempio: crea prima un’entità, poi avvia le sessioni

​Migrazione degli ID esterni

​Regole, convenzioni e buone pratiche

​Passi successivi

Panoramica degli utenti

Panoramica delle aziende

Crea sessione

Crea transazione

Cos’è

Come collega gli elementi

Unicità e ambito

Cosa succede se ometti `vendor_data`

Esempio: crea prima un’entità, poi avvia le sessioni

Migrazione degli ID esterni

Regole, convenzioni e buone pratiche

Passi successivi