Lister les États américains ou les provinces canadiennes disposant de numéros en stock

Utilisez cette étape facultative pour les États-Unis ou le Canada afin de limiter la recherche à un État ou à une province. Seuls US et CA sont acceptés.

• Chaque entrée décrit les préfixes en stock pour cet État au moment de la requête.
• Suivez next_function pour lister les zones de l'État. Ce lien inclut déjà le filtre state, mais pas pid.
• La recherche de zones effectue une correspondance légèrement différente des informations sur l'État. Si, pour un État, next_function renvoie No areas found, appelez getareas sans préciser d'État à la place.
• Vérifiez status.code avant de lire response. Un pays non pris en charge, ou un pays sans stock correspondant, renvoie le code 404 sans statut HTTP correspondant.
• Une liste vide accompagnée du code 200 signifie qu'il existe du stock, mais qu'aucune information sur l'État n'y est associée. Appelez getareas sans préciser d'État.

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. Si ce segment du chemin est omis, un champ isocode encodé au format formulaire est lu à la place. Le paramètre facultatif pid est envoyé dans la chaîne de requête.

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

Réponse

Enveloppe standard. En cas de succès, status.code vaut 200, status.msg est vide et status.results indique le nombre d'entrées. response est une liste triée par name (sans tenir compte de la casse), puis par code state. Champs : state (code de l'État ou de la province issu des données d'État des préfixes, généralement composé de deux lettres ; les valeurs inhabituelles sont transmises telles quelles) ; name (nom dans le catalogue, ou code lorsque le catalogue ne lui associe aucun nom) ; country_iso ; available (stock total pour l'ensemble des préfixes comptabilisés, toujours supérieur à 0) ; prefix_count (nombre de préfixes en stock comptabilisés) ; is_mobile (1 si au moins un préfixe comptabilisé prend en charge les services mobiles ; toujours 0 pour US, sauf si votre compte est activé pour les numéros mobiles américains) ; sms_coverage (1 si au moins un préfixe comptabilisé dispose d'une couverture SMS) ; returns_numbers (1 si au moins un préfixe comptabilisé possède l'indicateur de renvoi de numéros ou ne possède aucune valeur pour cet indicateur) ; next_function ('v3/getareas/{isocode}?state={state}'). Si des préfixes en stock existent mais qu'aucun ne comporte d'information sur l'État, le résultat est status.code à 200 avec une liste vide et status.results à 0.

Structure de réponse fournie à titre d'exemple ; 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
  },
  "response": [
    {
      "state": "NY",
      "name": "New York",
      "country_iso": "US",
      "available": 120,
      "prefix_count": 8,
      "is_mobile": 0,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=NY"
    },
    {
      "state": "TX",
      "name": "Texas",
      "country_iso": "US",
      "available": 45,
      "prefix_count": 3,
      "is_mobile": 0,
      "sms_coverage": 0,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=TX"
    }
  ]
}

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 ; lisez status.code.
• 404 : msg 'getstates is only available for US and CA' : tout autre code pays. Aucun statut HTTP correspondant n'est défini.
• 404 : msg 'No states found' : aucun préfixe en stock ne correspond aux filtres de pays et de source. 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

• Consultation uniquement. Cette opération ne réserve rien, ne passe aucune commande et ne modifie rien. available est fourni à titre informatif et ne réserve aucun numéro.