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 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. Trovare un numero nel tuo elenco spiega come cercarlo.

Gli esempi API leggono la chiave da BIRD_API_KEY, il suo host regionale 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}:

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:

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 spiega come ownership si collega al valore status del numero stesso.

Invia la documentazione dalla dashboard

1. Apri il numero dalla pagina 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. Imposta subject_kind su number, subject_id sull'identificatore nda_ del numero e country_code sul COUNTRY_CODE del numero stesso:

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 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, 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:

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, oppure scarica direttamente i byte con GET /v1/compliance/attachments/{attachment_id}.

Invia tutte le risposte

Invia le risposte con POST /v1/compliance/submissions. 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 <NUMBER_ID>, <PROGRAM>, <COUNTRY_CODE> e <ATTACHMENT_ID> con i tuoi valori. L'esempio mostra tre delle risposte richieste da un modulo:

{
  "subject_kind": "number",
  "subject_id": "<NUMBER_ID>",
  "program": "<PROGRAM>",
  "country_code": "<COUNTRY_CODE>",
  "answers": [
    { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" },
    { "key": "business_registration_number", "value": "90012768" },
    { "key": "business_registration_certificate", "attachment_id": "<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 spiega cosa viene conservato.

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 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, 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 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: correggila invece, come mostra 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. Per vedere l'esito di ogni risposta, leggi la richiesta con GET /v1/compliance/submissions/{submission_id} 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. 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:

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. 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, 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:

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. Quando le risposte sono presentate, il nuovo numero riporta under_review con il suo submission_id. Acquistare e rilasciare un numero descrive l'ordine stesso.

Riutilizzare un'identità aziendale

Usa GET /v1/compliance/identities/{identity_id} 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} oppure eliminala con DELETE /v1/compliance/identities/{identity_id}. 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 spiega come ottenere quella registrazione e come verificarne prima il prezzo.

Quando una richiesta viene rifiutata

Errori descrive il corpo della risposta di errore e il relativo remediation.

Passaggi successivi

• Panoramica dei numeri
• Acquistare e rilasciare un numero
• Gestire i tuoi numeri di telefono
• Migrare da Telserv a Bird