Lister les types de numéros spéciaux et leurs tarifs pour un pays

Les numéros locaux se recherchent avec getcountries et getareas. Pour les numéros nationaux, gratuits, à coûts partagés, mondiaux et mobiles, appelez other avec le code ISO du pays.

• Les groupes apparaissent dans un ordre fixe et ceux qui ne contiennent aucune entrée sont omis.
• Chaque entrée présente les offres tarifaires de votre compte dans prices. Choisissez une offre selon ses valeurs channels, monthly_price, setup_price, per_minute et free_minutes, et conservez son price_id pour commander lorsque le point de terminaison de commande le demande.
• Si needs_registration a une valeur évaluée comme vraie, lisez restrictions avant de commander. Traitez ce texte comme un contenu d’affichage non fiable.
• Suivez next_function : v3/getnumbers/{uuid} permet de choisir un numéro précis, et v3/order/{uuid} permet de commander directement à partir de l’entrée.
• Une liste response vide accompagnée du code 200 signifie qu’aucun type de numéro spécial n’a été trouvé au moment de la requête. Si le catalogue était temporairement inaccessible, la réponse peut être incomplète ou ne pas être du JSON valide ; réessayez donc plus tard.
• Les pays absents du catalogue renvoient le code 404 sans statut HTTP correspondant. Vérifiez toujours status.code.

Requête

Requis : authentification HTTP Basic ou jeton Bearer (voir Authentification et réponses de l’API). En cas d’échec de l’authentification, une réponse HTTP 401 est renvoyée avant l’exécution de la recherche.

GET avec isocode dans le chemin. Si ce segment du chemin est omis, un champ isocode encodé au format formulaire est lu à la place.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/other/FR'

Réponse

Enveloppe standard. En cas de succès, status.code vaut 200, status.msg est vide et status.results indique le nombre de groupes. response est une liste de groupes. Champs d’un groupe : group_key (clé de type normalisée : national, tollfree, sharedcost, global, mobile ou une autre clé alphanumérique en minuscules) ; group_name (nom affiché) ; group_type_uuid (identifiant opaque du type) ; items. Les groupes suivent cet ordre : national, tollfree, sharedcost, global, mobile, puis les autres clés triées selon group_name. Les groupes sans items sont omis, tout comme le type local. Pour US, le groupe mobile est omis, sauf si votre compte est activé pour les numéros mobiles de US. Les éléments sont triés par name (sans tenir compte de la casse), puis par prefix. Champs d’un élément : uuid (identifiant opaque de l’entrée utilisé dans next_function) ; area_uuid (identifiant opaque du groupe du catalogue) ; country_uuid (identifiant opaque du pays) ; prefix (préfixe complet commençant par '+' et l’indicatif téléphonique du pays) ; name (nom dans le catalogue ; les guillemets peuvent être échappés par une barre oblique inverse) ; metered, overflow et needs_registration (indicateurs pouvant être de type boolean ou number ; interprétez toute valeur évaluée comme vraie comme un oui) ; restrictions (vide lorsqu’aucun enregistrement n’est nécessaire ; sinon, texte des exigences pouvant contenir des sauts de ligne HTML et un lien, des guillemets englobants et des caractères échappés ; traitez-le comme un texte d’affichage non fiable) ; state (pour US, CA et PR, un code d’État ou une liste vide lorsqu’aucun n’est connu ; pour les autres pays, le code ISO du pays) ; country_iso ; is_mobile (1 dans le groupe mobile, sinon 0) ; number_type (identique à group_key) ; available (nombre de type integer indiqué par le catalogue pour l’entrée, 0 lorsqu’il n’est pas indiqué) ; sms_coverage (1 si une fonctionnalité mentionne SMS ou MMS) ; returns_numbers (1 lorsque des numéros précis peuvent être listés) ; next_function ('v3/getnumbers/{uuid}' lorsque returns_numbers vaut 1, sinon 'v3/order/{uuid}') ; prices ; features (liste de chaînes décrivant les capacités) ; group_key ; group_type_uuid. Chaque entrée de prices contient price_id (identifiant opaque de l’offre), is_customer_custom (true lorsqu’une tarification personnalisée s’applique à votre compte ; uniquement pour les offres sans canaux inclus), per_minute et free_minutes (chaînes représentant des nombres décimaux), setup_price et monthly_price (chaînes avec deux décimales), ainsi que channels (nombre de canaux inclus, de type integer). Les entrées sans aucune offre tarifaire sont omises. Au maximum 1000 entrées du catalogue par type de numéro sont prises en compte par requête. Si aucun type ne contient d’entrées, response est une liste vide avec status.results à 0. Si la recherche en temps réel dans le catalogue échoue, la réponse peut ne pas utiliser cette enveloppe, ou certains groupes peuvent manquer.

Structure de réponse fournie à titre d’illustration ; il ne s’agit ni de données du compte en temps réel ni d’un devis actuel.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "group_key": "tollfree",
      "group_name": "Toll-free",
      "group_type_uuid": "00000000-0000-4000-8000-0000000000a1",
      "items": [
        {
          "uuid": "0000000000000000000000000000b001",
          "area_uuid": "0000000000000000000000000000a001",
          "country_uuid": "0000000000000000000000000000c001",
          "prefix": "+33800",
          "name": "Example Toll-free",
          "metered": true,
          "overflow": 0,
          "needs_registration": 0,
          "restrictions": "",
          "state": "FR",
          "country_iso": "FR",
          "is_mobile": 0,
          "number_type": "tollfree",
          "available": 10,
          "sms_coverage": 0,
          "returns_numbers": 1,
          "next_function": "v3/getnumbers/0000000000000000000000000000b001",
          "prices": [
            {
              "price_id": "0000000000000000000000000000d001",
              "is_customer_custom": false,
              "per_minute": "0.05",
              "free_minutes": "0",
              "setup_price": "0.00",
              "monthly_price": "5.00",
              "channels": 2
            }
          ],
          "features": ["voice"],
          "group_key": "tollfree",
          "group_type_uuid": "00000000-0000-4000-8000-0000000000a1"
        }
      ]
    }
  ]
}

Erreurs

• 500 : msg 'ISO Code parameter is required' : isocode est absent ou vide. Il s’agit d’une erreur de requête qui peut être corrigée. Aucun statut HTTP correspondant n’est défini.
• 404 : msg 'Error: no such country' : le pays est inconnu ou n’est pas lié au catalogue des numéros spéciaux. Aucun statut HTTP correspondant n’est défini.
• 401 : authentification absente ou échouée. Renvoyé avec le statut HTTP 401.

Disponibilité et effets de bord

• Ne passe aucune commande. Aucune étape de facturation ne figure dans le code de ce point de terminaison.
• Actualise les détails du catalogue et les devis tarifaires de votre compte, en remplaçant les devis antérieurs pour les mêmes offres. L’utilisation de ces devis par les points de terminaison de commande est documentée séparément.
• Les tarifs sont propres à votre compte et peuvent inclure une tarification personnalisée. La réponse ne précise aucune devise.
• Effectue des recherches en temps réel dans le catalogue et peut donc être plus lent que d’autres appels de découverte. Les résultats peuvent changer d’un appel à l’autre.