API registro imprese: estrazione automatica dati KYB

Quando inizia una sessione di verifica aziendale, Didit interroga i registri ufficiali delle imprese per recuperare e validare le informazioni aziendali. Questa ricerca automatizzata costituisce la base dell’intero processo di verifica aziendale.

Ricerca nel registro

Didit si collega ai registri delle imprese nei paesi supportati per recuperare dati ufficiali. Nel flusso ospitato l’utente seleziona il paese di costituzione e compila il nome dell’azienda, il numero di registrazione, o entrambi: almeno uno dei due è obbligatorio. I numeri di registrazione vengono normalizzati dove il registro lo richiede (per esempio, i numeri delle società del Regno Unito vengono completati con zeri iniziali fino a otto cifre), e quando vengono forniti entrambi gli identificativi la ricerca nel registro li combina.

Precompilazione della ricerca con `expected_details`

Se conosci già l’azienda, passa expected_details (company_name, registry_country, registration_number) quando crei la sessione. Il flusso ospitato preseleziona e blocca il paese (e lo stato, per i registri a livello statale come US-CA), precompila i campi di ricerca corrispondenti ed esegue automaticamente la ricerca dichiarata: l’utente arriva direttamente al risultato della propria azienda. Entrambi i campi restano modificabili, così l’utente può correggere un’indicazione errata. È solo una precompilazione: selezionare un’azienda diversa da quella dichiarata non genera alcun avviso.

Tipi di ricerca

Le ricerche nel registro supportano due modalità:

Modalità	Descrizione
Esatta	Corrisponde con precisione al nome dell’azienda o al numero di registrazione
Contiene	Corrisponde alle aziende il cui nome contiene il termine di ricerca: utile quando la ragione sociale esatta non è nota

Flusso di ricerca

La ricerca nel registro segue un flusso asincrono:

Ricerca

Didit interroga il registro con il paese selezionato e gli identificativi forniti: nome dell’azienda, numero di registrazione o entrambi combinati. Il campo searched_by della risposta indica come sono stati abbinati i risultati (name, registration_number o registration_number_and_name), e l’interfaccia ospitata offre un’opzione con un solo tocco, “Cerca invece per nome dell’azienda”, sui risultati ottenuti tramite numero di registrazione. La ricerca viene eseguita in modo asincrono.

Esegui il polling dei risultati

Verifica lo stato della ricerca finché i risultati non sono disponibili. I registri di grandi dimensioni possono impiegare alcuni secondi per restituire i risultati.

Selezione dell'azienda

Controlla le aziende restituite e seleziona la corrispondenza corretta. Didit collega l’azienda selezionata al controllo KYB e compila tutti i dati disponibili.

Conferma e prosegui

Conferma o correggi i dati dell’azienda e prosegui con il passaggio successivo configurato. Alcuni registri restituiscono il profilo dell’azienda prima che il report sull’assetto proprietario sia pronto: l’elaborazione di tale report prosegue in background mentre il richiedente completa passaggi indipendenti, come il caricamento di un documento. La precompilazione dal registro non blocca il modulo delle persone chiave: il richiedente può inserire le persone manualmente, e le persone disponibili nel registro compaiono prima dell’invio man mano che il report arriva. Le decisioni personalizzate che dipendono dal report attendono il report, senza indovinarne l’esito. Le tue correzioni vengono conservate quando il report arriva. Un report in attesa non conta come controllo nel registro completato né come approvazione automatica, e la fatturazione del registro si basa sul livello effettivamente erogato.

Invio manuale

Se l’azienda non viene trovata nel registro, invia i dati aziendali manualmente. La sessione prosegue con i dati forniti e is_from_registry viene impostato su false.

Dati recuperati

Campo	Descrizione
`company_name`	Ragione sociale registrata presso l’autorità
`registration_number`	Numero ufficiale di registrazione o costituzione della società
`country_code`	Paese di costituzione (ISO 3166-1 alpha-3)
`company_type`	Tipo di entità giuridica (Ltd, LLC, PLC, SA, GmbH, SL, ecc.)
`registry_status`	Stato attuale dell’azienda nel registro (`active`, `dissolved`, `struck_off`, ecc.)
`incorporation_date`	Data in cui l’azienda è stata registrata originariamente
`registered_address`	Indirizzo ufficiale della sede legale
`tax_number`	Numero di identificazione fiscale, ove disponibile
`alternative_names`	Nomi commerciali, dba, precedenti ragioni sociali o nomi nella lingua originale come valore di testo
`legal_entity_identifier`	LEI: per istituti finanziari e società quotate
`nature_of_business`	Breve descrizione dell’attività (nella lingua del registro)
`registered_capital`	Capitale autorizzato / emesso come oggetto `{amount, currency}`
`location_of_registration`	Città / suddivisione del registro di riferimento
`control_scheme`	Schema di controllo / governance, ove esposto dal registro
`website`, `email`, `phone`	Recapiti presenti nel registro
`addresses[]`	Indirizzi aggiuntivi registrati o di esercizio dell’attività
`industries[]`	Codici di classificazione settoriale (SIC, NACE o equivalenti locali)
`accounts`	Date di deposito quando riportate, inclusi `last_annual_return_date` e `last_agm_date`. Le dichiarazioni annuali e le assemblee sono distinte dai bilanci.
`financial_summary`	Dati finanziari di sintesi quando pubblicati dal registro (ricavi, dipendenti, stato del deposito)
`confirmed_by_user_at`	Data e ora in cui l’utente finale ha confermato o modificato i dati del registro
`last_console_edit_at`	Data e ora dell’ultima modifica effettuata da un analista nella console
`is_editable`	`true` finché i dati provenienti dal registro possono ancora essere modificati dall’utente finale nel flusso ospitato
`is_from_registry`	`true` per le aziende provenienti dal registro, `false` per l’inserimento manuale
`fetch_status`	`pending`, `resolved` o `failed`: stato della ricerca nel registro
`verification_status`	`verified`, `failed` o `unknown`

Stati dell’azienda

Stato	Descrizione
Attiva	L’azienda è attualmente attiva e in regola
Sciolta	L’azienda è stata formalmente sciolta
Cancellata	Rimossa dal registro (ad esempio per inadempienza)
In liquidazione	L’azienda è in fase di liquidazione
Inattiva	Registrata ma non attualmente operativa

Le aziende con uno stato diverso da Attiva possono essere segnalate o rifiutate automaticamente, a seconda della configurazione del tuo workflow.

Indicatore della fonte dei dati

Ogni record di azienda include un flag is_from_registry:

true: i dati sono stati recuperati da un registro ufficiale delle imprese
false: i dati sono stati inseriti manualmente perché l’azienda non è stata trovata nel registro

Il campo fetch_status indica se la ricerca nel registro è stata completata, non è riuscita o è ancora in corso.

Livelli di dati e prezzi

Nel flusso ospitato, la selezione di un’azienda comporta l’addebito della tariffa del registro, anche se il richiedente lascia la pagina prima di confermare i dettagli o di completare la verifica. Se il report è pronto al momento della selezione, il livello consegnato viene addebitato subito. Se i dati sull’assetto proprietario sono ancora in sospeso, il livello Lite viene addebitato alla selezione e la differenza di prezzo viene addebitata solo quando viene consegnato un livello superiore. Se l’assetto proprietario non è disponibile, non si applica alcuna maggiorazione per l’assetto proprietario. Il totale usa i prezzi indicati al momento della selezione e non supera mai il prezzo del livello richiesto. La selezione e l’eventuale adeguamento successivo per l’assetto proprietario contano come un’unica verifica nel registro; leggere il report acquistato o confermarne i dettagli non la addebita di nuovo. I contratti a tariffa fissa esistenti contabilizzano una verifica del registro al momento della selezione, senza un’unità contrattuale aggiuntiva per la consegna successiva dell’assetto proprietario. Le ricerche nei workflow ospitati non hanno una tariffa di ricerca separata. Le ricerche API autonome possono comportare una tariffa di $0.50 per richiesta riuscita; vedi fatturazione delle ricerche. Consulta prezzi del registro KYB per la tabella completa per paese.

Livello	Cosa ottieni
Lite	I campi sopra indicati: profilo dell’azienda, identificativi, stato, indirizzo registrato, attività e dirigenti
Azionisti	Lite più gli azionisti diretti (persone fisiche e persone giuridiche) con le relative fasce di partecipazione
UBO	Azionisti più i titolari effettivi individuati lungo la catena di controllo

In un workflow ospitato il livello viene scelto per paese da Workflows → KYB Registry Check → Countries. Quando il registro non contiene alcun record sull’assetto proprietario per un’azienda, una richiesta di Azionisti o UBO viene consegnata e addebitata al livello più alto che i registri del paese possono fornire, di solito Lite. Un’azienda non trovata e inserita manualmente (is_from_registry: false) viene addebitata con una tariffa fissa di $0.75: la ricerca è stata comunque eseguita, anche se non è stato restituito alcun record dal registro.

Esempio: risposta del livello Lite

Lite restituisce solo il profilo dell’azienda, senza azionisti, UBO o struttura dell’assetto proprietario:

{
  "company_name": "ACME HOLDINGS PTY LTD",
  "registration_number": "094447122",
  "country_code": "AU",
  "registry_status": "active",
  "incorporation_date": "2000-09-12",
  "company_type": "Proprietary Limited",
  "registered_address": "Sydney, NSW, 2000",
  "tax_number": null,
  "vat_number": null,
  "website": null,
  "is_from_registry": true
}

Il livello Azionisti aggiunge ownership_structure e le voci degli azionisti oltre agli amministratori e ai dirigenti. Il livello UBO risolve inoltre i titolari effettivi con le percentuali di partecipazione. Vedi Assetto proprietario e Dirigenti e amministratori.

Dati del registro e dati forniti dall’utente

Didit conserva i dati restituiti dal registro e i dati confermati dall’utente come record di audit separati, con una vista canonica unificata utilizzata dai controlli successivi. Ogni azienda contiene tre blocchi correlati:

Campo	Descrizione
`registry_data`	La versione normalizzata dei dettagli del registro di Didit: l’esito dell’assetto proprietario (`ownership_error`, `section_errors`, `ubo_resolution`), le correzioni apportate con update-data e i dati del registro che non hanno un campo proprio. Le sue chiavi variano in base all’azienda e non costituiscono un contratto stabile.
`user_provided_data`	Ciò che l’utente finale ha confermato o modificato nella fase di conferma dei dati del registro nel flusso ospitato.
Campi canonici di primo livello (`company_name`, `registration_number`, `country_code`, `incorporation_date`, ecc.)	La versione unificata: i dati confermati dall’utente quando presenti, altrimenti i dati del registro come riserva. Le funzionalità a valle (confronto OCR dei documenti, screening AML, valutazione del rischio) operano sulla vista canonica.

Il timestamp confirmed_by_user_at indica quando l’utente finale ha confermato o modificato i dati del registro. Finché questo timestamp è null e is_editable è true, l’utente finale può continuare a modificare i campi all’interno del flusso ospitato. Per le aziende inserite manualmente (is_from_registry: false), user_provided_data è l’unica fonte e is_editable diventa false dopo l’invio da parte dell’utente. Gli analisti possono vedere le due fonti affiancate nella revisione della sessione in Business Console e confrontare ciò che ha indicato il registro con ciò che l’utente ha confermato.

Campi del modulo di registro configurabili

Puoi scegliere quali dati aziendali il flusso di verifica ospitato richiede durante il passaggio di conferma del registro. Configurali nella Business Console: apri l’editor del workflow, seleziona il nodo KYB Registry check e passa alla scheda Campi. Ogni campo può trovarsi in uno di tre stati:

Stato	Comportamento
Nascosto	Il campo non viene mostrato nel flusso ospitato e non viene raccolto.
Facoltativo	Il campo viene mostrato; l’utente può lasciarlo vuoto.
Obbligatorio	Il campo viene mostrato e deve essere compilato prima che l’utente possa inviare il modulo.

Tre campi vengono sempre mostrati e sono sempre obbligatori, perché identificano l’azienda, quindi non possono essere configurati: company_name, country_code e region (stato/regione, dove il registro è regionale). I 16 campi configurabili sono: registration_number, incorporation_date, legal_address, vat_number, alternative_names, tax_number, company_type, legal_entity_identifier, location_of_registration, nature_of_business, registered_capital_amount, registered_capital_currency, website, email, phone, control_scheme Per impostazione predefinita, e per tutti i workflow esistenti, solo incorporation_date è Obbligatorio; ogni altro campo configurabile è Facoltativo, quindi il modulo si comporta esattamente come prima che esistesse questa impostazione. L’obbligatorietà viene applicata lato server: se invii il modulo di registro con un campo obbligatorio vuoto, ricevi 400 con messaggi di errore per ciascun campo, e l’interfaccia ospitata mostra solo i campi abilitati. Nell’API dei workflow, l’impostazione è l’oggetto kyb_registry_fields_config sul nodo KYB Registry; consulta configurazioni delle funzionalità per la struttura.

Impostare vat_number come Obbligatorio ha effetto solo per le aziende costituite in un paese dell’UE con IVA (vedi sotto). Per tutti gli altri paesi il campo è trattato come facoltativo anche se impostato come obbligatorio, perché non esiste un numero IVA UE da raccogliere. Il loro tax_number viene comunque validato quando viene fornito.

Validazione del numero VAT e dell’identificativo fiscale

Quando il passaggio di registro viene inviato, Didit verifica il vat_number dell’azienda presso la fonte ufficiale del suo paese. Per un’azienda senza vat_number viene invece validato il tax_number. Il numero può essere inviato con o senza il prefisso del paese e con qualsiasi separatore (DE 123 456 789, DE123456789 e 123456789 sono equivalenti per un’azienda tedesca). Registri ufficiali. In questi paesi il numero viene verificato in tempo reale presso il registro governativo o ufficiale delle imprese, che restituisce anche la denominazione registrata (e, per la maggior parte, l’indirizzo):

Paese	Fonte
27 stati membri dell’UE e Irlanda del Nord (`XI`)	VIES della Commissione europea
Polonia	VIES, poi il registro dei contribuenti IVA del Ministero delle Finanze (la «White List») per un’azienda che VIES non elenca
Norvegia	Brønnøysund Register Centre (Central Coordinating Register for Legal Entities)
Svizzera	Registro UID dell’Ufficio federale di statistica
Brasile	Registro CNPJ della Receita Federal
Colombia	RUES, il Registro Unico Empresarial y Social delle camere di commercio
Costa Rica	Registro dei contribuenti del Ministero delle Finanze (Hacienda)
Ecuador	Registro dei contribuenti del Servizio di Riscossione delle Imposte (SRI)
Paraguay	Registro RUC della Direzione Nazionale delle Entrate (DNIT)

Un SIREN o SIRET francese, un RSIN olandese o un numero fiscale ungherese completo, inviati come numero VAT, vengono convertiti nel numero VAT corrispondente prima della verifica. I numeri VAT greci vengono verificati automaticamente con il prefisso EL. Regole di cifra di controllo. In questi paesi non è possibile interrogare alcun registro, quindi il numero viene verificato secondo il formato ufficiale del paese e le regole di cifra di controllo: Albania, Andorra, Argentina, Australia, Azerbaigian, Bielorussia, Canada, Cile, Cina, Repubblica Dominicana, Egitto, El Salvador, Ghana, Guatemala, Islanda, India, Indonesia, Israele, Giappone, Kenya, Liechtenstein, Messico, Moldova, Monaco, Montenegro, Marocco, Mozambico, Nuova Zelanda, Macedonia del Nord, Perù, Russia, San Marino, Serbia, Singapore, Sudafrica, Corea del Sud, Taiwan, Thailandia, Tunisia, Türkiye, Ucraina, Regno Unito, Stati Uniti, Uruguay, Venezuela e Vietnam. Queste regole si applicano anche nell’UE quando un tax_number è un codice fiscale nazionale per il quale non esiste un numero VAT da verificare, come una Steuernummer tedesca. Un tax_number indica solo un identificativo fiscale, non una registrazione IVA, quindi quando VIES non lo elenca il risultato ricade su queste regole invece di invalid. Le aziende di qualsiasi altro paese ricevono vat_validation_status: "not_applicable". Lo stesso vale per le sessioni sandbox, che non contattano mai un registro fiscale. Il risultato viene memorizzato sull’azienda ed esposto nel payload della decisione KYB:

Campo	Descrizione
`vat_number`	Il numero VAT così come inviato
`vat_validation_status`	`valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` o `not_applicable`
`vat_validated_number`	Il numero verificato, così come lo conosce la fonte (ad esempio il numero VAT derivato da un SIREN)
`vat_validation_source`	La fonte che ha determinato lo stato (vedi sotto)
`vat_validated_name`	Denominazione registrata presso la fonte, quando la fonte la comunica
`vat_validated_address`	Indirizzo registrato presso la fonte, quando la fonte lo comunica
`vat_checked_at`	Data e ora della verifica

Stato	Significato
`valid`	Il registro ufficiale conferma che il numero è registrato e attivo
`invalid`	Il registro ufficiale non ha alcuna registrazione attiva per il numero. Nell’UE, VIES elenca solo le aziende registrate per gli scambi intracomunitari
`format_valid`	Il numero rispetta il formato e le regole di cifra di controllo del paese; non è stato interrogato alcun registro
`invalid_format`	Il numero non rispetta il formato o le regole di cifra di controllo del paese
`could_not_validate`	Il registro non era disponibile, quindi il numero non ha potuto essere verificato. Viene verificato di nuovo alla successiva esecuzione del controllo sul registro
`not_applicable`	Non è stato fornito alcun numero VAT o identificativo fiscale, il paese non dispone di registro o di regole, oppure la sessione è una sessione sandbox

vat_validation_source assume uno dei valori eu_vies, pl_vat_white_list, no_brreg, ch_uid_register, br_receita_federal, co_rues, cr_hacienda, ec_sri, py_dnit o format_rules. Una volta che un numero è valid, invalid, format_valid o invalid_format, il risultato viene conservato per tutta la durata della sessione e il registro non viene interrogato di nuovo, a meno che il numero non cambi. Confronto dei nomi. Quando il numero è valid e la fonte comunica la denominazione registrata, Didit confronta in modo approssimato tale denominazione con il nome dell’azienda inviato. Una divergenza significativa genera l’avviso KYB_COMPANY_VAT_NAME_MISMATCH senza modificare lo stato della sessione: si tratta di un segnale indicativo per i revisori. Il suo additional_data contiene registry_name, registry_source e submitted_name, più vies_name quando la fonte è VIES. Alcuni stati membri dell’UE non comunicano la denominazione o l’indirizzo: i campi risultano vuoti e il confronto non viene eseguito. Azioni configurabili. Due impostazioni del nodo di controllo del registro KYB determinano cosa accade alla sessione quando il controllo non va a buon fine (valori REVIEW, DECLINE, NO_ACTION):

Impostazione	Si attiva quando	Predefinito
`kyb_vat_invalid_action`	`vat_validation_status` è `invalid`, oppure un `vat_number` è `invalid_format`	`REVIEW`: la sessione passa a In revisione
`kyb_vat_unverified_action`	`vat_validation_status` è `could_not_validate`	`NO_ACTION`: nessun effetto sulla sessione

Un tax_number che è invalid_format viene riportato nel payload senza attivare alcuna azione, perché il campo fiscale a testo libero spesso contiene un identificativo aziendale diverso. Ogni esito genera anche l’avviso corrispondente (KYB_COMPANY_VAT_INVALID, KYB_COMPANY_VAT_COULD_NOT_VALIDATE) sul controllo del registro: vedi avvisi di Verifica aziendale (KYB).

Verifica incrociata dei dati

Didit confronta automaticamente i dati forniti dall’utente / i dati canonici con quelli restituiti dal registro e con i dati OCR estratti dai documenti caricati:

Nome azienda: confronto approssimativo per tenere conto di abbreviazioni e differenze di formattazione
Numero di registrazione: verifica di corrispondenza esatta
Paese: verifica di coerenza tra il paese fornito e quello del registro
Indirizzo: geocodifica e normalizzazione per il confronto

Eventuali incoerenze vengono segnalate come avvisi nella sessione e sono visibili agli analisti nella console.

Riepilogo finanziario

Ove disponibili, Didit recupera dal registro i dati finanziari di sintesi:

Ricavi o fatturato
Numero di dipendenti
Codici settoriali SIC/NACE
Date di deposito e stato di conformità

Campi aggiuntivi del registro

A seconda della copertura della giurisdizione, la risposta del registro può includere anche:

alternative_names: nomi commerciali, dba, precedenti denominazioni legali
legal_entity_identifier (LEI): per istituti finanziari ed entità quotate
website, email, phone: dati di contatto presenti nel registro
nature_of_business: breve descrizione (nella lingua del registro)
registered_capital: capitale autorizzato / emesso come oggetto {amount, currency}

Tutti i campi confluiscono nel blocco business della decisione KYB.

Affidabilità e stato di verifica

Ogni risposta del registro include un verification_status:

Valore	Significato
`VERIFIED`	Il registro ha restituito una corrispondenza e i dati sono stati recuperati.
`FAILED`	Il registro ha restituito una corrispondenza, ma il recupero dei dati non è riuscito (ad esempio risposta parziale).
`UNKNOWN`	Non è stato possibile individuare l’azienda in nessun registro.

Combinalo con is_from_registry per guidare la tua logica di elaborazione successiva:

`is_from_registry`	`verification_status`	Significato
true	VERIFIED	Completamente verificata rispetto al registro ufficiale
true	FAILED	Parziale: alcuni campi potrebbero essere non aggiornati o mancanti
false	UNKNOWN	Solo dati forniti dall’utente; nessuna corrispondenza nel registro

Risultati della verifica incrociata

Ogni verifica incrociata viene eseguita per campo e restituisce uno dei seguenti valori:

MATCH: i dati forniti corrispondono a quelli del registro.
MISMATCH: divergenza significativa. Segnalata come avviso.
NO_DATA: uno dei due lati era vuoto; nessun confronto possibile.

Le mancate corrispondenze sono visibili campo per campo nella revisione della sessione nella console.

Cosa determina l’esito

Lo stato dell’azienda, il paese di costituzione, i risultati AML e la corrispondenza con i dati dichiarati alimentano la decisione come tag di avviso sul controllo del registro e sullo Screening AML. Il tuo workflow decide se ciascun avviso porta ad approvazione, revisione o rifiuto. Consulta valutazione del rischio per i segnali e le chiavi del workflow che li controllano.

Paesi supportati

La copertura varia da paese a paese: consulta paesi supportati per il dettaglio dei livelli per regione.

Passaggi successivi

Assetto proprietario

Identificazione dei titolari effettivi e catene di proprietà.

Schema della risposta

Dove compare ciascun campo nel payload.

Paesi supportati

Copertura per regione.

Primi passi

Funzionalità

Profili aziendali

Riferimento

Console

API registro imprese: estrazione automatica dati KYB

Ricerca nel registro

Precompilazione della ricerca con `expected_details`

Tipi di ricerca

Flusso di ricerca

Dati recuperati

Stati dell’azienda

Indicatore della fonte dei dati

Livelli di dati e prezzi

Dati del registro e dati forniti dall’utente

Campi del modulo di registro configurabili

Validazione del numero VAT e dell’identificativo fiscale

Verifica incrociata dei dati

Riepilogo finanziario

Campi aggiuntivi del registro

Affidabilità e stato di verifica

Risultati della verifica incrociata

Cosa determina l’esito

Paesi supportati

Passaggi successivi

Assetto proprietario

Schema della risposta

Paesi supportati

​Ricerca nel registro

​Precompilazione della ricerca con expected_details

​Tipi di ricerca

​Flusso di ricerca

​Dati recuperati

​Stati dell’azienda

​Indicatore della fonte dei dati

​Livelli di dati e prezzi

​Dati del registro e dati forniti dall’utente

​Campi del modulo di registro configurabili

​Validazione del numero VAT e dell’identificativo fiscale

​Verifica incrociata dei dati

​Riepilogo finanziario

​Campi aggiuntivi del registro

​Affidabilità e stato di verifica

​Risultati della verifica incrociata

​Cosa determina l’esito

​Paesi supportati

​Passaggi successivi

Assetto proprietario

Schema della risposta

Paesi supportati

Ricerca nel registro

Precompilazione della ricerca con `expected_details`

Tipi di ricerca

Flusso di ricerca

Dati recuperati

Stati dell’azienda

Indicatore della fonte dei dati

Livelli di dati e prezzi

Dati del registro e dati forniti dall’utente

Campi del modulo di registro configurabili

Validazione del numero VAT e dell’identificativo fiscale

Verifica incrociata dei dati

Riepilogo finanziario

Campi aggiuntivi del registro

Affidabilità e stato di verifica

Risultati della verifica incrociata

Cosa determina l’esito

Paesi supportati

Passaggi successivi