Commander des numéros de téléphone à partir d’un préfixe

Commander à partir d’un préfixe

Utilisez cette opération lorsque le catalogue des préfixes vous invite à commander une quantité de numéros à partir d’un préfixe plutôt qu’à choisir individuellement des numéros disponibles. Commencez par les pays, les zones ou les États, puis les préfixes. Conservez l’identifiant du préfixe et le forfait tarifaire provenant d’un même résultat à jour. Pour un numéro précis sélectionné dans une liste de numéros disponibles, utilisez Acheter un numéro de téléphone sélectionné.

Cette requête peut acheter des numéros et entraîner des frais. Il ne s’agit ni d’un devis, ni d’une réservation, ni d’une simulation. Examinez les frais de mise en service et les frais mensuels, les tarifs à la minute des appels entrants, les minutes incluses, les canaux, les exigences d’enregistrement et les limites d’achat du compte avant de l’envoyer. Un résultat du catalogue ne réserve aucun stock et ne fige pas les prix. Des vérifications liées à l’approvisionnement du compte en fonds peuvent avoir lieu avant l’exécution de la commande ; une erreur ne prouve pas à elle seule qu’aucun achat ni aucun approvisionnement du compte en fonds n’a eu lieu.

Envoyer la demande d’achat

Utilisez un compte API activé, via HTTPS, depuis une adresse IP source autorisée. Définissez les variables à partir de votre sélection actuelle dans le catalogue et de votre configuration d’acheminement approuvée. La commande suivante achète un numéro.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

Une requête POST avec des données de formulaire est présentée ci-dessus. Le coordinateur lit également un objet JSON lorsque Content-Type vaut application/json. Les champs JSON remplacent les champs correspondants du formulaire ou de la requête. Utilisez un seul encodage de manière cohérente ; n’envoyez pas de valeurs contradictoires dans les paramètres de requête et dans le corps.

Paramètres d’acheminement et de renouvellement

Choisissez les mêmes paramètres d’acheminement que ceux que vous utiliseriez pour le numéro dans le portail. Il s’agit de valeurs de configuration avancée, et non d’instructions pour créer un PBX hébergé ou un trunk d’origination. Réutilisez une configuration de compte dont le fonctionnement est établi et vérifiez le numéro enregistré après l’achat. L’acceptation d’un achat ne suffit pas à vérifier que l’acheminement des appels vocaux ou des SMS fonctionne.

Ces champs sont normalisés et transmis au processus d’achat, mais leur persistance varie selon les parcours de traitement du stock. La route de commande actuelle ne propose pas, comme protections équivalentes, les champs de plafonnement strict du devis décrits dans le guide d’achat d’un numéro sélectionné. Utilisez les autorisations d’achat et les limites tarifaires du compte, puis examinez la configuration du numéro obtenue.

Lire le résultat complet

Analysez le corps JSON et examinez status.code et status.msg, même lorsque la requête HTTP réussit. Cette route écrit sa propre réponse JSON, et la fonction auxiliaire de réponse partagée ne fait pas non plus nécessairement correspondre le code applicatif au statut HTTP. Les codes applicatifs peuvent être des nombres JSON ou des chaînes numériques. N’exigez pas status.results ; ce champ n’est pas présent dans le résultat normal d’une commande.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

L’identifiant, le numéro et les prix ci-dessus sont fictifs. Traitez l’identifiant de commande comme une valeur opaque. numbers répertorie les numéros que cette réponse indique comme achetés ; comparez la longueur de cette liste à la quantité demandée. Les montants des prix sont des chaînes de caractères et cette réponse arrondit les tarifs monétaires à deux décimales, y compris per_minute ; utilisez le catalogue à jour pour obtenir la précision d’origine des tarifs. Les minutes incluses et les canaux peuvent être reçus sous forme de valeurs numériques ou de chaînes numériques.

Le bloc de prix décrit le forfait sélectionné utilisé pour construire la réponse ; il ne constitue ni une facture détaillée pour chaque numéro ni le total de la commande. Plusieurs numéros candidats du stock peuvent relever de forfaits différents. Rapprochez les numéros achetés individuellement et les transactions du compte plutôt que de multiplier les montants de ce bloc en supposant qu’ils prouvent le total final.

Achats partiels et résultats incertains

Un code applicatif de 200 peut s’accompagner d’un avertissement et d’un nombre de numéros inférieur à la quantité demandée. Un échec ultérieur n’annule pas les numéros déjà achetés. Conservez l’identifiant de commande, les numéros et le message renvoyés. Rapprochez ces numéros avec votre inventaire et les transactions du compte avant de décider de commander une quantité restante.

Un dépassement de délai, une interruption de connexion pendant la requête, une réponse mal formée ou une erreur après l’envoi ne prouve pas qu’il ne s’est rien passé. N’envoyez pas automatiquement une autre demande d’achat, même avec la même référence. Conservez la requête d’origine, la référence et tout identifiant de commande renvoyé, vérifiez l’inventaire et les transactions du compte, et contactez l’assistance si le résultat reste incertain.

Une commande non confirmée peut renvoyer le code applicatif 400 avec un message indiquant que sa confirmation est toujours en cours. Conservez l’identifiant de commande renvoyé et rapprochez cet achat avec vos enregistrements ; ce message ne vous invite pas à soumettre à nouveau la commande. Le mécanisme de récupération des commandes enregistrées assure le suivi interne de la commande d’origine. Une nouvelle requête à cette opération crée une tentative d’achat distincte au lieu de reprendre une commande à partir de votre référence ; elle peut donc acheter et facturer des numéros supplémentaires. N’utilisez pas des demandes d’achat répétées pour vérifier un statut ou rechercher des numéros dans le stock.

Enregistrement et activation

Un numéro acheté ou attribué peut encore nécessiter un enregistrement ou une activation. Si needs_registration vaut 1, examinez restrictions et registration_requirements. Ce dernier champ peut indiquer v3/get_requirements avec des valeurs pour country et number_type. Effectuez la procédure applicable de vérification d’identité ou d’adresse et confirmez le statut du numéro avant de compter sur les appels entrants ou la messagerie.

features décrit les fonctionnalités annoncées ; ce champ ne vérifie ni le routage effectif, ni l’approbation d’une campagne, ni l’acheminement des SMS, ni la réception des fax. Vérifiez les paramètres d’acheminement enregistrés et effectuez le test de service approprié lorsque le numéro est actif.

Notifications de rappel des commandes

Les notifications de rappel envoient par POST du JSON contenant le statut et la réponse de la commande, avec votre référence ajoutée lorsqu’elle a été fournie. Elles sont envoyées pour les achats signalés, y compris les résultats partiels. L’échec d’une notification de rappel n’annule pas l’achat. L’envoi peut être retenté ; traitez donc les doublons à l’aide de l’identifiant de commande et rapprochez les numéros avec vos enregistrements plutôt que de lancer un autre achat.

Cette route n’ajoute pas de signature cryptographique aux notifications de rappel. Traitez une notification de rappel comme une notification à rapprocher de l’inventaire obtenu via un accès authentifié, et non comme une autorisation indépendante de facturer, de provisionner des services ou d’accorder un accès. Ne placez pas d’identifiants d’authentification API dans l’URL de rappel. Soumettre un autre achat avec une URL de rappel différente ne met pas à jour la commande d’origine ; cela crée une tentative d’achat distincte. Conservez l’identifiant de la commande d’origine lorsque vous demandez à l’assistance d’examiner sa notification de rappel.

Échecs à gérer