--- title: "Presentare la documentazione di titolarità di un numero" description: "Presenta la documentazione di titolarità che un paese richiede per un numero di telefono, dalla dashboard o con l'API, segui la revisione e correggi le risposte rifiutate." canonical: "https://bird.com/it-it/documentazione/guides/numbers/ownership-paperwork" --- # Presentare la documentazione di titolarità di un numero Alcuni paesi chiedono chi detiene un numero prima che possa gestire traffico. Finché la documentazione non viene accettata e la registrazione del numero non è completata, il numero ti è assegnato e viene fatturato, ma il suo `status` è `pending_ownership_registration`: non gestisce chiamate vocali in entrata o in uscita e non invia SMS. Il numero gestisce traffico quando il suo `status` è `active` e il suo `ownership.blocked_at` è `null`. Presenti la documentazione dalla dashboard o con l'API, ed entrambe le strade usano gli stessi requisiti, le stesse regole di revisione e lo stesso processo di registrazione. Il campo `ownership.next` del numero indica ogni passaggio, compreso il momento in cui presentare una nuova richiesta. Le risposte che presenti costituiscono una dichiarazione legale resa a nome della tua azienda. Una volta accettate, vengono trasmesse all'operatore o all'autorità di regolamentazione di quel paese a nome dell'azienda che descrivono. Per questo, verificale con chi ne è responsabile prima di presentarle e non lasciare che un processo automatico presenti risposte che nessuno ha controllato. ## Prima di iniziare - Per presentare la documentazione dalla dashboard, il tuo ruolo nello spazio di lavoro deve consentire la modifica dei dati di conformità. Senza questo permesso, il numero mostra lo stato di titolarità ma nessun pulsante per presentarla. - Per presentare la documentazione tramite gli endpoint di conformità autonomi, serve una [chiave API](/docs/guides/authentication) con l'ambito `compliance` a livello di scrittura. Una chiave con livello di lettura può controllare i requisiti e l'avanzamento della revisione, ma non presentare. Per leggere il numero serve anche l'ambito `numbers` a livello di lettura. Nel selettore delle chiavi della dashboard, `compliance` si trova in **Compliance**. - L'identificatore `nda_` del numero, ottenuto da [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). [Trovare un numero nel tuo elenco](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) spiega come cercarlo. Gli esempi API leggono la chiave da `BIRD_API_KEY`, il suo [host regionale](/docs/api/regions) da `BIRD_API_URL` e l'identificatore del numero da `NUMBER_ID`. Ogni passaggio successivo indica la variabile che imposta. I comandi `jq` estraggono un campo da una risposta; se non usi `jq`, leggi il campo manualmente. ## Verificare se un numero richiede documentazione Leggi il numero con [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number): ```bash curl "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Conserva il valore `country_code` del numero come `COUNTRY_CODE`; servirà sia alla lettura dei requisiti sia all'invio: ```bash COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code) ``` `ownership` è `null` quando il paese del numero non richiede alcuna documentazione. È `null` anche quando non siamo riusciti a leggere l'avanzamento della documentazione e sul numero non risulta alcun blocco; in questo caso leggi di nuovo il numero. Altrimenti contiene: - `status`: `needs_input` indica che mancano risposte o che vanno corrette, `under_review` indica che le tue risposte sono in revisione, `approval_pending` indica che la documentazione è stata accettata e la registrazione è ancora in sospeso; le chiamate e gli SMS in uscita restano bloccati finché `blocked_at` è impostato. `approved` indica che la registrazione è approvata, anche se le chiamate e gli SMS in uscita restano bloccati finché `blocked_at` è impostato. `not_required` indica che non viene richiesto altro. `rejected` indica che l'invio è stato chiuso, oppure che una scadenza per le correzioni è passata, e non accetta più correzioni. Contatta l'assistenza per farlo riaprire. `unknown` indica che non è stato possibile leggere lo stato; leggi di nuovo il numero. - `next`: i passaggi che fanno avanzare la documentazione, in ordine. Un passaggio `wait` indica che al momento non ti viene richiesto nulla. Leggilo di nuovo dopo ogni modifica. - `submission_id`: l'invio più recente per il numero, se ne esiste uno. - `blocked_at`: il momento in cui è iniziato il blocco per la titolarità, oppure `null` quando il blocco è stato rimosso. Il blocco interrompe le chiamate vocali in entrata e in uscita e gli SMS in uscita. [Lo stato di un numero assegnato](/docs/guides/numbers/overview#the-status-of-an-allocated-number) spiega come `ownership` si collega al valore `status` del numero stesso. ## Invia la documentazione dalla dashboard 1. Apri il numero dalla pagina [**Numbers**](https://bird.com/dashboard/w/numbers). La riga **Ownership** mostra lo stato della documentazione e i passaggi successivi. 2. Quando lo stato è **Details needed**, seleziona **Update ownership details**. Si apre il modulo **Prove ownership of this number**. 3. Scegli l'azienda titolare del numero, oppure descrivine una nuova, quindi rispondi a ogni voce e carica i documenti richiesti. Le voci che prevedono un modulo vuoto ne forniscono il link: scaricalo, compilalo e ricaricalo. 4. Seleziona **Submit answers**. La riga **Ownership** passa a **Under review**. Se un revisore rifiuta una risposta, la riga torna a **Details needed**: seleziona di nuovo **Update ownership details**, correggi le risposte indicate dal modulo, quindi seleziona **Update ownership details** in fondo al modulo per inviarle. Se per il paese del numero non esiste ancora un modulo, la pagina del modulo mostra **Ownership form unavailable**. Contatta l'assistenza per richiederlo per quel paese. ## Invia la documentazione con API Per inviare la documentazione con API, leggi cosa richiede il paese, carica ogni documento, invia tutte le risposte in un'unica volta, quindi leggi il numero per seguire la revisione. ### Leggi cosa richiede il paese Leggi i requisiti per il numero con [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements). Imposta `subject_kind` su `number`, `subject_id` sull'identificatore `nda_` del numero e `country_code` sul `COUNTRY_CODE` del numero stesso: ```bash curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` La risposta indica il `program` con cui il numero viene registrato, che dipende dal tipo di numero; conservalo come `PROGRAM`. Elenca in `fields` ogni voce a cui rispondere, nell'ordine in cui presentarle. Per ogni campo: - `key` è la chiave con cui invii la risposta. - `data_type` indica come rispondere. Un campo `document` accetta un file caricato; tutti gli altri tipi accettano una stringa, quindi un numero si invia come `"1500"` e un sì o no come `"true"`. Un campo `enum` accetta uno dei suoi `options`. - `required` indica se l'approvazione dipende dal campo, e `help_text` descrive com'è una risposta valida. - `max_items` è impostato sui campi che accettano più di una risposta. - `template_url` rimanda a un modulo vuoto da scaricare, compilare e ricaricare, se il campo ne prevede uno. - `state` indica lo stato della voce: `not_supplied` prima che tu risponda, poi `supplied`, `in_review`, `approved` o `rejected`, con il `reason` del revisore su una voce rifiutata. Una risposta accettata può in seguito risultare `expired` e va fornita di nuovo, mentre `not_applicable` indica una voce che non ti riguarda. `submission_id` è `null` finché non invii la pratica. `needs_input` è `true` finché una qualsiasi voce attende una tua azione. Un `422` con [`E19001`](/docs/api/errors/E19001) significa che non abbiamo ancora un modulo di titolarità per quel paese. Contatta l'assistenza per richiederlo. ### Carica ogni documento Carica ogni file richiesto da un campo `document` con [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment), come corpo `multipart/form-data` con i byte in una parte `file`. Conserva come `ATTACHMENT_ID` il valore `id` della risposta, cioè l'identificatore `tca_` dell'allegato: ```bash curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --form "file=@registration-certificate.pdf" ``` Sono accettati file PNG, JPEG e PDF fino a 10 MB, e il tipo viene determinato dal contenuto del file. Una risposta `201` restituisce il nuovo allegato. Se carichi di nuovo lo stesso file, ricevi il primo allegato con `200`, quindi un nuovo tentativo di caricamento non crea duplicati. Un allegato non citato da alcun invio scade dopo sette giorni. Il valore `download_url` dell'allegato è un link firmato valido per 24 ore dal momento in cui hai recuperato l'allegato. Per ottenerne uno nuovo, elenca i tuoi allegati con [`GET /v1/compliance/attachments`](/docs/api/reference/list-compliance-attachments), oppure scarica direttamente i byte con [`GET /v1/compliance/attachments/{attachment_id}`](/docs/api/reference/get-compliance-attachment). ### Invia tutte le risposte Invia le risposte con [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission). Invia `subject_kind` e `subject_id`, il valore `program` restituito dalla lettura dei requisiti e il valore `country_code` del numero. In `answers` invia una voce per ogni campo il cui `required` è `true` e una per ogni campo facoltativo per cui hai una risposta reale; ometti un campo facoltativo anziché inventarne il valore. Un campo tipizzato accetta `value`, un campo documento accetta `attachment_id` e un campo con `max_items` accetta `values` o `attachment_ids`. Salva il corpo come `submission.json`, sostituendo ``, ``, `` e `` con i tuoi valori. L'esempio mostra tre delle risposte richieste da un modulo: ```json { "subject_kind": "number", "subject_id": "", "program": "", "country_code": "", "answers": [ { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" }, { "key": "business_registration_number", "value": "90012768" }, { "key": "business_registration_certificate", "attachment_id": "" } ] } ``` Invialo con un `Idempotency-Key`. Riutilizza la chiave solo per riprovare con lo stesso corpo: un rifiuto può essere conservato e riproposto, quindi dopo un `422` correggi il corpo e invialo con una nuova chiave. [Idempotenza](/docs/guides/idempotency) spiega cosa viene conservato. ```bash curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: ownership-$NUMBER_ID" \ --data-binary @submission.json ``` Non esistono bozze: questa richiesta invia le risposte in revisione, quindi deve contenere tutte le risposte obbligatorie. Se ometti un campo obbligatorio o il modulo rifiuta una risposta, ricevi un `422` con [`E01001`](/docs/api/errors/E01001) e una voce in `details` per ogni campo, indicato in `param`, e non viene inviato nulla. Una risposta `201` restituisce l'invio con tutte le risposte. Conserva come `SUBMISSION_ID` il suo `id`, cioè l'identificatore `csb_` dell'invio. Un'azienda descritta dal tuo spazio di lavoro è un'identità. Creala nell'**Identity Center** della dashboard oppure con [`POST /v1/compliance/identities`](/docs/api/reference/create-compliance-identity), inviando il suo `name` visualizzato. Un invio per un numero può anche contenere un `identity` inline al posto di un `identity_id`. Il valore `identity_id` della risposta all'invio indica la nuova identità, che `POST /v1/compliance/identities` restituisce come `id`; riutilizzala per i numeri successivi anziché crearne un'altra. Per presentare la documentazione per un'identità, aggiungi il suo `identity_id`: le risposte che contiene completano quelle che ometti. [`GET /v1/compliance/identities`](/docs/api/reference/list-compliance-identities) elenca le identità aziendali. Le risposte a valore singolo che presenti vengono salvate sull'identità qualunque sia l'esito della revisione, quindi il successivo invio che la indica parte da queste; documenti e risposte a più valori vengono richiesti ogni volta. Usa un'identità per azienda: se presenti documentazione per più clienti finali, assegna a ciascuno la propria identità, altrimenti le risposte approvate di un cliente completano quelle di un altro. Segui `ownership.next` invece di presentare di nuovo la documentazione. Un numero ha una sola richiesta per ogni versione del modulo del suo paese, quindi una nuova presentazione mentre quella richiesta è aperta riceve `409` con [`E19009`](/docs/api/errors/E19009): correggila invece, come mostra [Correggere una risposta rifiutata](#correggere-una-risposta-rifiutata). Quando riapriamo una richiesta chiusa dopo una modifica del modulo, `next` chiede una nuova richiesta a `POST /v1/compliance/submissions`. ### Seguire la revisione Ogni risposta viene revisionata singolarmente. Leggi di nuovo il numero e controlla `ownership.status` e `ownership.next`, come in [Verificare se un numero richiede documentazione](#verificare-se-un-numero-richiede-documentazione). Per vedere l'esito di ogni risposta, leggi la richiesta con [`GET /v1/compliance/submissions/{submission_id}`](/docs/api/reference/get-workspace-compliance-submission) oppure leggi di nuovo i requisiti: ogni campo riporta il proprio `state` e, se rifiutato, il proprio `reason`. Al termine di una revisione, inviamo l'esito via email ai proprietari della tua organizzazione e, se presente, all'ultima persona registrata che ha presentato o corretto la richiesta. Una prima presentazione tramite chiave API viene notificata ai proprietari. Una correzione successiva tramite chiave API mantiene tra i destinatari la persona registrata in precedenza. La tua integrazione conosce l'esito leggendo `ownership.status`. ### Correggere una risposta rifiutata Invia le risposte sostitutive a [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission). Includi solo le risposte che sostituisci; le altre restano invariate. Prendi il valore `submission_id` dal campo `ownership` del numero o dalla lettura dei requisiti: ```bash curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: ownership-fix-1-$NUMBER_ID" \ --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}' ``` Una risposta `200` restituisce la richiesta con le tue sostituzioni, che tornano in revisione. Quando nessuna risposta obbligatoria è più rifiutata, scaduta o mancante, il campo `ownership.status` del numero torna a `under_review`. Sostituisci le risposte il cui `state` è `rejected`, `expired` o `not_supplied`. Se chiediamo una correzione dopo aver accettato le tue risposte, puoi sostituire anche una risposta il cui `editable_for_verifier_repair` è `true`, finché quella correzione non si chiude. Una risposta in qualsiasi altro stato, ad esempio ancora in revisione o accettata al di fuori di una correzione da noi richiesta, riceve `422` con [`E19003`](/docs/api/errors/E19003). Un documento sostitutivo è un nuovo caricamento: caricalo prima e invia il suo `attachment_id`. ## Presentare la documentazione con l'ordine Se conosci le risposte al momento dell'acquisto del numero, inviale nel blocco `compliance` dell'ordine su [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order), con la stessa struttura `answers` usata dalla richiesta. Per leggere cosa chiede il paese prima di possedere il numero, chiama la lettura dei requisiti senza `subject_id`, impostando `COUNTRY_CODE` e `NUMBER_TYPE` sui valori `country_code` e `number_type` del numero in [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers): ```bash curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&country_code=$COUNTRY_CODE&program=$NUMBER_TYPE" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Un ordine con un blocco `compliance` usa l'ambito `numbers` già previsto per l'ordine, a livello di scrittura. Una volta accettato, l'ordine viene completato in ogni caso: se la presentazione nel blocco `compliance` viene rifiutata, il numero resta tuo e presenti la documentazione con `POST /v1/compliance/submissions` come in [Inviare tutte le risposte](#invia-tutte-le-risposte). Quando le risposte sono presentate, il nuovo numero riporta `under_review` con il suo `submission_id`. [Acquistare e rilasciare un numero](/docs/guides/numbers/buying-numbers) descrive l'ordine stesso. ## Riutilizzare un'identità aziendale Usa [`GET /v1/compliance/identities/{identity_id}`](/docs/api/reference/get-compliance-identity) per leggere l'azienda e le sue risposte salvate. Le risposte salvate possono includere un `state` di revisione, `reason` e `decided_at`; un valore senza decisione di revisione può omettere il proprio stato. Rinomina l'azienda con [`PATCH /v1/compliance/identities/{identity_id}`](/docs/api/reference/update-compliance-identity) oppure eliminala con [`DELETE /v1/compliance/identities/{identity_id}`](/docs/api/reference/delete-compliance-identity). Le letture richiedono `compliance:read`; creazione, ridenominazione ed eliminazione richiedono `compliance:write`. Per verificare l'azienda stessa, crea prima l'identità. Leggi i requisiti con `subject_kind=identity`, il suo identificatore `cid_` come `subject_id`, `program=business` e `country_code=ZZ`. Presenta la documentazione per quella stessa identità. Un'identità inline in un invio per un numero non sostituisce questo flusso di verifica dell'identità. La revisione si basa sui dati aziendali inviati, sui contatti dichiarati e sulle prove di verifica. Presentare la documentazione tramite una chiave API o dalla dashboard non stabilisce un rapporto aziendale diverso. Mantieni accurati i dati di contatto e fornisci le prove richieste dal modulo. ## Presentare invece la documentazione per un mittente SMS La documentazione di un mittente SMS usa le stesse richieste di requisiti, allegati, invio e correzione, con la registrazione del mittente come oggetto. [Registrare un mittente SMS tramite API](/docs/guides/sms/sender-registration-api) spiega come ottenere quella registrazione e come verificarne prima il prezzo. ## Quando una richiesta viene rifiutata | Risposta | Significato | Cosa fare | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `403` con `E02035` | Per una scrittura sugli endpoint di conformità autonomi, la chiave non ha lo scope `compliance` oppure lo ha solo a livello di lettura. | Usa una chiave con `compliance` a livello di scrittura. | | `422` con `E19001` | Non abbiamo ancora un modulo di titolarità per il paese del numero. | Contatta l'assistenza per richiederlo per quel paese. | | `422` con `E19013` | La lettura dei requisiti non conteneva né `subject_id` né `program`. | Invia l'identificatore `nda_` del numero, oppure `program` se leggi i requisiti prima dell'acquisto. | | `422` con `E01001` | L'invio omette un campo obbligatorio o contiene una risposta non valida. | Correggi ogni campo indicato in `details` e invia di nuovo l'intero invio con una nuova chiave di idempotenza. | | `409` con `E19009` | Il numero ha già un invio per il suo modulo attuale. | Sostituisci le risposte da correggere con la richiesta di nuova fornitura. | | `409` con `E01009` | La nuova fornitura riguarda un invio chiuso. | Contatta l'assistenza. Se lo riapriamo, invia ciò che indica `ownership.next`. | | `422` con `E19003` | Una sostituzione riguarda una risposta in revisione o accettata al di fuori di una correzione richiesta da noi. | Sostituisci solo le risposte il cui `state` è `rejected`, `expired` o `not_supplied`. | | `404` con `E01008` | Il numero non è in questo spazio di lavoro, oppure `country_code` non è il paese del numero. | Invia il `country_code` indicato da `GET /v1/numbers/{number_id}`. | [Errori](/docs/guides/errors) descrive il corpo della risposta di errore e il relativo `remediation`. ## Passaggi successivi - [Panoramica dei numeri](/docs/guides/numbers/overview) - [Acquistare e rilasciare un numero](/docs/guides/numbers/buying-numbers) - [Gestire i tuoi numeri di telefono](/docs/guides/numbers/managing-numbers) - [Migrare da Telserv a Bird](/docs/guides/numbers/migrate/telserv) ## Related resources - [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer) - [SMS numbers](/sms-api/features/numbers) (product) - [Number types](/docs/guides/numbers/number-types) (docs) [Get an implementation brief](/learn/workspace?topic=phone-numbers)