Lister les zones de couverture d’un pays

Après avoir choisi un pays (et, pour les États-Unis ou le Canada, éventuellement un État ou une province via getstates), appelez getareas pour voir dans quelles zones des numéros sont proposés. Conservez l’identifiant uuid de la zone pour l’étape suivante.

Chaque zone mène à l’une des deux étapes suivantes :

• available > 0 : next_function vaut v3/getprefixes/{uuid}, avec ?state= ajouté si vous avez filtré par État ou province. Utilisez ce lien pour consulter les préfixes.
• available = 0 : la zone possède des préfixes, mais aucun stock, et next_function vaut v3/order/{uuid}. Consultez la documentation de commande pour connaître les exigences de cette étape.

available indique le total pour l’ensemble de la zone, même si vous filtrez par État ou province. Le filtre d’État ou de province accepte un code ou un nom complet, mais ne fonctionne que pour US et CA. Si ce filtre renvoie No areas found, réessayez sans ce filtre. Les vérifications s’effectuent dans cet ordre : code pays manquant, pays inconnu, filtre d’État ou de province pour un autre pays, État ou province invalide, aucune zone correspondante. Chacun de ces cas renvoie le code 500 ou 404 dans status.code, sans statut HTTP correspondant.

Requête

Obligatoire : 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 et les paramètres facultatifs state et pid dans la chaîne de requête. Si le segment du chemin est omis, un champ isocode encodé comme un formulaire est lu à la place.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

Réponse

Enveloppe standard. En cas de succès, status.code vaut 200, status.msg vaut 'Results: N', status.results vaut N et response est une liste triée par nom de zone. Champs : uuid (identifiant opaque de la zone utilisé à l’étape suivante) ; country_uuid (identifiant opaque du pays de 32 caractères, inutile pour la suite) ; name ; area_type et number_type (descripteurs du catalogue ; les entrées ne sont pas nécessairement des types de numéros locaux) ; country_iso ; is_mobile (0 ou 1, d’après les indicateurs mobiles de la zone ; toujours 0 pour US sauf si votre compte est autorisé à utiliser les numéros mobiles du pays US) ; available (stock total pour les préfixes correspondants de la zone, sans restriction à l’État ou à la province demandé) ; sms_coverage (0 ou 1) ; returns_numbers (0 ou 1, indicateur le plus élevé parmi les préfixes de la zone) ; latitude et longitude ; state_iso ; next_function. state_iso : lorsqu’un filtre d’État ou de province est appliqué, il s’agit du code résolu du filtre. Pour US et CA sans filtre, la valeur correspond à l’État ou à la province dont le nom est identique à celui de la zone, sinon à la valeur enregistrée pour la zone, sinon à un code déduit des données des préfixes de la zone. Pour les autres pays, il s’agit de la valeur enregistrée, qui peut être vide. next_function vaut 'v3/getprefixes/{uuid}' (avec '?state={code}' en plus lorsqu’un filtre est appliqué) quand available est supérieur à 0, sinon 'v3/order/{uuid}'. Les zones sans aucun préfixe correspondant sont omises. Les zones ayant des préfixes mais aucun stock sont renvoyées avec available à 0.

Exemple de structure de réponse ; il ne s’agit ni de données de compte en temps réel ni d’un devis actuel.

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

Erreurs

• 500 : msg 'ISO Code parameter is required' : isocode est absent ou vide. Il s’agit d’une erreur de requête que vous pouvez corriger. Aucun statut HTTP correspondant n’est défini.
• 404 : msg 'Error: no such country' : le code pays est inconnu. Aucun statut HTTP correspondant n’est défini.
• 404 : msg 'State filter is only available for US and CA' : une valeur state non vide a été envoyée pour un autre pays. Aucun statut HTTP correspondant n’est défini.
• 404 : msg 'Invalid state' : state n’est ni un code connu ni un nom connu pour ce pays. Aucun statut HTTP correspondant n’est défini.
• 404 : msg 'No areas found' : aucune zone ne correspond aux filtres de pays, de source et d’État ou de province. Aucun statut HTTP correspondant n’est défini.
• 401 : authentification absente ou échouée. Renvoyée avec le statut HTTP 401.

Disponibilité et effets de bord

• Consultation uniquement pour les comptes clients. Cette opération ne réserve rien, ne passe aucune commande et ne modifie rien.
• available est fourni à titre indicatif et peut changer avant l’étape suivante.