--- title: "Migrare da Telserv a Bird" description: "Sposta un'integrazione con l'API partner di Telserv verso l'Bird API, mappa ogni gruppo di operazioni alla rispettiva chiamata Bird e scopri come ogni attività viene svolta in Bird." canonical: "https://bird.com/it-it/documentazione/guides/numbers/migrate/telserv" --- # Migrare da Telserv a Bird Questa guida è per le integrazioni che chiamano l'API partner di Telserv, V1 o V2, per acquistare, instradare e rilasciare numeri, e che ora passano all'Bird API. L'Bird API serve ogni prodotto Bird, quindi le sue operazioni su numeri e voce seguono le convenzioni di Bird anziché quelle di Telserv. La maggior parte delle funzionalità usate dalla tua integrazione ha una chiamata Bird corrispondente. Endpoint, payload, identificatori e autenticazione sono diversi, quindi pianifica una riscrittura dell'integrazione. Dove Bird svolge un'attività in modo diverso, questa guida mostra come. Questa guida è in fase di sviluppo. Copre ciò che Bird fa oggi e cresce man mano che procede la migrazione. Se un'operazione Telserv che usi non è elencata qui, richiede ancora analisi e lavoro prima di poter essere aggiunta; chiedi al tuo contatto per la migrazione. ## Prima di iniziare - Un'organizzazione Bird con verifica dell'identità completata, necessaria per il primo acquisto di un numero. - Una [chiave API](/docs/api/authentication) con gli scope usati dalle ricette: `numbers` a livello di scrittura per numeri e ordini, `compliance` a livello di scrittura per le operazioni autonome sulla documentazione di titolarità, e `voice_management` a livello di scrittura per trunk SIP, numeri voce e numeri verificati. La chiamata di test richiede anche `voice:write`, e la lettura dei leg di chiamata richiede `voice:read`. - Saldo del wallet. Gli ordini vengono pagati dal wallet. [Quando un ordine viene rifiutato](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) spiega i rifiuti `402` e `412`. I numeri che la tua integrazione gestisce in Telserv non devono essere riacquistati. Una volta spostati nel tuo spazio di lavoro Bird, compaiono in [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). Il tuo contatto per la migrazione conferma quando ciò avviene. Per ottenere l'identificatore `nda_` di un numero spostato, cercalo con `GET /v1/numbers?number=` indicando le cifre con il prefisso internazionale e conserva il `id` come `NUMBER_ID`. Gli esempi leggono la tua chiave da `BIRD_API_KEY` e il suo [host regionale](/docs/api/regions) da `BIRD_API_URL`: `https://eu1.platform.bird.com` per una chiave `bk_eu1_`, oppure `https://us1.platform.bird.com` per una chiave `bk_us1_`. Le altre variabili, come `TRUNK_ID` e `NUMBER_ID`, contengono un identificatore di una risposta precedente; ogni passaggio indica quale imposta. ## Cosa cambia nel contratto | Area | API partner Telserv | Bird API | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Autenticazione | Header `X-ApiKey` (V2) o parametro `apiKey` (V1), verificato rispetto alla tua allowlist IP | `Authorization: Bearer` con una chiave API i cui scope indicano le aree di prodotto utilizzabili. Una allowlist IP è opzionale: impostala in **IP restrictions** sulla chiave in [**API keys**](https://bird.com/dashboard/w/api-keys) | | Identificatori | Interi. L'acquisto di un numero gli assegna un nuovo `id` | TypeID con prefisso come `nda_`, `nor_`, `vnu_` e `spt_`. Un numero mantiene il proprio id `nda_` finché è allocato a te | | Numeri di telefono | Cifre senza `+` iniziale | E.164 con lo `+` iniziale | | Paginazione | Offset `start` e `limit`, fino a 1000 per pagina | Cursori: `limit` fino a 100 (predefinito 25), poi `starting_after` impostato sul `next_cursor` della pagina precedente. Vedi [Paginazione](/docs/api/pagination) | | Errori | `errorCode` indica una classe di eccezione e `403` copre sia una risorsa mancante sia molti errori di validazione | `error.code` è un codice `E` stabile con una pagina di documentazione e, dove un recupero è noto, un `remediation`. Una risorsa mancante risponde `404`, una precondizione non soddisfatta `412` e un input non valido `422` con i dettagli dei campi. Vedi [Errori](/docs/guides/errors) | | Ambienti | LIVE e SANDBOX, ciascuno con le proprie chiavi | Un solo ambiente. Ogni ordine acquista e addebita un numero reale, e ogni chiamata di test è una chiamata reale | | Nuovi tentativi | Nessuna chiave di idempotenza | Un header `Idempotency-Key` sulle scritture. La stessa chiave e lo stesso body restituiscono la prima risposta con `Idempotency-Replay: true`; la stessa chiave con un body diverso risponde `409`. Vedi [Idempotenza](/docs/guides/idempotency) | L'Bird API rifiuta un parametro di query che non riconosce con `422` e [`E01029`](/docs/api/errors/E01029). Rimuovi dalle tue richieste i filtri esclusivi di Telserv, come `city`, invece di passarli invariati. ## Due identificatori per un numero Un numero con capacità vocale assegnato al tuo spazio di lavoro ha due record, ciascuno con il proprio identificatore: - L'allocazione, restituita da [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). Il suo `id` inizia con `nda_` per un numero dedicato e con `nal_` per uno condiviso, e il `number_id` di un ordine è l'identificatore `nda_` del numero acquistato. Usala per leggere, denominare e referenziare il numero, e per rilasciare un numero dedicato. - Il record vocale, `vnu_`, restituito da [`GET /v1/voice/numbers`](/docs/api/reference/list-voice-numbers). Usalo per leggere e modificare dove vanno le chiamate in entrata del numero. Un numero senza capacità vocale, ad esempio un numero solo SMS, non ha un record vocale. Le operazioni vocali rifiutano un identificatore `nda_` o `nal_` con `422`. Per trovare il record vocale di un numero, elenca i numeri vocali con `search` impostato sulle cifre del numero e prendi la voce il cui `provider.number_id` corrisponde al `id` dell'allocazione. [Instrada un numero verso il tuo trunk SIP](#instradare-un-numero-verso-il-tuo-trunk-sip) mostra la richiesta, e [Gestire i tuoi numeri di telefono](/docs/guides/numbers/managing-numbers#find-the-voice-record-that-routes-a-number) tratta la ricerca. Il `GET /numbers/{dnisId}` di Telserv diventa due letture in Bird: l'allocazione per lo stato e la documentazione di titolarità, e il record vocale per l'instradamento. ## Mappare le operazioni Telserv su Bird Ogni tabella elenca un'operazione, la chiamata Telserv che la eseguiva e la chiamata Bird che la esegue ora. Le note sotto ogni tabella descrivono cosa cambia nella richiesta o nella risposta. ### Acquisto | Operazione | Telserv | Bird | | ----------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | Cerca numeri in vendita | `GET /shop` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers) | | Verifica un numero | `GET /shop/{stockDnisId}` | [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number) | | Acquista un numero | `POST /shop/{stockDnisId}` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | | Riserva un numero | `POST /shop/{stockDnisId}/reserve`, `GET /shop/reserved` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | - **Ricerca.** `country_code` è obbligatorio, quindi una ricerca copre un solo paese. `prefix` accetta le cifre nazionali dopo il prefisso internazionale: il `prefix=3170` di Telserv diventa `country_code=NL&prefix=70`. Restringi per prefisso locale con `prefix` al posto di `city`, e per `number_type` e `capabilities` al posto di `productId`. - **Documentazione nei risultati di ricerca.** Ogni risultato contiene `ownership_registration_required` al posto del filtro `excludeNumbersRequireVerification`. Un valore `true` indica che il numero è fatturato dall'acquisto, ma non invia SMS e non gestisce chiamate vocali in entrata o in uscita finché la documentazione non viene approvata. - **Verifica di un singolo numero.** Si indirizza tramite il suo numero E.164. - **Prezzi.** Telserv restituiva `pricing.staticPricing` nelle letture dettagliate di un numero e di un prodotto. In Bird, ogni risultato di ricerca contiene il prezzo per la tua organizzazione in `pricing`: `setup_price` al posto di `nrc`, e `recurring_price` per `recurring_period` al posto di `mrc`, con `intervals_per_charge` per il numero di periodi coperti da un singolo addebito. [Cerca e acquista un numero con il tuo riferimento](#cerca-e-acquista-un-numero-con-il-tuo-riferimento) descrive i campi del prezzo. - **Acquisto.** Invia `number` e un `reference` opzionale. L'ordine è pagato dal tuo wallet. La maggior parte degli ordini risponde `201`; un ordine in attesa di un operatore risponde `202`, e lo interroghi periodicamente. - **Prenotazione.** Ordinare il numero lo riserva. Verifica prima un candidato, poi ordinalo. ### Numeri | Operazione | Telserv | Bird | | -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Elencare i numeri | `GET /numbers` | [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) | | Leggere un numero | `GET /numbers/{dnisId}` | [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) con l'id `nda_` o `nal_` dell'allocazione, e [`GET /v1/voice/numbers/{number_id}`](/docs/api/reference/get-voice-number) con l'id `vnu_` del record vocale | | Modificare un numero | `PATCH /numbers/{dnisId}` | [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number) con l'id `nda_` o `nal_` dell'allocazione, e [`PATCH /v1/voice/numbers/{number_id}`](/docs/api/reference/update-voice-number) con l'id `vnu_` del record vocale | | Rilasciare un numero | `DELETE /numbers/{dnisId}?requestedCancelDate=` | [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) alla fine del periodo pagato, oppure [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) subito, entrambi con l'id `nda_` dell'allocazione | - **Lista.** La lista contiene i numeri attualmente assegnati a te. Un numero rilasciato che hai ordinato in Bird resta visibile tramite il suo ordine in [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders). [Riconcilia i tuoi numeri](#riconciliare-i-tuoi-numeri) mappa i filtri. - **Lettura.** Stato, documentazione di titolarità e prezzo si trovano sull'allocazione, mentre l'instradamento è sul record vocale. L'oggetto `pricing` dell'allocazione, con `recurring_price` per `recurring_period` e `intervals_per_charge`, sostituisce `pricing.staticPricing.mrc`, e anche la lista lo riporta, mentre il `GET /numbers` di Telserv non lo faceva. - **Modifica.** `name` e `reference` sono sull'allocazione, e l'instradamento è sul record vocale. Imposta un codec forzato e un limite alle chiamate simultanee sulla tua apparecchiatura SIP. `destinationDistributionType` diventa `priority` del gateway sul trunk SIP: `FailOver` assegna a ogni gateway un `priority` diverso, e `RoundRobin` assegna loro lo stesso. - **Rilascio.** `DELETE` mantiene il numero fino alla fine del periodo già pagato e lo rilascia a quel punto. `POST …/release` lo rilascia immediatamente. Nessuna delle due accetta una data. [Rilasciare un numero](#rilasciare-un-numero) mostra entrambe le richieste. ### Destinazioni e profili | Operazione | Telserv | Bird | | ------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Inviare le chiamate all'apparecchiatura SIP | `POST /numbers/{dnisId}/destinations` | [`POST /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/create-voice-trunk-gateway), poi instrada `trunk` | | Inoltrare le chiamate a un telefono | `POST /numbers/{dnisId}/destinations` | Instrada `forward` | | Smettere di ricevere chiamate | `DELETE /numbers/{dnisId}/destinations` | Instrada `reject` | | Leggere i profili di destinazione | `GET /destinationprofiles`, `GET /destinationprofiles/{id}` | [`GET /v1/voice/trunks`](/docs/api/reference/list-voice-trunks) e [`GET /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/list-voice-trunk-gateways) | | Applicare un profilo a un numero | `POST /numbers/{dnisId}/destinations/profile` | Instrada `trunk` con `trunk_id` | - **Apparecchiatura SIP.** Un gateway appartiene al trunk e serve ogni numero instradato verso di esso, quindi numeri che richiedono liste di destinazione diverse necessitano di trunk diversi. `sortOrder` diventa `priority`. Applica tempo di squillo e finestre temporali sulla tua apparecchiatura SIP. - **Inoltro.** Imposta `forward_to` e `forward_as`. `forward_to` deve essere uno dei tuoi [numeri verificati](/docs/guides/voice/caller-ids); un numero non verificato risponde `412` con [`E21053`](/docs/api/errors/E21053). `forward_as` sceglie quale numero la chiamata inoltrata mostra come chiamante. Un numero ha un solo instradamento alla volta, quindi per ripiegare dall'apparecchiatura SIP a un numero telefonico, inoltra la chiamata dalla tua apparecchiatura SIP. - **Smettere di ricevere chiamate.** Il numero rifiuta le chiamate finché non lo instradi di nuovo. Per mantenere un'impostazione predefinita fissa al posto di un profilo predefinito, instrada il numero verso un trunk che contiene i tuoi gateway predefiniti. - **Profili.** `distributionType` diventa `priority`: `FailOver` assegna a ogni gateway un `priority` diverso, e `RoundRobin` assegna a tutti lo stesso. La distribuzione è impostata per trunk, quindi numeri che richiedono una distribuzione diversa richiedono trunk diversi. Il segnaposto `{dnis}` diventa `{number}` in `destination_format`, e un `prefixCLIP` diventa il testo prima di `{number}` in `origination_format`. - **Applicare un profilo.** Un trunk è indirizzato tramite il suo identificatore `spt_`, mentre Telserv indirizzava un profilo per nome. ### Documenti e dati dell'utente finale | Operazione | Telserv | Bird | | ----------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Leggere i requisiti | `GET /products/conditions`, `GET /masterdata/productconditions` | [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements) per il numero, oppure con `program` e senza `subject_id` per il modulo che un paese richiede prima che tu possieda un numero | | Caricare un documento | `POST /numbers/{dnisId}/documents` | [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment), poi cita l'allegato nell'invio. Vedi [Inviare la documentazione di titolarità](#inviare-la-documentazione-di-titolarità) | | Inviare i dati dell'utente finale | `POST /numbers/{dnisId}/enduserdata` | [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), con i documenti, in un'unica richiesta. Vedi [Invia la documentazione di titolarità](#inviare-la-documentazione-di-titolarità) | | Sostituire un documento | Di nuovo `POST /numbers/{dnisId}/documents` | [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission) con le risposte rifiutate o scadute | | Controllare lo stato della documentazione | `GET /numbers/{dnisId}/documents` | `ownership` su [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number), e l'invio per l'esito di ogni risposta | - **Requisiti.** Il catalogo delle condizioni di Telserv copriva tutti i prodotti insieme; Bird legge un modulo alla volta. Richiedi i requisiti di un numero con `subject_kind=number`, il suo identificatore `nda_` come `subject_id` e il suo `country_code`, oppure leggi un modulo prima dell'acquisto con `program` impostato sul tipo di numero e senza `subject_id`. Ogni voce in `fields` sostituisce una condizione Telserv o un'etichetta dell'utente finale: il suo `key` è la chiave sotto cui rispondi, e `data_type` `document` indica una voce che richiede un file. - **Documenti.** Carica il file come `multipart/form-data` al posto di un `fileContent` in base64; [Carica ogni documento](/docs/guides/numbers/ownership-paperwork#upload-each-document) elenca i file accettati. Caricare due volte lo stesso file restituisce lo stesso allegato. Il solo caricamento non invia nulla: è l'invio che cita il suo `attachment_id` a farlo. - **Dati dell'utente finale e documenti insieme.** Telserv accettava ogni documento con una chiamata separata e i dati dell'utente finale come un unico elenco di etichette in un'altra chiamata. Bird accetta tutte le risposte, testuali e documenti, in un unico invio, e non esistono bozze: la richiesta invia le risposte per la revisione. Poi segui `ownership.next`, che indica un nuovo inoltro per le correzioni e un nuovo invio solo quando serve ([Invia tutte le risposte](/docs/guides/numbers/ownership-paperwork#submit-every-answer)). - **Sostituzioni.** Invia solo le risposte che sostituisci; le altre mantengono la loro revisione. Telserv accettava un nuovo file per una condizione mentre il numero era in attesa di verifica, e il file azzerava la revisione di quella condizione; Bird sostituisce una risposta rifiutata, scaduta o non ancora fornita, e rifiuta una risposta ancora in revisione o già accettata, tranne una risposta contrassegnata con `editable_for_verifier_repair` mentre è aperta una correzione richiesta da noi ([Correggi una risposta rifiutata](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer)). - **Avanzamento.** `ownership.status` e `ownership.next` indicano a che punto è il numero. Ogni risposta ha il proprio `state`, e una risposta rifiutata riporta il `reason` del revisore. Bird invia inoltre ogni esito via email ai proprietari della tua organizzazione e alla persona che ha inviato o corretto l'invio per ultima. `ownership` è di solito `null` quando il numero non richiede documentazione. [Invia la documentazione di titolarità](#inviare-la-documentazione-di-titolarità) mostra le richieste, e [Inviare la documentazione di titolarità di un numero](/docs/guides/numbers/ownership-paperwork) descrive l'intero flusso, incluso l'invio dalla dashboard e insieme all'ordine. ### Prodotti e dati anagrafici | Operazione | Telserv | Bird | | -------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Sfogliare i prodotti | `GET /products`, `GET /products/{productId}` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers), che richiede `country_code` e restituisce i numeri in vendita in quel solo paese. Bird non ha un catalogo globale dei prodotti, e nulla corrisponde a `productId`. Nessuna API elenca i paesi e i tipi di numero in vendita; la pagina dei [prezzi dei numeri telefonici](/pricing/numbers) elenca i prezzi standard di Bird per paese. | Ogni risultato di ricerca descrive il proprio prodotto con `number_type`, `capabilities` e `ownership_registration_required`, e riporta il prezzo per la tua organizzazione al posto di `pricing.staticPricing` del prodotto (`nrc` e `mrc`). I prezzi standard di Bird sono nella pagina [prezzi dei numeri telefonici](/pricing/numbers). Il `sessionPricing` al minuto di Telserv non ha un equivalente in queste letture; le tariffe voce sono nella pagina [prezzi voce](/pricing/voice). I tipi di numero Telserv corrispondono a `number_type` di Bird in questo modo: | `numberType` Telserv | Bird `number_type` | | -------------------- | ------------------------------------------ | | `DID` | `local` o `national`, a seconda del numero | | `FreePhone` | `toll_free` | | `Mobile` | `mobile` | ## Cosa funziona diversamente Queste operazioni Telserv funzionano diversamente in Bird. Pianificale prima di spostare un'integrazione che dipende da una di esse. - **Documentazione.** Invia i documenti e i dati dell'utente finale di un numero in un'unica submission, senza bozze, e correggi le risposte rifiutate con il resupply. - **Prenotazioni.** Ordina il numero quando lo hai scelto; l'ordine lo riserva. - **Impostazioni di chiamata per numero.** Applica un codec forzato, un limite di chiamate simultanee, il tempo di squillo e le fasce orarie sulla tua apparecchiatura SIP. - **Una data di rilascio.** Bird rilascia un numero alla fine del periodo pagato o immediatamente, non in una data a tua scelta. Conserva le date di cancellazione che hai inviato a Telserv dalla tua parte e agisci su ciascuna quando arriva a scadenza. - **Saldo del wallet.** Controlla il saldo e ricarica nella dashboard. ## Cerca e acquista un numero con il tuo riferimento Cerca in un solo paese. Combina `number_type`, `capabilities` e `prefix` per restringere i risultati: ```bash curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Ogni risultato riporta un oggetto `pricing` con il prezzo che la tua organizzazione paga per il numero, al netto delle imposte e nella tua valuta di fatturazione, con eventuali prezzi concordati con Bird applicati: - `setup_price` viene addebitato una sola volta quando ordini il numero. Un costo pubblicato pari a zero ha un `amount` di `"0"`. Il campo stesso è `null` quando non si applica alcun costo di attivazione, e anche ogni volta che `recurring_price` è `null`, perché quel numero non può essere ordinato. - `recurring_price` è la tariffa per `recurring_period`. - `intervals_per_charge` indica quanti `recurring_period` copre un singolo addebito. L'addebito ricorrente al netto delle imposte è `recurring_price` moltiplicato per `intervals_per_charge`, prelevato quando il numero viene assegnato al tuo spazio di lavoro e a ogni rinnovo; il costo di attivazione è separato. Per un ordine in attesa di un operatore, l'assegnazione avviene quando l'ordine è completato. Il [riferimento API](/docs/api/reference/list-available-numbers) mostra un esempio di risultato. Un risultato con `pricing.recurring_price: null` non fornisce un prezzo ricorrente. [Contatta il team commerciale](/contact-sales) per ottenere un prezzo per quel paese e tipo di numero prima di effettuare l'ordine. La dashboard e API usano lo stesso prezzo dell'organizzazione, inclusa la conversione nella tua valuta di fatturazione. La lettura di un prezzo non blocca un preventivo: variazioni di tariffe o tassi di cambio prima di un addebito successivo possono modificarne l'importo. Se la ricerca del prezzo fallisce, la ricerca restituisce `503` con [`E14009`](/docs/api/errors/E14009). Riprova la lettura con backoff esponenziale; un errore nella ricerca del prezzo non significa mai che il numero non costa nulla. Per confermare un candidato e il suo prezzo prima di ordinarlo, leggilo con `GET /v1/numbers/available/{number}`. Un `404` significa che non è più in vendita. Ordina il numero con il riferimento che usavi in Telserv e scegli una chiave di idempotenza da conservare per ogni nuovo tentativo di questo acquisto: ```bash curl --request POST "$BIRD_API_URL/v1/numbers/orders" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: order-CUST-778812" \ --data '{"number": "+31612345678", "reference": "CUST-778812"}' ``` Una risposta `201` contiene `status: completed` e un `number_id`, l'identificatore `nda_` del numero. Conservalo come `NUMBER_ID`. Una risposta `202` significa che l'ordine è in attesa di un operatore: [interroga l'ordine](/docs/guides/numbers/buying-numbers#poll-an-order-that-did-not-finish) finché il suo `status` non è `completed` o `failed`. Un costo di attivazione già addebitato non viene rimborsato se l'ordine poi fallisce. Il riferimento viene impostato sul numero quando l'ordine è completato. Può contenere fino a 100 caratteri e non deve essere univoco. Un nuovo tentativo di ordine per un numero già assegnato al tuo spazio di lavoro restituisce l'ordine esistente, quindi riprovare non comporta un doppio addebito. [Acquistare e rilasciare un numero](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) spiega i rifiuti. Per impostare o modificare un riferimento in seguito, invia `reference` (e opzionalmente `name`) a `PATCH /v1/numbers/{number_id}`. Invia `null` per svuotare un campo. ## Verificare che un numero possa gestire le chiamate Un numero il cui `status` è `pending_ownership_registration` è assegnato e fatturato, ma non invia SMS e rifiuta le chiamate vocali in entrata e in uscita finché la documentazione di titolarità non viene approvata. Prima di instradare un numero o effettuare una chiamata di test verso di esso, leggilo con [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) e verifica che `status` sia `active`. Se è in attesa, [invia la documentazione di titolarità](#inviare-la-documentazione-di-titolarità). [Lo stato di un numero assegnato](/docs/guides/numbers/overview#the-status-of-an-allocated-number) spiega ciascun valore. Gli esempi seguenti usano un numero mobile olandese. Controlla il `status` del tuo numero allo stesso modo, qualunque sia il suo paese. ## Inviare la documentazione di titolarità Telserv riceveva la documentazione di un numero con un `POST /numbers/{dnisId}/documents` per ogni documento e un `POST /numbers/{dnisId}/enduserdata` per tutte le etichette. Bird riceve entrambi in un'unica submission, dopo che hai caricato i documenti. 1. Leggi il `country_code` del numero e conservalo come `COUNTRY_CODE`. Il comando lo estrae con `jq`; se non usi `jq`, leggilo manualmente: ```bash COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code) ``` 2. Leggi cosa richiede il paese del numero. Ogni voce in `fields` ha il `key` con cui rispondi, un `data_type` e `required`, che indica se la risposta è obbligatoria. Conserva il `program` indicato dalla risposta come `PROGRAM`: ```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" ``` Un `422` con [`E19001`](/docs/api/errors/E19001) significa che per quel paese non esiste un modulo di titolarità. 3. Carica ogni documento richiesto da un campo `document` come file, al posto di `fileContent` in base64. Conserva il `id` della risposta, l'identificatore `tca_` dell'allegato, come `ATTACHMENT_ID`: ```bash curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --form "file=@registration-certificate.pdf" ``` 4. Invia tutte le risposte insieme: una voce per ogni campo il cui `required` è `true` e per ogni campo opzionale per cui hai una risposta reale, con i dati dell'utente finale come `value` e ogni documento come `attachment_id`. Ometti un campo opzionale invece di inventarne il valore. L'esempio mostra due risposte; aggiungi le altre obbligatorie prima dell'invio. Questa richiesta sottopone le risposte a revisione. Conserva il `id` della risposta, l'identificatore `csb_` della submission, come `SUBMISSION_ID`: ```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-CUST-778812" \ --data '{"subject_kind": "number", "subject_id": "'"$NUMBER_ID"'", "program": "'"$PROGRAM"'", "country_code": "'"$COUNTRY_CODE"'", "answers": [{"key": "business_registration_number", "value": "90012768"}, {"key": "business_registration_certificate", "attachment_id": "'"$ATTACHMENT_ID"'"}]}' ``` Una risposta `201` restituisce la submission. Un `422` non invia nulla: correggi il body e invialo con una nuova chiave di idempotenza, perché la chiave riproduce il rifiuto. [Invia tutte le risposte](/docs/guides/numbers/ownership-paperwork#submit-every-answer) spiega ogni rifiuto. 5. Quando un revisore rifiuta una risposta, sostituisci solo quella, come descritto in [Correggi una risposta rifiutata](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer): ```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-CUST-778812" \ --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}' ``` Per inviare la documentazione durante l'acquisto, invia lo stesso `answers` nel blocco `compliance` di `POST /v1/numbers/orders`. Quell'ordine usa lo scope `numbers` esistente a livello di scrittura, anche quando include la documentazione. Segui la revisione con `ownership.status` su [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number). Le risposte sono una dichiarazione legale resa a nome della tua azienda, quindi invia solo risposte confermate da una persona che ne è responsabile. [Inviare la documentazione di titolarità di un numero](/docs/guides/numbers/ownership-paperwork) descrive ogni richiesta, la revisione e l'invio insieme all'ordine. ## Instradare un numero verso il tuo trunk SIP Un nuovo numero non ha un instradamento proprio, quindi segue l'[instradamento predefinito](/docs/guides/voice/receiving-calls#set-a-default-route) del tuo spazio di lavoro. Quell'instradamento parte come `reject`, ma uno spazio di lavoro che ne ha già impostato uno risponde alle chiamate del nuovo numero secondo quell'instradamento non appena il numero viene allocato. Per consegnare le sue chiamate alla tua apparecchiatura, crea un trunk SIP con le chiamate in entrata attive, assegnagli un gateway e punta il numero verso il trunk. [Trunk SIP](/docs/guides/voice/sip-trunks) spiega come collegare la tua apparecchiatura al trunk. 1. Crea il trunk con le chiamate in entrata attive. Conserva `id` dalla risposta, l'identificatore `spt_` del trunk, come `TRUNK_ID`: ```bash curl --request POST "$BIRD_API_URL/v1/voice/trunks" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: trunk-production-pbx" \ --data '{"name": "Production PBX", "inbound_enabled": true}' ``` 2. Aggiungi un gateway. Per impostazione predefinita il gateway riceve i numeri chiamato e chiamante in E.164 con il relativo `+`. Se la tua apparecchiatura si aspetta numeri senza `+`, come faceva il segnaposto `{dnis}` di Telserv, imposta `destination_format` per il numero chiamato e `origination_format` per il numero chiamante a `{number}`: ```bash curl --request POST "$BIRD_API_URL/v1/voice/trunks/$TRUNK_ID/gateways" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: gateway-pbx-primary" \ --data '{"sip_uri": "sip:pbx.example.com:5060", "priority": 0, "destination_format": "{number}", "origination_format": "{number}"}' ``` Per il failover, aggiungi un secondo gateway; [Cosa serve a un gateway](/docs/guides/voice/receiving-calls#what-a-gateway-needs) spiega `priority` e i formati dei numeri. Creare di nuovo lo stesso gateway senza una chiave di idempotenza restituisce `409` con [`E21047`](/docs/api/errors/E21047). 3. Trova il record vocale del numero. Cerca con le cifre del numero e prendi `id` della voce il cui `provider.number_id` corrisponde al `id` dell'allocazione. Conservalo come `VOICE_NUMBER_ID`: ```bash curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` 4. Indirizza il numero al trunk: ```bash curl --request PATCH "$BIRD_API_URL/v1/voice/numbers/$VOICE_NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --data '{"inbound_configuration": {"route": {"type": "trunk", "trunk_id": "'"$TRUNK_ID"'"}}}' ``` Una risposta `200` mostra il nuovo instradamento. Un trunk con le chiamate in entrata disattivate risponde `412` con [`E21052`](/docs/api/errors/E21052). Disattivare le chiamate in entrata su un trunk, o eliminare il trunk, riporta ogni numero instradato su di esso all'instradamento predefinito del tuo spazio di lavoro, e riattivare le chiamate in entrata non ripristina quegli instradamenti. [Consegnare le chiamate a un trunk SIP](/docs/guides/voice/receiving-calls#deliver-calls-to-a-sip-trunk) spiega questo e gli instradamenti `trunk`, `forward` e `reject`. ## Riconciliare i tuoi numeri Scorri la lista con la dimensione di pagina massima. Passa `next_cursor` di ogni pagina come `NEXT_CURSOR` per leggere la pagina successiva, finché `next_cursor` non è `null`. La lista non restituisce un conteggio totale. ```bash curl "$BIRD_API_URL/v1/numbers?limit=100" \ --header "Authorization: Bearer $BIRD_API_KEY" curl "$BIRD_API_URL/v1/numbers?limit=100&starting_after=$NEXT_CURSOR" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` I filtri della lista di Telserv corrispondono a quelli di Bird in questo modo: | Filtro Telserv su `GET /numbers` | Filtro Bird su `GET /v1/numbers` | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number`, che corrisponde all'inizio del numero | `prefix` senza `country_code`, che corrisponde alle cifre dall'inizio del numero completo | | `prefix`, che corrisponde al prefisso di accesso e di area come `3170` | `country_code` con `prefix` impostato sulle cifre nazionali: `country_code=NL&prefix=70` | | `reference` con un valore parziale | `search`, che corrisponde a parte del numero, del nome o del riferimento, senza distinzione tra maiuscole e minuscole | | `reference` con un valore esatto tra virgolette | `reference`, che restituisce i numeri con quel riferimento esatto. La corrispondenza distingue tra maiuscole e minuscole | | Novità in Bird | `number` restituisce un numero intero fornito con il suo prefisso internazionale, con o senza `+` o `00`: `+31612345678`, `31612345678` e `0031612345678` trovano lo stesso numero | [Trova un numero nella tua lista](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) descrive ogni filtro in dettaglio. Ogni voce riporta `pricing`, con `recurring_price` per `recurring_period` e `intervals_per_charge`. Se il prezzo non è fisso per il numero, `recurring_price` è la tariffa corrente della tua organizzazione, e ogni rinnovo addebita la tariffa in vigore al momento del rinnovo, quindi un addebito già fatturato può differire. [Elenca tutti i numeri che possiedi](/docs/guides/numbers/managing-numbers#list-every-number-you-hold) spiega in quale valuta viene addebitato ogni numero, quando `pricing` o i suoi prezzi sono `null` e cosa fare quando `pricing.error` è impostato. Un numero rilasciato esce da questa lista, e leggerlo tramite `number_id` restituisce `404`. Se lo hai ordinato in Bird, il suo ordine completato resta in [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders). ## Rilasciare un numero Entrambe le richieste si applicano a un numero dedicato, tramite il suo identificatore `nda_`; un numero condiviso viene rifiutato con [`E14002`](/docs/api/errors/E14002). Per mantenere il numero fino alla fine del periodo già pagato, cancellalo: ```bash curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Idempotency-Key: cancel-CUST-778812" ``` Una risposta `202` restituisce il numero con `releases_at`, la fine del periodo pagato. Il numero mantiene il suo stato attuale fino a quel momento, l'abbonamento non si rinnova e il numero viene rilasciato a quella scadenza. Ripetere la richiesta restituisce lo stesso `releases_at`, e una cancellazione non può essere annullata. Un numero senza abbonamento viene rilasciato immediatamente, e la risposta è `200` con il `status` del numero impostato su `released`. Per rilasciare il numero subito, anche se è già programmato per la cancellazione: ```bash curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Idempotency-Key: release-CUST-778812" ``` Una risposta `204` significa che il numero è rilasciato, con effetto immediato. Il resto del periodo in corso non viene rimborsato. Finché un pagamento di rinnovo per il numero è in arretrato, entrambe le richieste rispondono `409` con [`E03015`](/docs/api/errors/E03015) fino al saldo. Nessuna delle due richieste accetta una data, quindi mantieni la pianificazione che hai inviato a Telserv come `requestedCancelDate` dal tuo lato. Per mantenere un numero fino alla sua data, cancellalo quando la data rientra nel periodo di fatturazione corrente: viene rilasciato alla fine di quel periodo, alla data o dopo. Per cederlo esattamente alla data, rilascialo quel giorno. [Rilasciare un numero](/docs/guides/numbers/managing-numbers#release-a-number) spiega cosa fa ciascuna richiesta al numero, ai suoi addebiti e a un nuovo tentativo. ## Effettuare una chiamata di test al tuo numero Per verificare un instradamento da un capo all'altro, effettua una chiamata al numero da un altro numero che il tuo spazio di lavoro può presentare come caller ID. Il paese del numero deve essere abilitato nelle tue [destinazioni vocali](/docs/guides/voice/destinations), altrimenti la chiamata non viene completata. La richiesta qui sotto esegue una sequenza inline che riaggancia quando la chiamata riceve risposta, quindi non serve una sequenza salvata. Effettua una chiamata reale e si applicano le normali tariffe di chiamata. Salva la richiesta come `test-call.json`. Inserisci il caller ID che presenti in `from`, un [numero verificato](/docs/guides/voice/caller-ids) o di proprietà del tuo spazio di lavoro, e il numero sotto test in `to`: ```json { "from": "+31612345679", "to": "+31612345678", "sequence": { "definition": { "schema_version": 1, "expression_environment": "bird.cel.v1", "nodes": [ { "id": "entry", "type": "trigger.start_call", "type_version": 1, "config": {}, "input": {}, "connections": { "event": { "node_id": "end", "port": "input" } } }, { "id": "end", "type": "voice.hangup", "type_version": 1, "config": {}, "input": {} } ] }, "entry_node_id": "entry", "trigger_data": {} } } ``` Inviala: ```bash curl --request POST "$BIRD_API_URL/v1/voice/calls" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: ${TEST_CALL_KEY:?Set TEST_CALL_KEY once for this test call}" \ --data-binary @test-call.json ``` Imposta `TEST_CALL_KEY` su un valore nuovo per ogni test e riutilizzalo quando riprovi lo stesso test dopo un timeout o un risultato incerto: la stessa chiave e la stessa richiesta entro tre ore riproducono la prima accettazione invece di effettuare una seconda chiamata. Una risposta `202` accetta la chiamata e restituisce il suo `initial_leg_id`. L'accettazione non dimostra che la chiamata sia stata connessa: leggi il leg con [`GET /v1/voice/legs/{leg_id}`](/docs/api/reference/get-voice-leg), oppure elenca i leg effettuati verso il numero con [`GET /v1/voice/legs`](/docs/api/reference/list-voice-legs) e il suo filtro `to`, e verifica che la tua apparecchiatura abbia ricevuto la chiamata. [Creare una chiamata vocale](/docs/guides/voice/create-calls) illustra i requisiti di caller ID e destinazione e le regole per riprovare. ## Passi successivi - [Acquistare e rilasciare un numero](/docs/guides/numbers/buying-numbers) - [Gestire i tuoi numeri di telefono](/docs/guides/numbers/managing-numbers) - [Inviare la documentazione di titolarità di un numero](/docs/guides/numbers/ownership-paperwork) - [Ricevere chiamate](/docs/guides/voice/receiving-calls) - [Trunk SIP](/docs/guides/voice/sip-trunks) - [Idempotenza](/docs/guides/idempotency) ## 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)