Vai al contenuto principale
POST
Python
Usa questa guida per scegliere il percorso di importazione corretto quando sposti dati da un altro provider in Didit. Con “importazione” i clienti intendono spesso due operazioni diverse:
  • Importare verifiche storiche: ricreare record storici di verifiche KYC e KYB, di monitoraggio delle transazioni o di regole del workflow già completate, così che Didit mostri lo storico del vecchio provider. Usa POST /v3/session/imports/.
  • Importare dati operativi: creare Users, Businesses, volti del profilo, voci di blocklist o di allowlist, così che Didit possa usarli nei controlli futuri. Usa le API delle entità, dei volti e delle liste.
Le importazioni di verifiche creano record storici con session_type: "MIGRATED" per KYC e KYB. Non inviano email agli utenti finali, non reindirizzano gli utenti al flusso ospitato e non rieseguono la verifica originale. I record importati compaiono negli elenchi delle sessioni, nei profili delle entità, nelle viste delle transazioni e in GET /v3/session/{session_id}/decision/ dove applicabile.

Quale importazione usare?

Se ti serve solo un profilo utente o aziendale per i controlli futuri, non importare una sessione di verifica storica. Usa le API delle entità User o Business. Se vuoi che la decisione, i campi del documento, gli avvisi o le evidenze del vecchio provider compaiano in Didit come storico di conformità, usa POST /v3/session/imports/.

Cosa può essere migrato da ciascun provider?

Didit accetta un file CSV o NDJSON in formato canonico, quindi puoi migrare da qualsiasi provider dopo aver esportato e trasformato i dati. Lo schema di importazione è sempre quello canonico di Didit.

Flusso di migrazione

  1. Decidi se vuoi importare storico, profili, volti, liste, transazioni o regole.
  2. Esporta i dati dal vecchio provider in autonomia. Non inviare a Didit le chiavi API del vecchio provider.
  3. Trasforma l’esportazione del provider nel template CSV o NDJSON canonico di Didit corrispondente.
  4. Per le migrazioni di grandi dimensioni, preferisci NDJSON e suddividi i dati in file che puoi riprovare in modo indipendente.
  5. Crea il job di importazione e controllane l’avanzamento.
  6. Recupera gli errori di riga, correggi solo le righe non riuscite e ritentale. Tutti i job di importazione sono idempotenti sul loro ID esterno naturale.

Crea un job di importazione

Crea un job di importazione con una singola richiesta multipart:
Usa CSV per migrazioni più piccole basate su fogli di calcolo e NDJSON per le migrazioni di grandi dimensioni. Con 100k+ righe, NDJSON è più facile da trasmettere in streaming, suddividere, validare e ritentare. Un’applicazione può eseguire fino a 4 job di importazione contemporaneamente, quindi suddividi una migrazione grande in più file e avvia un job per ciascuno. Ogni job scarica in parallelo i file multimediali di una riga. Un job interrotto da un deploy o dal riavvio di un worker riprende automaticamente dall’ultima riga importata, quindi non devi riavviarlo. Per le importazioni di transazioni, ometti workflow_id:

Campi della richiesta

Come vengono tracciati e deduplicati i record

Non esiste un campo della richiesta per la sorgente dei dati: ogni importazione usa lo schema canonico di Didit. Ogni record importato salva metadata.imported_from = "generic" per la tracciabilità. Le importazioni user_verification e business_verification deduplicano le righe su external_id all’interno dell’applicazione, quindi ritentare lo stesso file non crea duplicati. Le importazioni transactions deduplicano invece su transaction_id. Una migrazione da provider (source=provider) salva ogni record come <provider>:<id>, ad esempio sumsub:5f8c0e2a9b1d4c3e2f1a0b9c. Un’importazione di file di Verifica degli utenti che ha inviato l’ID del provider senza prefisso (5f8c0e2a9b1d4c3e2f1a0b9c) viene riconosciuta come lo stesso record, in entrambe le direzioni. Puoi quindi avviare una migrazione tramite file e completarla con una migrazione da provider, o viceversa, senza importare due volte lo stesso record.

Importare foto dei documenti, video e selfie come prova

Per import_type=user_verification, puoi importare le foto originali dei documenti, i video di acquisizione del documento e del rilevamento della vitalità e l’immagine selfie dal provider precedente. Usa queste colonne canoniche: Per le migrazioni di grandi dimensioni, usa URL HTTPS. Didit scarica ogni file, verifica che l’URL sia sicuro, salva una copia di proprietà di Didit e la collega alla sessione importata. Le immagini vengono compresse; i video vengono salvati così come sono. Il base64 inline è accettato per le immagini nelle importazioni di piccole dimensioni, ma i video devono essere sempre forniti come URL: il base64 aumenterebbe ogni video di circa il 33% e supererebbe rapidamente il limite di importazione per file. Esempio di riga NDJSON con URL dei media ospitati dal provider:
Regole importanti sui media:
  • Gli URL devono usare https.
  • Gli URL non devono risolvere in indirizzi IP privati, localhost, intervalli link-local o host di metadati interni.
  • Per le immagini si accetta una colonna URL oppure la relativa alternativa *_base64; se sono impostate entrambe, ha precedenza il base64. I video accettano solo URL: non esiste una colonna *_video_base64.
  • I video devono essere mp4, webm o mov, e ciascun video può avere una dimensione massima di 10 MB. I file più grandi o non video vengono rifiutati come errori di riga.
  • Didit applica timeout di connessione e lettura, una dimensione massima dei file e non effettua tentativi infiniti.
  • Gli errori di download dei media vengono salvati come errori di riga, così il resto dell’importazione può proseguire.
  • Se non hai media dal provider, lascia vuote queste colonne. Didit importa comunque i dati strutturati della decisione e i campi del documento.
  • Immagini e video importati sono una prova per la revisione storica. Per impostazione predefinita, Didit non riesegue OCR, analisi di vitalità o analisi delle frodi documentali sui media storici importati.

Interrogare lo stato di avanzamento

La risposta include status, import_type, total_rows, processed_rows, created_count, updated_count, skipped_count, failed_count e checkpoint_row.

Scaricare gli errori di riga

Ogni errore include row_number, external_id, error e raw_row, così puoi correggere solo le righe non riuscite e riprovare.

Protezione dagli abusi

Le importazioni storiche tramite POST /v3/session/imports/ sono disabilitate per impostazione predefinita. Didit abilita questa funzione per ogni organizzazione dopo una revisione, perché questi processi possono elaborare milioni di righe e scaricare media. Le importazioni di dati operativi descritte in questa guida, ovvero la creazione di utenti, la creazione di aziende, il caricamento di volti di profilo, il caricamento di blocklist di volti o l’aggiunta di voci alle liste, non richiedono un’abilitazione speciale per la migrazione, oltre alle normali autorizzazioni della chiave API, alla disponibilità del prodotto e ai limiti di frequenza di questi endpoint. I processi di importazione storici vengono eseguiti su processi di lavoro isolati, con limiti di dimensione dei file, budget di righe, URL dei media solo HTTPS, blocco degli URL verso reti private e un limite di 4 processi di importazione attivi per applicazione. Inoltre, gli errori vengono registrati per ogni riga.

Stati canonici

Idempotenza

Didit usa external_id come chiave di idempotenza per le importazioni di Verifica degli utenti e Verifica aziendale (KYB), nell’ambito di ciascuna applicazione. Le importazioni di transazioni usano transaction_id nell’ambito di ciascuna applicazione. Ripetere l’importazione dello stesso file salta le righe già importate e crea le righe non ancora elaborate.

Importare utenti, volti di profilo e blocklist

Usa questi percorsi quando non stai ricreando una sessione di verifica completata.

Importare i profili utente

Crea gli utenti con POST /v3/users/create/ oppure con l’importazione CSV dalla Business Console in Importare ed esportare utenti. Questa operazione crea o aggiorna solo il profilo VendorUser. Non crea una sessione di verifica, una decisione KYC, un report sui documenti, un avviso o uno storico di webhook. Usala quando vuoi che Didit sappia che il cliente esiste prima dei controlli futuri, oppure quando devi completare campi simili a quelli di un CRM, come display_name, tag o metadati.

Caricare volti di profilo attendibili

Dopo che esiste un utente, carica un volto di profilo attendibile con POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/. Questo collega la prova biometrica al profilo utente e la indicizza per il rilevamento dei duplicati e per la ricerca facciale. Questa operazione non inserisce il volto in blocklist. È utile quando disponi di un’immagine del profilo attendibile proveniente da un precedente provider KYC e vuoi che i futuri controlli di Didit la confrontino.

Importare blocklist e allowlist di volti

Per bloccare o consentire direttamente un volto, usa POST /v3/lists/{list_uuid}/entries/face-upload/ con una lista di tipo facciale. Didit estrae l’embedding biometrico e memorizza una voce della lista. Usalo per immagini di frodatori noti, volti di allowlist attendibili o migrazioni di liste antifrode dai provider. Se il volto proviene da una sessione Didit esistente, preferisci POST /v3/lists/{list_uuid}/entries/ con reference_session_id: Didit estrae il volto corretto dalla sessione e collega la voce alla sessione di origine.

Importare liste di utenti, aziende, documenti, wallet, email, telefoni, IP o dispositivi

Usa POST /v3/lists/{list_uuid}/entries/ per i valori di lista non relativi ai volti. Questo è il percorso corretto per blocklist, allowlist e liste di chargeback dei provider, indirizzi dei wallet, IP a rischio noti, impronte dei dispositivi, numeri di documento, email, numeri di telefono, utenti o aziende.

Prossimi passi

Importare utenti

Carica i profili utente e collega i volti di profilo attendibili.

Importare aziende

Carica i profili delle aziende prima di eseguire il KYB.

Caricare un volto di profilo

Collega immagini di volti attendibili agli utenti importati.

Caricare un volto in lista

Aggiungi volti a blocklist o allowlist.

Creare una voce di lista

Importa numeri di telefono, email, wallet, documenti, IP, dispositivi, utenti o aziende nelle liste.

Limiti di frequenza

Progetta cicli di migrazione sicuri e nuovi tentativi.

Autorizzazioni

x-api-key
string
header
obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Corpo

import_type
enum<string>
predefinito:user_verification

Cosa importare: sessioni storiche di Verifica degli utenti, sessioni storiche di Verifica aziendale, regole di stato personalizzate del workflow o record storici di monitoraggio delle transazioni.

Opzioni disponibili:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

UUID del workflow a cui collegare le sessioni importate o le regole di stato. Obbligatorio per user_verification, business_verification e status_rules. Omettere per transactions.

source_format
enum<string>

Opzionale. Se omesso, viene dedotto dall'estensione del file caricato.

Opzioni disponibili:
csv,
ndjson
file
file

File canonico CSV o NDJSON. Usa NDJSON per importazioni di grandi dimensioni. Dimensione massima di caricamento 25 MB (usa source_file_url per file più grandi). È mutuamente esclusivo con source_file_url.

source_file_url
string<uri>

Alternativa al caricamento del file. Deve essere un URL HTTPS che punta a un indirizzo pubblico (le reti private/di loopback vengono rifiutate). Si esclude a vicenda con file.

source
enum<string>

provider indica una migrazione da un altro provider di verifica dell'identità. Ometti per un'importazione da file.

Opzioni disponibili:
file,
provider
provider
enum<string>

Origine della migrazione, da GET /v3/session/imports/providers/. Obbligatoria quando source è provider.

Opzioni disponibili:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

La chiave di sola lettura del provider, con i nomi dei campi elencati in credential_fields. Crittografata a riposo, mai restituita ed eliminata al termine dell'importazione. Inviala come stringa JSON in multipart.

options
object
status_mapping
object

Modifiche alla mappatura predefinita degli stati del provider: dallo stato di origine allo stato di Didit. Not Finished e Abandoned vengono ignorati e conteggiati, mai importati.

dry_run
boolean
predefinito:false

Conta ciò che la migrazione importerebbe (per stato, già in Didit, stessa persona, non completato) senza scrivere nulla. Il job termina nello stato READY; avvialo con POST /v3/session/imports/{importId}/start/.

face_templates
boolean
predefinito:false

Genera modelli biometrici dai selfie importati ed esegui la ricerca rispetto ai volti e alla blocklist dell'applicazione. Le corrispondenze vengono contrassegnate solo per la revisione. Richiede lawful_basis_confirmed.

lawful_basis_confirmed
boolean
predefinito:false

Conferma che disponi di una base giuridica per condividere questi selfie con Didit in qualità di responsabile del trattamento.

Risposta

Processo di importazione accettato. Effettua il polling dello uuid restituito fino a quando lo status non è COMPLETED o FAILED.

uuid
string<uuid>
obbligatorio

ID del processo di importazione. Usa questo valore per verificare lo stato di avanzamento e recuperare gli errori delle righe.

status
enum<string>
obbligatorio
Opzioni disponibili:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
obbligatorio
Opzioni disponibili:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
obbligatorio
Opzioni disponibili:
csv,
ndjson
source_filename
string
obbligatorio
total_rows
integer<int64>
obbligatorio
processed_rows
integer<int64>
obbligatorio
created_count
integer<int64>
obbligatorio
updated_count
integer<int64>
obbligatorio
skipped_count
integer<int64>
obbligatorio
failed_count
integer<int64>
obbligatorio
checkpoint_row
integer<int64>
total_media_bytes
integer<int64>
last_error
string | null
created_at
string<date-time>
updated_at
string<date-time>
started_at
string<date-time> | null
completed_at
string<date-time> | null
state
enum<string>

Lo stato del job così come mostrato nella console; errors corrisponde a un job completato con righe rifiutate.

Opzioni disponibili:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
Opzioni disponibili:
file,
api,
provider
provider
string

Origine della migrazione; vuota per un'importazione da file o API.

provider_options
object
credential_hint
string

I primi caratteri della chiave contenuta nella migrazione. La chiave stessa non viene mai restituita.

credentials_expires_at
string<date-time> | null
resumes_at
string<date-time> | null

Quando un processo sospeso a causa del limite di frequenza del provider riprende automaticamente.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

Risultati di una simulazione (dry run): total, by_status, already_in_didit, same_person, not_finished, failed, unmapped_statuses.

face_templates_enabled
boolean
lawful_basis_confirmed_at
string<date-time> | null
not_finished_count
integer<int64>
same_person_count
integer<int64>
face_templates_count
integer<int64>
face_duplicates_count
integer<int64>
face_blocklist_hits_count
integer<int64>
created_by_name
string | null
created_by_email
string | null
Ultima modifica il 7 novembre 2026