Guida all'integrazione KYB: architettura e pattern

Questa guida è il complemento della guida rapida. Descrive l’architettura, ogni decisione di integrazione e i modelli operativi che rendono la verifica KYB affidabile in produzione.

Architettura

Autenticazione

Tutte le richieste richiedono l’intestazione x-api-key con la chiave API della tua applicazione. Consulta Autenticazione API per la rotazione delle chiavi, la separazione degli ambienti e gli scope.

Creazione della sessione

Endpoint unico: POST /v3/session/. Il tipo del workflow determina se la sessione è KYC o KYB, quindi non serve alcun flag esplicito “business”. Campi consigliati in fase di creazione:

Campo	Scopo
`workflow_id`	Obbligatorio: fa riferimento al tuo workflow KYB.
`vendor_data`	Il tuo identificativo per l’azienda. Associa la sessione a un’entità Business.
`callback_url`	Facoltativo: indirizzo a cui reindirizzare l’utente al termine della verifica.
`expected_details`	Facoltativo: `{ company_name, registry_country, registration_number }`. Precompila la ricerca nel registro delle imprese: il paese di costituzione viene preselezionato e bloccato (`registry_country` come `XX`, oppure `XX-YY` per i registri a livello di stato, ad esempio `US-CA`), i campi della ragione sociale e del numero di registrazione vengono precompilati e la ricerca basata sui dati dichiarati viene eseguita automaticamente, combinando entrambi gli identificativi quando sono presenti. Solo precompilazione: eventuali discrepanze non generano avvisi.
`metadata`	Facoltativo: JSON allegato alla sessione.

Schema completo: crea sessione.

Invio del link ospitato

L’url della risposta è un link di verifica ospitato. Opzioni per l’invio:

Inviarlo via email dalla tua piattaforma.
Incorporarlo come link nella tua interfaccia di onboarding.
Aprirlo in una webview interna all’app (iOS / Android / React Native).

Puoi personalizzare l’esperienza ospitata (logo, colori, dominio, modelli delle email) tramite White label.

Polling o webhook

I webhook sono il modello consigliato. Didit invia eventi di completamento con una POST all’endpoint che hai sottoscritto non appena l’elaborazione termina. Il polling è supportato per lo sviluppo o quando il tuo endpoint webhook non è raggiungibile:

Esegui il polling di GET /v3/session/{id}/decision/ con backoff esponenziale (ogni 10 s inizialmente, fino a 60 s).
Interrompi il polling quando status è uno tra "Approved", "Declined", "In Review".

Un polling ad alta frequenza può superare i limiti di frequenza. In produzione preferisci sempre i webhook.

Gestione dei webhook

Sottoscrivi gli eventi che ti interessano. Gli stessi eventi coprono sia KYC sia KYB, con session_kind: "business" nel payload per identificare gli eventi delle sessioni business:

status.updated: lo stato della sessione è cambiato. Filtra su session_kind === "business" per le sessioni KYB.
data.updated: un revisore ha modificato i dati del registro o le persone chiave nella console, oppure il registro ha segnalato una modifica. Non viene inviato quando il richiedente carica un documento o invia le persone chiave: per questo segui status.updated. Vale lo stesso filtro su session_kind.
business.status.updated / business.data.updated: l’entità Business collegata è cambiata.

Catalogo completo degli eventi: webhook KYB. Verifica della firma e comportamento dei nuovi tentativi: riferimento dei webhook.

Gestione delle decisioni

switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}

Per la macchina a stati completa consulta stati KYB, e per i tag che spiegano una decisione consulta avvisi KYB.

Flusso di nuova presentazione

Quando una sessione di Verifica aziendale (KYB) passa a Resubmitted (oppure una funzionalità viene contrassegnata per la nuova presentazione), l’azienda deve caricare dati corretti o aggiuntivi. Puoi:

Rinviare lo stesso url: il flusso ospitato riprende dal punto in cui serve la nuova presentazione.
Riemettere un link non valido per una persona chiave: a una parte la cui sessione KYC figlia è stata eliminata, o è scaduta prima che la persona la avviasse, viene assegnata una nuova sessione con Rigenera la sessione KYC delle persone chiave.
Aprire un caso nella Business Console per tenere traccia internamente dello scambio.

Esegui i passaggi dal tuo front end

I passaggi relativi ai documenti e alle persone chiave possono essere gestiti anche dal tuo server con la tua chiave API: così mantieni l’interfaccia utente e Didit mantiene la verifica e la decisione. Ogni chiamata è limitata alla sessione KYB, richiede l’autorizzazione write:businesses (la lettura delle parti estratte accetta anche read:businesses o read:sessions) ed esegue gli stessi controlli, la stessa fatturazione e lo stesso avanzamento al passaggio successivo della pagina ospitata.

Carica i documenti societari mentre la sessione si trova nel passaggio Documenti KYB.
Leggi i soggetti nominati nei documenti, inclusi gli azionisti e le percentuali di proprietà, e mostrali al tuo richiedente.
Crea, modifica ed elimina bozze di soggetti. Una bozza non è dichiarata e non ha costi.
Invia le bozze. Didit decide quali parti devono essere verificate, crea una sessione KYC per ciascuna e restituisce il suo kyc_session_url da inviare o incorporare.
Leggi la decisione consolidata dalla sessione, come nel flusso ospitato.

Una chiamata effettuata mentre la sessione si trova in un altro passaggio riceve 409 kyb_step_mismatch con il passaggio in cui si trova, mentre una sessione conclusa riceve 409 kyb_session_not_writable.

Aggregazione del profilo aziendale

Se passi vendor_data alla creazione della sessione, Didit aggrega tutte le sessioni di quell’azienda in un’unica entità Business. Usa la mappa features dell’entità per rispondere alla domanda “questa azienda è completamente verificata in questo momento?” senza scorrere le sessioni. Vantaggi:

I flussi di re-KYB periodici si aggiungono allo stesso profilo.
Le transazioni monitorate con lo stesso vendor_data portano il contesto di rischio dell’azienda.
I titolari effettivi e gli amministratori collegati alle entità User popolano le relazioni tra entità.

Migliori pratiche

Pratica	Motivo
Passa sempre `vendor_data`	Senza di esso, la sessione resta orfana e non può essere aggregata.
Usa i webhook invece del polling	Latenza più bassa, nessuna pressione sul limite di frequenza.
Verifica le firme dei webhook	Impedisce eventi falsificati.
Memorizza il `session_id` nel tuo sistema	Serve per recuperare la decisione e generare i PDF.
Etichetta le sessioni con `metadata`	Semplifica la reportistica e il debugging.
Configura un workflow di test	Usa un workflow sandbox per i test di integrazione prima della produzione.

Gestione degli errori

Scenario	Risposta
`workflow_id` non valido	`400 Bad Request`
Sessione duplicata con lo stesso `vendor_data`	Crea una nuova sessione: è il comportamento previsto, perché è prevista una nuova verifica.
Paese dell’azienda al di fuori dei paesi consentiti dal workflow	Il controllo del registro genera l’avviso `KYB_COUNTRY_RESTRICTED`.
Interruzione del provider del registro durante la ricerca dell’azienda	`POST /v3/kyb/search/` restituisce `502` con `code: "kyb_registry_provider_unavailable"`. Non viene fatturata: riprova, oppure usa `code` per proporre l’inserimento manuale dell’azienda. Nel flusso ospitato di Didit, l’azienda viene indirizzata automaticamente all’inserimento manuale invece di ricevere un errore che prevede solo il nuovo tentativo. Vedi Ricerca nel registro KYB.
Limite di frequenza	`429 Too Many Requests` con l’intestazione `Retry-After`.

Riferimento completo sui limiti di frequenza.

Prossimi passi

Webhook

Ogni evento e payload KYB.

Stati

Riferimento alla macchina a stati.

Schema della risposta

Come decodificare la decisione KYB.

Primi passi

Funzionalità

Profili aziendali

Riferimento

Console

Guida all'integrazione KYB: architettura e pattern

Architettura

Autenticazione

Creazione della sessione

Invio del link ospitato

Polling o webhook

Gestione dei webhook

Gestione delle decisioni

Flusso di nuova presentazione

Esegui i passaggi dal tuo front end

Aggregazione del profilo aziendale

Migliori pratiche

Gestione degli errori

Prossimi passi

Webhook

Stati

Schema della risposta

​Architettura

​Autenticazione

​Creazione della sessione

​Invio del link ospitato

​Polling o webhook

​Gestione dei webhook

​Gestione delle decisioni

​Flusso di nuova presentazione

​Esegui i passaggi dal tuo front end

​Aggregazione del profilo aziendale

​Migliori pratiche

​Gestione degli errori

​Prossimi passi

Webhook

Stati

Schema della risposta

Architettura

Autenticazione

Creazione della sessione

Invio del link ospitato

Polling o webhook

Gestione dei webhook

Gestione delle decisioni

Flusso di nuova presentazione

Esegui i passaggi dal tuo front end

Aggregazione del profilo aziendale

Migliori pratiche

Gestione degli errori

Prossimi passi