Migrer de Telserv vers Bird

Ce guide s'adresse aux intégrations qui appellent l'API partenaire Telserv, V1 ou V2, pour acheter, router et libérer des numéros, et qui migrent maintenant vers Bird API.

Bird API dessert chaque produit Bird, donc ses opérations sur les numéros et la voix suivent les conventions propres à Bird au lieu de celles de Telserv. La plupart des fonctionnalités utilisées par votre intégration ont un appel Bird correspondant. Les endpoints, les payloads, les identifiants et l'authentification diffèrent : prévoyez de réécrire l'intégration. Lorsque Bird fait une tâche différemment, ce guide montre comment.

Ce guide est un travail en cours. Il couvre ce que fait Bird et s'enrichit au fil de la migration. Si une opération Telserv que vous utilisez n'est pas répertoriée ici, elle nécessite encore un cadrage et du travail avant de pouvoir être ajoutée ; contactez votre référent migration à ce sujet.

Avant de commencer

• Une organisation Bird dont la vérification d'identité est terminée, condition requise pour le premier achat de numéro.
• Une clé API avec les scopes utilisés par les recettes : numbers en écriture pour les numéros et les commandes, compliance en écriture pour les opérations autonomes sur les documents de propriété, et voice_management en écriture pour les trunks SIP, les numéros voix et les numéros vérifiés. L'appel de test nécessite aussi voice:write, et la lecture des segments d'appel nécessite voice:read.
• Solde du portefeuille. Les commandes sont payées depuis le portefeuille. Quand une commande est refusée explique les refus 402 et 412.

Les numéros que votre intégration gère dans Telserv n'ont pas besoin d'être rachetés. Une fois vos numéros déplacés vers votre espace de travail Bird, ils apparaissent dans GET /v1/numbers. Votre référent migration confirme quand cela se produit. Pour obtenir l'identifiant nda_ d'un numéro migré, recherchez-le avec GET /v1/numbers?number=<digits> en indiquant les chiffres avec leur indicatif pays, et conservez le id comme NUMBER_ID.

Les exemples lisent votre clé depuis BIRD_API_KEY et son hôte régional depuis BIRD_API_URL : https://eu1.platform.bird.com pour une clé bk_eu1_, ou https://us1.platform.bird.com pour une clé bk_us1_. Les autres variables, comme TRUNK_ID et NUMBER_ID, contiennent un identifiant issu d'une réponse précédente ; chaque étape nomme celui qu'elle définit.

Ce qui change dans le contrat

L'Bird API refuse un paramètre de requête qu'elle ne reconnaît pas avec 422 et E01029. Supprimez de vos requêtes les filtres propres à Telserv, comme city, au lieu de les transmettre tels quels.

Deux identifiants pour un même numéro

Un numéro compatible voix attribué à votre espace de travail possède deux enregistrements, chacun avec son propre identifiant :

• L'allocation, renvoyée par GET /v1/numbers. Son id commence par nda_ pour un numéro dédié et par nal_ pour un numéro partagé, et le number_id d'une commande est l'identifiant nda_ du numéro acheté. Utilisez-la pour lire, nommer et référencer le numéro, et pour libérer un numéro dédié.
• L'enregistrement vocal, vnu_, renvoyé par GET /v1/voice/numbers. Utilisez-le pour lire et modifier la destination des appels entrants du numéro. Un numéro sans capacité vocale, par exemple un numéro SMS uniquement, n'a pas d'enregistrement vocal.

Les opérations vocales refusent un identifiant nda_ ou nal_ avec 422. Pour trouver l'enregistrement vocal d'un numéro, listez les numéros vocaux avec search défini sur les chiffres du numéro et prenez l'entrée dont le provider.number_id correspond au id de l'allocation. Acheminer un numéro vers votre trunk SIP montre la requête, et Gérer vos numéros de téléphone couvre la recherche.

Le GET /numbers/{dnisId} de Telserv devient deux lectures dans Bird : l'allocation pour le statut et les documents de propriété, et l'enregistrement vocal pour la route.

Correspondance des opérations Telserv avec Bird

Chaque tableau liste une tâche, l'appel Telserv qui l'effectuait et l'appel Bird qui l'effectue maintenant. Les notes sous chaque tableau indiquent ce qui change dans la requête ou la réponse.

Boutique

• Recherche. country_code est obligatoire, donc une recherche couvre un seul pays. prefix prend les chiffres nationaux après l'indicatif pays : Telserv prefix=3170 devient country_code=NL&prefix=70. Affinez par indicatif régional avec prefix à la place de city, et par number_type et capabilities à la place de productId.
• Documents dans les résultats de recherche. Chaque résultat contient ownership_registration_required à la place du filtre excludeNumbersRequireVerification. Une valeur true signifie que le numéro est facturé dès l'achat, mais qu'il n'envoie aucun SMS et n'achemine aucun appel vocal entrant ou sortant tant que ses documents ne sont pas approuvés.
• Vérifier un numéro. Il est adressé par son numéro E.164.
• Prix. Telserv renvoyait pricing.staticPricing dans les lectures détaillées d'un numéro et d'un produit. Dans Bird, chaque résultat de recherche contient son prix pour votre organisation dans pricing : setup_price à la place de nrc, et recurring_price par recurring_period à la place de mrc, avec intervals_per_charge pour le nombre de périodes couvertes par une facturation. Rechercher et acheter un numéro avec votre référence décrit les champs de prix.
• Achat. Envoyez number et un reference facultatif. La commande est payée depuis votre portefeuille. La plupart des commandes répondent 201 ; une commande en attente chez un opérateur répond 202, et vous interrogez son état.
• Réservation. Commander le numéro le réserve. Vérifiez d'abord un candidat, puis commandez-le.

Numéros

• Liste. La liste contient les numéros qui vous sont actuellement attribués. Un numéro libéré que vous avez commandé dans Bird reste visible via sa commande dans GET /v1/numbers/orders. Réconcilier vos numéros décrit la correspondance des filtres.
• Lecture. Le statut, les documents de propriété et le prix se trouvent sur l'allocation, et la route sur l'enregistrement vocal. L'objet pricing de l'allocation, avec recurring_price par recurring_period et intervals_per_charge, remplace pricing.staticPricing.mrc, et la liste le porte aussi, contrairement au GET /numbers de Telserv.
• Modification. name et reference se trouvent sur l'allocation, et la route sur l'enregistrement vocal. Définissez un codec forcé et un plafond d'appels simultanés sur votre équipement SIP. destinationDistributionType devient le priority de la passerelle sur le trunk SIP : FailOver attribue à chaque passerelle un priority différent, et RoundRobin leur attribue le même.
• Libération. DELETE conserve le numéro jusqu'à la fin de la période déjà payée, puis le libère. POST …/release le libère immédiatement. Aucune des deux options n'accepte de date. Libérer un numéro montre les deux requêtes.

Destinations et profils

• Équipement SIP. Une passerelle appartient au trunk et dessert chaque numéro routé vers elle, de sorte que les numéros nécessitant des listes de destinations différentes ont besoin de trunks différents. sortOrder devient priority. Appliquez la durée de sonnerie et les plages horaires sur votre équipement SIP.
• Renvoi. Définissez forward_to et forward_as. forward_to doit être l'un de vos numéros vérifiés ; un numéro non vérifié répond 412 avec E21053. forward_as détermine quel numéro l'appel renvoyé affiche comme appelant. Un numéro n'a qu'une seule route à la fois : pour basculer d'un équipement SIP vers un numéro de téléphone, renvoyez l'appel depuis votre équipement SIP.
• Cesser de recevoir des appels. Le numéro rejette les appels jusqu'à ce que vous le routiez à nouveau. Pour conserver un réglage par défaut permanent à la place d'un profil par défaut, routez le numéro vers un trunk qui contient vos passerelles par défaut.
• Profils. distributionType devient priority : FailOver attribue à chaque passerelle un priority différent, et RoundRobin leur attribue le même. La distribution est définie par trunk, donc les numéros nécessitant une distribution différente ont besoin de trunks différents. L'espace réservé {dnis} devient {number} dans destination_format, et un prefixCLIP devient le texte avant {number} dans origination_format.
• Appliquer un profil. Un trunk est adressé par son identifiant spt_, alors que Telserv adressait un profil par son nom.

Documents et données d'utilisateur final

• Exigences. Le catalogue de conditions de Telserv couvrait tous les produits à la fois ; Bird lit un formulaire à la fois. Demandez les exigences d'un numéro avec subject_kind=number, son identifiant nda_ comme subject_id et son country_code, ou lisez un formulaire avant l'achat avec program défini sur le type de numéro et sans subject_id. Chaque entrée de fields remplace une condition ou un libellé d'utilisateur final Telserv : son key est la clé sous laquelle vous répondez, et data_type document signale une entrée qui attend un fichier.
• Documents. Téléversez le fichier sous forme de multipart/form-data au lieu d'un fileContent en base64 ; Téléverser chaque document liste les fichiers acceptés. Téléverser deux fois le même fichier renvoie la même pièce jointe. Un téléversement seul ne dépose rien : c'est la soumission qui cite son attachment_id qui le dépose.
• Données d'utilisateur final et documents ensemble. Telserv recevait chaque document dans un appel distinct, et les données d'utilisateur final sous forme d'une liste de libellés dans un autre. Bird reçoit toutes les réponses, saisies et documents, en une seule soumission, sans brouillon : la requête dépose les réponses pour examen. Suivez ensuite ownership.next, qui indique un complément pour les corrections, et une nouvelle soumission seulement lorsqu'elle est nécessaire (Soumettre toutes les réponses).
• Remplacements. Envoyez uniquement les réponses que vous remplacez ; les autres conservent leur examen. Telserv acceptait un nouveau fichier pour une condition tant que le numéro était en attente de vérification, et ce fichier relançait l'examen de cette condition. Bird remplace une réponse rejetée, expirée ou pas encore fournie, et refuse une réponse encore en cours d'examen ou déjà acceptée, sauf une réponse marquée editable_for_verifier_repair pendant qu'une correction que nous avons demandée est ouverte (Corriger une réponse rejetée).
• Avancement. ownership.status et ownership.next indiquent où en est le numéro. Chaque réponse a son propre state, et une réponse rejetée porte le reason de l'examinateur. Bird envoie aussi chaque résultat par e-mail aux propriétaires de votre organisation et à la personne qui a déposé ou corrigé la soumission en dernier. ownership vaut généralement null lorsque le numéro ne nécessite aucun document.

Déposer les documents de propriété montre les requêtes, et Déposer les documents de propriété d'un numéro couvre l'ensemble du processus, y compris le dépôt depuis le tableau de bord et avec la commande.

Produits et données de référence

Chaque résultat de recherche décrit son produit avec number_type, capabilities et ownership_registration_required, et porte le prix pour votre organisation à la place du pricing.staticPricing du produit (nrc et mrc). Les prix standard de Bird figurent sur la page tarification des numéros de téléphone. Le sessionPricing à la minute de Telserv n'a pas d'équivalent dans ces lectures ; les tarifs voix figurent sur la page tarification voix.

Les types de numéros Telserv correspondent au number_type de Bird comme suit :

Ce qui fonctionne différemment

Ces tâches Telserv fonctionnent différemment dans Bird. Prévoyez-les avant de migrer une intégration qui dépend de l'une d'elles.

• Documents. Déposez les documents et les données d'utilisateur final d'un numéro en une seule soumission, sans brouillon, et corrigez les réponses rejetées par un nouvel envoi.
• Réservations. Commandez le numéro une fois votre choix fait ; la commande le réserve.
• Paramètres d'appel par numéro. Appliquez un codec forcé, un plafond d'appels simultanés, un temps de sonnerie et des plages horaires sur votre équipement SIP.
• Date de libération. Bird libère un numéro à la fin de sa période payée ou immédiatement, pas à une date de votre choix. Conservez de votre côté les dates d'annulation que vous avez envoyées à Telserv, et agissez sur chacune à son échéance.
• Solde du portefeuille. Vérifiez le solde et rechargez depuis le tableau de bord.

Rechercher et acheter un numéro avec votre référence

Recherchez dans un seul pays. Combinez number_type, capabilities et prefix pour affiner les résultats :

curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Chaque résultat porte un objet pricing avec le prix que votre organisation paie pour le numéro, hors taxes et dans votre devise de facturation, avec les prix convenus avec Bird appliqués :

• setup_price est facturé une seule fois à la commande du numéro. Des frais publiés de zéro ont un amount de "0". Le champ lui-même vaut null lorsqu'aucuns frais de mise en service ne s'appliquent, et aussi chaque fois que recurring_price vaut null, car ce numéro ne peut pas être commandé.
• recurring_price est le tarif par recurring_period.
• intervals_per_charge est le nombre de recurring_period couverts par une facturation. Le montant récurrent hors taxes est recurring_price multiplié par intervals_per_charge, prélevé lorsque le numéro est attribué à votre espace de travail et à chaque renouvellement ; les frais de mise en service sont séparés. Pour une commande en attente chez un opérateur, l'attribution a lieu lorsque la commande aboutit.

La référence API présente un exemple de résultat. Un résultat avec pricing.recurring_price: null ne fournit pas de tarif récurrent. Contactez l'équipe commerciale pour obtenir un tarif pour ce pays et ce type de numéro avant de commander.

Le tableau de bord et API utilisent le même prix organisation, y compris la conversion dans votre devise de facturation. Une lecture de prix ne verrouille pas un devis : des changements de tarif ou de taux de change avant une facturation ultérieure peuvent en modifier le montant. Si la recherche de prix échoue, la recherche renvoie 503 avec E14009. Réessayez la lecture avec un backoff exponentiel ; un échec de recherche de prix ne signifie jamais que le numéro ne coûte rien.

Pour confirmer un candidat et son prix avant de le commander, lisez-le avec GET /v1/numbers/available/{number}. Un 404 signifie qu'il n'est plus en vente.

Commandez le numéro avec la référence que vous utilisiez dans Telserv, et choisissez une clé d'idempotence que vous conservez pour toute nouvelle tentative de cet achat :

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"}'

Une réponse 201 contient status: completed et un number_id, l'identifiant nda_ du numéro. Conservez-le dans NUMBER_ID. Une réponse 202 signifie que la commande attend un opérateur : interrogez la commande jusqu'à ce que son status soit completed ou failed. Des frais de mise en service déjà facturés ne sont pas remboursés si la commande échoue ensuite. La référence est inscrite sur le numéro lorsque la commande aboutit. Elle peut contenir jusqu'à 100 caractères et n'a pas besoin d'être unique.

Réessayer une commande pour un numéro déjà alloué à votre espace de travail renvoie la commande existante ; une nouvelle tentative ne facture donc pas deux fois. Acheter et libérer un numéro explique les refus.

Pour définir ou modifier une référence ultérieurement, envoyez reference (et éventuellement name) à PATCH /v1/numbers/{number_id}. Envoyez null pour effacer un champ.

Vérifier qu'un numéro peut acheminer des appels

Un numéro dont le status est pending_ownership_registration est alloué et facturé, mais il n'envoie aucun SMS et refuse les appels vocaux entrants et sortants tant que ses documents de propriété ne sont pas approuvés. Avant de router un numéro ou de passer un appel de test vers celui-ci, lisez-le avec GET /v1/numbers/{number_id} et vérifiez que status est active. S'il est en attente, déposez les documents de propriété. Le statut d'un numéro alloué explique chaque valeur.

Les exemples ci-dessous utilisent un numéro mobile néerlandais. Vérifiez le status de votre propre numéro de la même façon, quel que soit son pays.

Déposer les documents de propriété

Telserv recevait les documents d'un numéro avec un POST /numbers/{dnisId}/documents par document et un POST /numbers/{dnisId}/enduserdata pour l'ensemble des libellés. Bird reçoit les deux en une seule soumission, après le téléversement des documents.

1. Lisez le country_code du numéro et conservez-le dans COUNTRY_CODE. La commande l'extrait avec jq ; lisez-le manuellement si vous n'utilisez pas jq :

   Exemple de code

   COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

2. Lisez ce que demande le pays du numéro. Chaque entrée de fields contient le key sous lequel vous répondez, un data_type et required, qui indique si la réponse est obligatoire. Conservez le program indiqué dans la réponse dans PROGRAM :

   Exemple de code

   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 avec E19001 signifie qu'il n'existe aucun formulaire de propriété pour ce pays.

3. Téléversez chaque document demandé par un champ document, sous forme de fichier au lieu de fileContent en base64. Conservez le id de la réponse, l'identifiant tca_ de la pièce jointe, dans ATTACHMENT_ID :

   Exemple de code

   curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --form "file=@registration-certificate.pdf"

4. Soumettez toutes les réponses en une fois : une entrée pour chaque champ dont le required est true, et pour chaque champ facultatif auquel vous avez une vraie réponse, avec les données d'utilisateur final en value et chaque document en attachment_id. Omettez un champ facultatif plutôt que d'inventer une valeur. L'exemple montre deux réponses ; ajoutez les autres réponses obligatoires avant l'envoi. Cette requête dépose les réponses pour examen. Conservez le id de la réponse, l'identifiant csb_ de la soumission, dans SUBMISSION_ID :

   Exemple de code

   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"'"}]}'

   Une réponse 201 renvoie la soumission. Un 422 ne dépose rien : corrigez le corps et renvoyez-le avec une nouvelle clé d'idempotence, car la clé rejoue le refus. Soumettre toutes les réponses explique chaque refus.

5. Lorsqu'un examinateur rejette une réponse, remplacez uniquement cette réponse, comme le décrit Corriger une réponse rejetée :

   Exemple de code

   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"}]}'

Pour déposer les documents lors de l'achat, envoyez le même answers dans le bloc compliance de POST /v1/numbers/orders. Cette commande utilise le scope numbers existant en écriture, y compris lorsqu'elle contient des documents.

Suivez l'examen avec ownership.status sur GET /v1/numbers/{number_id}. Les réponses constituent une déclaration juridique faite au nom de votre entreprise : ne déposez que des réponses confirmées par une personne qui en est responsable. Déposer les documents de propriété d'un numéro couvre chaque requête, l'examen et le dépôt avec la commande.

Acheminer un numéro vers votre trunk SIP

Un nouveau numéro n'a pas de route propre : il suit donc la route par défaut de votre espace de travail. Cette route par défaut vaut d'abord reject, mais dans un espace de travail qui en a déjà défini une, le nouveau numéro répond aux appels selon celle-ci dès qu'il est alloué. Pour livrer ses appels à votre équipement, créez un trunk SIP avec les appels entrants activés, ajoutez-lui une passerelle, puis pointez le numéro vers le trunk. Trunks SIP explique comment connecter votre équipement au trunk.

1. Créez le trunk avec les appels entrants activés. Conservez le id de la réponse, l'identifiant spt_ du trunk, dans TRUNK_ID :

   Exemple de code

   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. Ajoutez une passerelle. Par défaut, la passerelle reçoit les numéros composés et appelants en E.164 avec leur +. Si votre équipement attend les numéros sans le +, comme le faisait le placeholder {dnis} de Telserv, définissez destination_format pour le numéro composé et origination_format pour le numéro appelant sur {number} :

   Exemple de code

   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}"}'

   Pour le basculement, ajoutez une seconde passerelle ; Ce dont une passerelle a besoin explique priority et les formats de numéro. Créer la même passerelle une seconde fois sans clé d'idempotence renvoie 409 avec E21047.

3. Trouvez l'enregistrement vocal du numéro. Recherchez avec les chiffres du numéro et prenez le id de l'entrée dont le provider.number_id est le id de l'allocation. Conservez-le dans VOICE_NUMBER_ID :

   Exemple de code

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

4. Pointez le numéro vers le trunk :

   Exemple de code

   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"'"}}}'

   Une réponse 200 affiche la nouvelle route. Un trunk avec les appels entrants désactivés renvoie 412 avec E21052.

Désactiver les appels entrants sur un trunk, ou supprimer le trunk, renvoie chaque numéro acheminé vers lui à la route par défaut de votre espace de travail, et les réactiver ne restaure pas ces routes. Livrer les appels à un trunk SIP explique ce comportement ainsi que les routes trunk, forward et reject.

Réconcilier vos numéros

Parcourez la liste avec la taille de page maximale. Transmettez le next_cursor de chaque page comme NEXT_CURSOR pour lire la page suivante, jusqu'à ce que next_cursor soit null. La liste ne renvoie pas de nombre total.

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"

Les filtres de la liste Telserv correspondent à ceux de Bird comme suit :

Trouver un numéro dans votre liste détaille chaque filtre.

Chaque entrée porte pricing, avec recurring_price par recurring_period et intervals_per_charge. Sauf si un prix est fixé pour le numéro, recurring_price est le tarif actuel de votre organisation, et chaque renouvellement facture le tarif en vigueur au moment du renouvellement ; un montant déjà facturé peut donc en différer. Lister tous les numéros que vous détenez explique dans quelle devise chaque numéro est facturé, quand pricing ou ses prix valent null, et que faire lorsque pricing.error est défini.

Un numéro libéré quitte cette liste, et sa lecture par number_id répond 404. Si vous l'avez commandé dans Bird, sa commande terminée reste dans GET /v1/numbers/orders.

Libérer un numéro

Les deux requêtes s'appliquent à un numéro dédié, par son identifiant nda_ ; un numéro partagé est refusé avec E14002. Pour conserver le numéro jusqu'à la fin de la période déjà payée, annulez-le :

curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: cancel-CUST-778812"

Une réponse 202 renvoie le numéro avec releases_at, la fin de sa période payée. Le numéro conserve son statut actuel jusque-là, son abonnement ne se renouvelle pas, et il est libéré à ce moment. Une nouvelle demande renvoie le même releases_at, et une annulation ne peut pas être révoquée. Un numéro sans abonnement sous-jacent est libéré immédiatement, et la réponse est 200 avec le status du numéro défini sur released.

Pour libérer le numéro maintenant, y compris un numéro déjà planifié pour annulation :

curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: release-CUST-778812"

Une réponse 204 signifie que le numéro est libéré, avec effet immédiat. Le reste de la période en cours n'est pas remboursé.

Tant qu'un paiement de renouvellement pour le numéro est en retard, les deux requêtes répondent 409 avec E03015 jusqu'à ce qu'il soit réglé.

Aucune des deux requêtes n'accepte de date : conservez le calendrier que vous avez envoyé à Telserv sous forme de requestedCancelDate de votre côté. Pour conserver un numéro jusqu'à sa date, annulez-le une fois que la date tombe dans sa période de facturation en cours : il est libéré à la fin de cette période, à la date prévue ou après. Pour y renoncer exactement à la date, libérez-le ce jour-là. Libérer un numéro explique ce que chaque requête fait au numéro, à ses frais et à une nouvelle tentative.

Passer un appel de test vers votre numéro

Pour vérifier une route de bout en bout, passez un appel vers le numéro depuis un autre numéro que votre espace de travail peut présenter comme identifiant de l'appelant. Le pays du numéro doit être activé dans vos destinations vocales, sinon l'appel n'aboutit pas. La requête ci-dessous exécute une séquence en ligne qui raccroche dès que l'appel obtient une réponse : aucune séquence enregistrée n'est nécessaire. Elle passe un appel réel, et les frais d'appel normaux s'appliquent.

Enregistrez la requête sous test-call.json. Indiquez l'identifiant de l'appelant que vous présentez dans from, un numéro possédé ou vérifié de votre espace de travail, et le numéro testé dans 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": {}
  }
}

Envoyez-la :

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

Donnez à TEST_CALL_KEY une nouvelle valeur pour chaque test, et réutilisez-la lorsque vous réessayez le même test après un délai d'attente ou un résultat incertain : la même clé et la même requête dans les trois heures rejouent la première acceptation au lieu de passer un second appel. Une réponse 202 accepte l'appel et renvoie son initial_leg_id. L'acceptation ne prouve pas que l'appel a abouti : lisez le segment d'appel avec GET /v1/voice/legs/{leg_id}, ou listez les segments passés vers le numéro avec GET /v1/voice/legs et son filtre to, et vérifiez que votre équipement a reçu l'appel. Créer un appel vocal couvre les exigences d'identifiant d'appelant et de destination ainsi que les règles de nouvelle tentative.

Étapes suivantes

• Acheter et libérer un numéro
• Gérer vos numéros de téléphone
• Déposer les documents de propriété d'un numéro
• Recevoir des appels
• Trunks SIP
• Idempotence