> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API registro KYB: ricerca e selezione aziende > Con Didit cerca nei registri delle imprese e recupera l'azienda al livello necessario: Lite (select), Shareholders o UBO, con prezzi per paese. ## Endpoint e fatturazione Le ricerche autonome riuscite che usano una fonte di dati aziendali a pagamento costano **\$0.50 per richiesta**, indipendentemente dal numero di candidati. I risultati vuoti, le ricerche non riuscite e i risultati forniti solo da altre fonti non vengono addebitati. Il recupero successivo del profilo viene fatturato separatamente. Il recupero è venduto in tre livelli di dati, ciascuno con un proprio endpoint, con prezzi diversi per paese ([prezzi per paese](https://docs.didit.me/it/getting-started/kyb-registry-pricing.md)): | Endpoint | Cosa ottieni | Prezzo | | - | - | - | | [`POST /v3/kyb/search/`](https://docs.didit.me/it/standalone-apis/kyb-registry-search) | Aziende candidate: nome, numero di registrazione, stato, tipo | \$0.50 quando vengono restituiti risultati da fonti a pagamento | | [`POST /v3/kyb/select/`](https://docs.didit.me/it/standalone-apis/kyb-registry-select) | **Lite**: il profilo aziendale (identificativi, stato, forma giuridica, data di costituzione, indirizzo registrato, attività, recapiti) e gli esponenti aziendali | Prezzo Lite: \$2.00-\$3.00 a seconda del paese | | [`POST /v3/kyb/shareholders/`](https://docs.didit.me/it/standalone-apis/kyb-registry-shareholders) | Lite più gli azionisti diretti con le rispettive fasce di partecipazione | Prezzo Shareholders: \$5.00-\$22.00 a seconda del paese | | [`POST /v3/kyb/ubo/`](https://docs.didit.me/it/standalone-apis/kyb-registry-ubo) | Shareholders più i titolari effettivi individuati lungo la catena di partecipazione | Prezzo UBO: \$9.00-\$96.00 a seconda del paese | `select` è il livello Lite: è ciò che un workflow KYB ospitato addebita per un controllo nel registro a livello Lite, e mantiene il contratto che ha sempre avuto. Per Europa si intendono lo Spazio economico europeo (EEA), il Regno Unito e la Svizzera. Una ricerca Shareholders o UBO interroga la fonte sull'assetto proprietario che serve il livello richiesto. Quando tale fonte risponde che non dispone di informazioni sull'azienda, la ricerca interroga anche le altre fonti registrali del paese, così un'azienda che la fonte sull'assetto proprietario non elenca viene comunque proposta come candidata invece di finire in inserimento manuale. I candidati trovati in questo modo mantengono il livello richiesto: al recupero viene ricontrollata la fonte sull'assetto proprietario e, se questa continua a non disporre di informazioni sull'azienda, viene consegnato e fatturato il profilo Lite, con `registry_ownership_status: "not_held"`. > [!NOTE] > > **Paghi il livello consegnato.** Ogni risposta contiene `registry_tier_requested` e `registry_tier_delivered`. Quando i registri del paese non hanno dati sull'assetto proprietario, oppure il registro non ha una registrazione di assetto proprietario per l'azienda selezionata, una richiesta di assetto proprietario viene consegnata e fatturata al livello più alto disponibile (di solito Lite), e `registry_ownership_status` ne indica il motivo. Una richiesta UBO il cui report elaborato non indica alcuna persona fisica come titolare effettivo viene consegnata e fatturata come Shareholders. > [!NOTE] > > **Versionamento.** Gli endpoint Shareholders e UBO esistono solo su `/v3/`. La commissione per la ricerca autonoma si applica anche a `/v2/kyb/search/`; il recupero del profilo viene fatturato separatamente. ## Stato dell'assetto proprietario `registry_ownership_status` indica cosa è successo alla parte relativa all'assetto proprietario di una richiesta Shareholders o UBO: | Valore | Significato | | - | - | | `not_requested` | La chiamata era un recupero Lite, quindi non è stato richiesto alcun assetto proprietario. | | `delivered` | Il registro ha fornito i dati sull'assetto proprietario, e il livello in `registry_tier_delivered` è quello che paghi. | | `not_held` | Il registro dell'assetto proprietario ha risposto ma non elenca questa azienda, quindi non dispone di alcun record di assetto da fornire: l'azienda è stata trovata da un'altra fonte del registro del paese. Il profilo Lite viene consegnato e fatturato al suo posto, con `registry_data.ownership_error: "company_not_found"`. | | `unavailable` | I dati sull'assetto proprietario non sono stati forniti per qualsiasi altro motivo: il record del registro non indica alcun titolare, oppure il registro non ha restituito affatto la sezione sull'assetto proprietario, oppure non è stato possibile interrogarlo. `registry_data.ownership_error` indica quale. Il profilo Lite viene consegnato e fatturato al suo posto. | | `pending` | La sezione sull'assetto proprietario non è ancora stata recuperata dal registro. Non viene addebitato nulla e `registry_tier_delivered` è `null` finché non avviene il recupero. | `not_held` e `unavailable` vengono entrambi consegnati e fatturati come Lite, ma non indicano lo stesso esito: `not_held` significa che la fonte sull'assetto proprietario non copre l'azienda, cioè una lacuna di copertura, mentre `unavailable` significa che i dati non sono stati forniti, a causa di un'interruzione o di una sezione lasciata vuota dal registro. `registry_data.ownership_error` indica il motivo. Le selezioni che in precedenza riportavano `unavailable` perché il registro dell'assetto proprietario non elencava l'azienda ora riportano `not_held`; se implementi una diramazione in base allo stato, tratta entrambi i casi come la stessa consegna Lite. Due dei suoi valori hanno significati diversi e non devono essere letti come lo stesso esito: | `ownership_error` | Significato | | - | - | | `no_owners_on_record` | Il registro ha risposto per la sezione sull'assetto proprietario e non indica alcun titolare. Il registro non ha nei propri archivi alcun prospetto dell'assetto proprietario dell'azienda. | | `ownership_section_unavailable` | Il registro non ha restituito la sezione sull'assetto proprietario, quindi per essa non è stato consegnato nulla. L'elenco manca, non è vuoto: non dice nulla su chi possiede l'azienda. | Una sezione che il registro non ha restituito viene registrata anche in modo strutturato, in `registry_data.section_errors`, indicizzata per sezione (`officers`, `shareholders`, `group_structure`) con lo stato con cui il registro ha risposto: ```json theme={null} { "section_errors": { "shareholders": { "status_code": 404 } } } ``` `section_errors` descrive la risposta che stai ricevendo, non la storia che ha portato ad essa. Una sezione non restituita alla prima richiesta e fornita in un passaggio successivo (vedi il recupero asincrono qui sotto) perde la sua voce, quindi `registry_ownership_status`, `ownership_error` e `section_errors` concordano sempre: una sezione `delivered` non ha mai una voce, e `no_owners_on_record` non è mai accompagnato da una voce per `shareholders`. Una sezione non viene inoltre mai consegnata in parte: se il registro fornisce la prima pagina di un elenco e poi non riesce a fornire una pagina successiva, il recupero non si considera completato in quel tentativo. Un recupero `pending` viene ritentato al passaggio successivo, mentre una nuova richiesta riceve l'errore di indisponibilità del registro. Quindi un elenco `officers` o degli azionisti consegnato è sempre l'elenco completo che il registro possiede. Tratta una sezione elencata in `section_errors` come dato mai consegnato, mai come risultato vuoto: un elenco `officers` o degli azionisti vuoto accanto a una voce `section_errors` per la stessa sezione non dice nulla sull'azienda. ### Assetto proprietario recuperato in modo asincrono Alcuni registri vengono interrogati su richiesta: la prima richiesta per un'azienda su cui la fonte non è mai stata interrogata non restituisce alcuna sezione sull'assetto proprietario mentre viene recuperata, e i dati arrivano entro un paio di minuti. Segnalarlo come "nessun assetto proprietario registrato" sottostimerebbe un'azienda che in realtà ha degli azionisti, quindi in questo caso la richiesta restituisce `pending`. Mentre un recupero è `pending`, anche `fetch_status` è `pending` e lo stato della risposta è `202 Accepted`. Didit ritenta la sezione autonomamente e completa il recupero senza ulteriori chiamate da parte tua: * non appena arrivano i dati sull'assetto proprietario, gli azionisti e i titolari effettivi compaiono nella verifica salvata, `registry_tier_delivered` diventa il livello che è stato fornito e l'utilizzo viene addebitato a quel livello; * se la sezione è ancora vuota alla chiusura della finestra di nuovo tentativo, lo stato diventa `unavailable` e la richiesta viene consegnata e fatturata come Lite. Conserva il `request_id` e interroga `GET /v3/session/{request_id}/decision/` finché `registry_checks[0].company.fetch_status` non diventa `resolved`. Non ripetere la richiesta di recupero mentre è `pending`: ogni nuova `POST` è una richiesta separata, fatturabile separatamente. Usa `POST /v3/kyb/search/` per trovare le aziende candidate. La ricerca non crea una verifica salvata. L'input `tier` della ricerca sceglie la catena su cui cerca: vedi [livello di ricerca](https://docs.didit.me/it/standalone-apis/kyb-registry-search.md#livello-di-ricerca). Le ricerche nei registri possono richiedere circa 90 secondi. Invia `webhook_url` se vuoi che Didit restituisca subito la risposta e invii una notifica al tuo URL quando i candidati sono pronti. La callback di ricerca non è firmata di proposito, quindi per questa notifica leggera non devi configurare un segreto condiviso. Usa `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/` con il `kyb_response_id` restituito per recuperare il profilo al livello che ti serve. Il recupero è fatturabile e salva il risultato come Manual Check nella Business Console. ## Flusso tipico 1. Cerca per nome dell'azienda, numero di registrazione e paese, sul `tier` che intendi acquistare (`basic` è la catena Lite predefinita; `shareholders` e `ubo` cercano nella catena di quel livello). 2. Se `search_resolved=false`, attendi la callback facoltativa `webhook_url` invece di interrogare il servizio. 3. Mostra i candidati restituiti al tuo operatore o cliente. 4. Recupera il `kyb_response_id` corrispondente al livello che ti serve (select per Lite, shareholders o ubo). 5. Conserva il `request_id` restituito e usalo per recuperare il risultato salvato della verifica aziendale. ## Callback di ricerca Quando il provider comunica a Didit che la ricerca è completata, Didit invia una singola richiesta `POST` al tuo `webhook_url`: ```json theme={null} { "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91", "event_type": "kyb.registry_search.resolved", "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85", "vendor_data": "business-123", "metadata": { "source": "onboarding" }, "search_status": "resolved", "search_resolved": true, "kyb_registry": { "companies": [ { "kyb_response_id": "kyb_resp_123", "name": "TESCO PLC", "registration_number": "00445790", "status": "active", "type": "Public Limited Company", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA", "risk_level": null, "fetch_status": "pending" } ], "pagination": { "total": 1, "page": 1, "per_page": 25 }, "search_status": "resolved", "search_resolved": true }, "timestamp": 1767225600, "created_at": 1767225600 } ``` Considera il callback come una notifica di consegna. Usa il `kyb_response_id` restituito con `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/` per eseguire il recupero del profilo nel registro, che è a pagamento. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.