--- title: "Migrer de Telserv vers Bird" description: "Migrez une intégration partenaire Telserv API vers Bird API, associez chaque groupe d'opérations à son appel Bird, et voyez comment chaque tâche est réalisée dans Bird." canonical: "https://bird.com/fr-fr/documentation/guides/numbers/migrate/telserv" --- # 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](/docs/api/authentication) 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](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) 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`](/docs/api/reference/list-workspace-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=` 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](/docs/api/regions) 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 | Domaine | API partenaire Telserv | Bird API | | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Authentification | En-tête `X-ApiKey` (V2) ou paramètre `apiKey` (V1), vérifié par rapport à votre liste d'adresses IP autorisées | `Authorization: Bearer` avec une clé API dont les scopes désignent les domaines produit auxquels elle a accès. Une liste d'adresses IP autorisées est facultative : configurez-la sous **IP restrictions** sur la clé dans [**Clés API**](https://bird.com/dashboard/w/api-keys) | | Identifiants | Entiers. L'achat d'un numéro lui attribue un nouveau `id` | TypeID préfixés tels que `nda_`, `nor_`, `vnu_` et `spt_`. Un numéro conserve son identifiant `nda_` tant qu'il vous est attribué | | Numéros de téléphone | Chiffres sans `+` initial | E.164 avec le `+` initial | | Pagination | Décalages `start` et `limit`, jusqu'à 1000 par page | Curseurs : `limit` jusqu'à 100 (25 par défaut), puis `starting_after` défini sur le `next_cursor` de la page précédente. Voir [Pagination](/docs/api/pagination) | | Erreurs | `errorCode` nomme une classe d'exception, et `403` couvre une ressource manquante et de nombreuses erreurs de validation | `error.code` est un code `E` stable avec une page de documentation et, lorsqu'une résolution est connue, un `remediation`. Une ressource manquante répond `404`, une précondition non remplie `412`, et une entrée invalide `422` avec le détail des champs. Voir [Erreurs](/docs/guides/errors) | | Environnements | LIVE et SANDBOX, chacun avec ses propres clés | Un seul environnement. Chaque commande achète et facture un vrai numéro, et chaque appel de test est un appel réel | | Nouvelles tentatives | Pas de clé d'idempotence | Un en-tête `Idempotency-Key` sur les écritures. La même clé et le même corps rejouent la première réponse avec `Idempotency-Replay: true` ; la même clé avec un corps différent répond `409`. Voir [Idempotence](/docs/guides/idempotency) | L'Bird API refuse un paramètre de requête qu'elle ne reconnaît pas avec `422` et [`E01029`](/docs/api/errors/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`](/docs/api/reference/list-workspace-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`](/docs/api/reference/list-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](#acheminer-un-numéro-vers-votre-trunk-sip) montre la requête, et [Gérer vos numéros de téléphone](/docs/guides/numbers/managing-numbers#find-the-voice-record-that-routes-a-number) 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 | Tâche | Telserv | Bird | | ------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | Rechercher des numéros en vente | `GET /shop` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers) | | Vérifier un numéro | `GET /shop/{stockDnisId}` | [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number) | | Acheter un numéro | `POST /shop/{stockDnisId}` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | | Réserver un numéro | `POST /shop/{stockDnisId}/reserve`, `GET /shop/reserved` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | - **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](#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 | Tâche | Telserv | Bird | | ------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lister vos numéros | `GET /numbers` | [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) | | Lire un numéro | `GET /numbers/{dnisId}` | [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) avec l'id `nda_` ou `nal_` de l'allocation, et [`GET /v1/voice/numbers/{number_id}`](/docs/api/reference/get-voice-number) avec l'id `vnu_` de l'enregistrement vocal | | Modifier un numéro | `PATCH /numbers/{dnisId}` | [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number) avec l'id `nda_` ou `nal_` de l'allocation, et [`PATCH /v1/voice/numbers/{number_id}`](/docs/api/reference/update-voice-number) avec l'id `vnu_` de l'enregistrement vocal | | Libérer un numéro | `DELETE /numbers/{dnisId}?requestedCancelDate=` | [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) à la fin de la période payée, ou [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) immédiatement, tous deux avec l'id `nda_` de l'allocation | - **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`](/docs/api/reference/list-numbers-orders). [Réconcilier vos numéros](#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](#libérer-un-numéro) montre les deux requêtes. ### Destinations et profils | Tâche | Telserv | Bird | | ----------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Envoyer les appels vers un équipement SIP | `POST /numbers/{dnisId}/destinations` | [`POST /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/create-voice-trunk-gateway), puis router `trunk` | | Transférer les appels vers un téléphone | `POST /numbers/{dnisId}/destinations` | Router `forward` | | Cesser de recevoir des appels | `DELETE /numbers/{dnisId}/destinations` | Router `reject` | | Lire les profils de destination | `GET /destinationprofiles`, `GET /destinationprofiles/{id}` | [`GET /v1/voice/trunks`](/docs/api/reference/list-voice-trunks) et [`GET /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/list-voice-trunk-gateways) | | Appliquer un profil à un numéro | `POST /numbers/{dnisId}/destinations/profile` | Router `trunk` avec `trunk_id` | - **É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](/docs/guides/voice/caller-ids) ; un numéro non vérifié répond `412` avec [`E21053`](/docs/api/errors/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 | Tâche | Telserv | Bird | | --------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lire les exigences | `GET /products/conditions`, `GET /masterdata/productconditions` | [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements) pour le numéro, ou avec `program` et sans `subject_id` pour le formulaire qu'un pays exige avant que vous déteniez un numéro | | Téléverser un document | `POST /numbers/{dnisId}/documents` | [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment), puis citez la pièce jointe dans la soumission. Voir [Déposer les documents de propriété](#déposer-les-documents-de-propriété) | | Envoyer les données d'utilisateur final | `POST /numbers/{dnisId}/enduserdata` | [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), avec les documents, en une seule requête. Voir [Déposer les documents de propriété](#déposer-les-documents-de-propriété) | | Remplacer un document | `POST /numbers/{dnisId}/documents` à nouveau | [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission) avec les réponses rejetées ou expirées | | Suivre l'avancement des documents | `GET /numbers/{dnisId}/documents` | `ownership` sur [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number), et la soumission pour le verdict de chaque réponse | - **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](/docs/guides/numbers/ownership-paperwork#upload-each-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](/docs/guides/numbers/ownership-paperwork#submit-every-answer)). - **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](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer)). - **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é](#déposer-les-documents-de-propriété) montre les requêtes, et [Déposer les documents de propriété d'un numéro](/docs/guides/numbers/ownership-paperwork) 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 | Tâche | Telserv | Bird | | ---------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Parcourir les produits | `GET /products`, `GET /products/{productId}` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers), qui exige `country_code` et renvoie les numéros en vente dans ce seul pays. Bird n'a pas de catalogue global de produits, et rien ne correspond à `productId`. Aucune API ne liste les pays et types de numéros en vente ; la page de [tarification des numéros de téléphone](/pricing/numbers) liste les prix standard de Bird par pays. | 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](/pricing/numbers). Le `sessionPricing` à la minute de Telserv n'a pas d'équivalent dans ces lectures ; les tarifs voix figurent sur la page [tarification voix](/pricing/voice). Les types de numéros Telserv correspondent au `number_type` de Bird comme suit : | `numberType` Telserv | Bird `number_type` | | -------------------- | -------------------------------------- | | `DID` | `local` ou `national`, selon le numéro | | `FreePhone` | `toll_free` | | `Mobile` | `mobile` | ## 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 : ```bash 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](/docs/api/reference/list-available-numbers) 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](/contact-sales) 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`](/docs/api/errors/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 : ```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"}' ``` 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](/docs/guides/numbers/buying-numbers#poll-an-order-that-did-not-finish) 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](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) 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}`](/docs/api/reference/get-workspace-number) et vérifiez que `status` est `active`. S'il est en attente, [déposez les documents de propriété](#déposer-les-documents-de-propriété). [Le statut d'un numéro alloué](/docs/guides/numbers/overview#the-status-of-an-allocated-number) 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` : ```bash 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` : ```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` avec [`E19001`](/docs/api/errors/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` : ```bash 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` : ```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"'"}]}' ``` 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](/docs/guides/numbers/ownership-paperwork#submit-every-answer) 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](/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"}]}' ``` 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}`](/docs/api/reference/get-workspace-number). 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](/docs/guides/numbers/ownership-paperwork) 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](/docs/guides/voice/receiving-calls#set-a-default-route) 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](/docs/guides/voice/sip-trunks) 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` : ```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. 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}` : ```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}"}' ``` Pour le basculement, ajoutez une seconde passerelle ; [Ce dont une passerelle a besoin](/docs/guides/voice/receiving-calls#what-a-gateway-needs) 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`](/docs/api/errors/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` : ```bash curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` 4. Pointez le numéro vers le 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"'"}}}' ``` Une réponse `200` affiche la nouvelle route. Un trunk avec les appels entrants désactivés renvoie `412` avec [`E21052`](/docs/api/errors/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](/docs/guides/voice/receiving-calls#deliver-calls-to-a-sip-trunk) 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. ```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" ``` Les filtres de la liste Telserv correspondent à ceux de Bird comme suit : | Filtre Telserv sur `GET /numbers` | Filtre Bird sur `GET /v1/numbers` | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number`, qui correspond au début du numéro | `prefix` sans `country_code`, qui correspond aux chiffres depuis le début du numéro complet | | `prefix`, qui correspond à l'indicatif d'accès et de zone tel que `3170` | `country_code` avec `prefix` défini sur les chiffres nationaux : `country_code=NL&prefix=70` | | `reference` avec une valeur partielle | `search`, qui correspond à une partie du numéro, du nom ou de la référence, sans tenir compte de la casse | | `reference` avec une valeur exacte entre guillemets | `reference`, qui renvoie les numéros ayant cette référence exacte. La correspondance est sensible à la casse | | Nouveau dans Bird | `number` renvoie un numéro complet donné avec son indicatif pays, avec ou sans `+` ou `00` : `+31612345678`, `31612345678` et `0031612345678` trouvent le même numéro | [Trouver un numéro dans votre liste](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) 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](/docs/guides/numbers/managing-numbers#list-every-number-you-hold) 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`](/docs/api/reference/list-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`](/docs/api/errors/E14002). Pour conserver le numéro jusqu'à la fin de la période déjà payée, annulez-le : ```bash 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 : ```bash 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`](/docs/api/errors/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](/docs/guides/numbers/managing-numbers#release-a-number) 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](/docs/guides/voice/destinations), 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é](/docs/guides/voice/caller-ids) de votre espace de travail, et le numéro testé dans `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": {} } } ``` Envoyez-la : ```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 ``` 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}`](/docs/api/reference/get-voice-leg), ou listez les segments passés vers le numéro avec [`GET /v1/voice/legs`](/docs/api/reference/list-voice-legs) et son filtre `to`, et vérifiez que votre équipement a reçu l'appel. [Créer un appel vocal](/docs/guides/voice/create-calls) 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](/docs/guides/numbers/buying-numbers) - [Gérer vos numéros de téléphone](/docs/guides/numbers/managing-numbers) - [Déposer les documents de propriété d'un numéro](/docs/guides/numbers/ownership-paperwork) - [Recevoir des appels](/docs/guides/voice/receiving-calls) - [Trunks SIP](/docs/guides/voice/sip-trunks) - [Idempotence](/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)