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 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 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. 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=<digits> 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 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

L'Bird API rifiuta un parametro di query che non riconosce con 422 e 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. 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. 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 mostra la richiesta, e Gestire i tuoi numeri di telefono 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

• 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 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

• 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. Riconcilia 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 mostra entrambe le richieste.

Destinazioni e profili

• 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; un numero non verificato risponde 412 con 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

• 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 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).
• 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).
• 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à mostra le richieste, e Inviare la documentazione di titolarità di un numero descrive l'intero flusso, incluso l'invio dalla dashboard e insieme all'ordine.

Prodotti e dati anagrafici

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. Il sessionPricing al minuto di Telserv non ha un equivalente in queste letture; le tariffe voce sono nella pagina prezzi voce.

I tipi di numero Telserv corrispondono a number_type di Bird in questo modo:

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:

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 mostra un esempio di risultato. Un risultato con pricing.recurring_price: null non fornisce un prezzo ricorrente. Contatta il team commerciale 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. 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:

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 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 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} e verifica che status sia active. Se è in attesa, invia la documentazione di titolarità. Lo stato di un numero assegnato 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:

   Esempio di codice

   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:

   Esempio di codice

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

   Esempio di codice

   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:

   Esempio di codice

   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 spiega ogni rifiuto.

5. Quando un revisore rifiuta una risposta, sostituisci solo quella, come descritto in Correggi una risposta rifiutata:

   Esempio di codice

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

   Esempio di codice

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

   Esempio di codice

   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 spiega priority e i formati dei numeri. Creare di nuovo lo stesso gateway senza una chiave di idempotenza restituisce 409 con 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:

   Esempio di codice

   curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \
     --header "Authorization: Bearer $BIRD_API_KEY"

4. Indirizza il numero al trunk:

   Esempio di codice

   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.

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

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:

Trova un numero nella tua lista 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 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.

Rilasciare un numero

Entrambe le richieste si applicano a un numero dedicato, tramite il suo identificatore nda_; un numero condiviso viene rifiutato con E14002. Per mantenere il numero fino alla fine del periodo già pagato, cancellalo:

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:

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 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 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, 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 o di proprietà del tuo spazio di lavoro, e il numero sotto test in to:

{
  "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:

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}, oppure elenca i leg effettuati verso il numero con GET /v1/voice/legs e il suo filtro to, e verifica che la tua apparecchiatura abbia ricevuto la chiamata. Creare una chiamata vocale illustra i requisiti di caller ID e destinazione e le regole per riprovare.

Passi successivi

• Acquistare e rilasciare un numero
• Gestire i tuoi numeri di telefono
• Inviare la documentazione di titolarità di un numero
• Ricevere chiamate
• Trunk SIP
• Idempotenza