Authentification et réponses API

Utilisez les identifiants API

Envoyez les requêtes v3 via HTTPS à https://api.multitel.net. Chaque point de terminaison de ce guide nécessite une authentification. Conservez les identifiants sur votre serveur et ne les placez jamais dans du JavaScript de navigateur, des pages publiques, des captures d'écran ou un dépôt de code source.

Utilisez l'une de ces formes d'identifiants :

• HTTP Basic avec le nom d'utilisateur et le mot de passe API configurés pour votre compte MultiTEL.
• Jeton Bearer dans l'en-tête Authorization: Bearer YOUR_API_TOKEN, pour un compte API activé configuré pour l'authentification par jeton. Les requêtes avec jeton ne sont acceptées que depuis les adresses autorisées pour ce compte API.

Si une liste d'autorisation IP est configurée pour votre compte API, envoyez toutes les requêtes depuis des adresses autorisées.

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

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

Les variables de ces exemples sont des espaces réservés pour les identifiants que vous stockez en privé dans votre environnement.

Gérez les échecs d'authentification

Les échecs d'authentification sont envoyés avec le statut HTTP 401. Le corps utilise l'enveloppe standard, avec status.code défini à 401 et une chaîne vide comme response.

• Aucun identifiant : status.msg est Username and password are required, et la réponse inclut un défi d'authentification Basic.
• Jeton Bearer rejeté : si l'en-tête Authorization utilise le schéma Bearer et que le jeton est inconnu, désactivé ou non autorisé depuis votre adresse, status.msg est Invalid bearer token. Aucun autre identifiant n'est essayé lorsqu'un en-tête Bearer est présent.
• Identifiants Basic invalides : status.msg commence par A valid username and password pair are required., et la réponse inclut un défi d'authentification Basic. Le message peut contenir davantage de texte de diagnostic, ne l'analysez donc pas.

Ne réessayez pas automatiquement avec les mêmes identifiants. De nombreuses tentatives échouées depuis une même adresse en peu de temps peuvent entraîner le blocage des requêtes ultérieures provenant de cette adresse.

Lisez le corps de la réponse

La plupart des points de terminaison v3, notamment getcountries, getstates, getareas et other, renvoient du JSON dans cette enveloppe :

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

Il s'agit d'une réponse illustrative de liste de pays, et non d'une déclaration sur l'inventaire ou les capacités actuels.

Une réponse d'erreur ressemble à ceci :

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

Si une réponse ne peut pas être encodée, le corps contient status.code 500, status.msg Response encoding error, et un objet vide comme response.

Le point de terminaison historique GET /v3/countries renvoie {"code": 200, "data": [...]} à la place. Vérifiez la réponse documentée de chaque point de terminaison. Si un corps n'est pas du JSON valide, par exemple après une défaillance inattendue du serveur, considérez la requête comme échouée et réessayez ultérieurement.

Codes de résultat API et statut HTTP

status.code est le code de résultat API. Ce n'est pas le statut HTTP. Les échecs d'authentification sont envoyés avec HTTP 401. Sinon, les points de terminaison de découverte signalent des résultats tels que 404 et 500 uniquement dans status.code et ne définissent pas de statut HTTP correspondant. Un résultat introuvable ou à paramètre manquant peut donc arriver avec un statut HTTP de réussite. Vérifiez toujours status.code avant d'utiliser response.

Le code de résultat 500 avec le message ISO Code parameter is required signifie qu'un paramètre requis est manquant. Corrigez la requête au lieu de la considérer comme une panne de serveur.

Suivez next_function

Les résultats de découverte incluent next_function. Il s'agit d'un chemin relatif sans barre oblique initiale, parfois avec une chaîne de requête, par exemple v3/getareas/US ou v3/getareas/US?state=NY. Préfixez-le avec https://api.multitel.net/ pour construire la requête suivante, et authentifiez cette requête de la même manière. Les filtres facultatifs que vous avez envoyés, tels que pid, ne sont pas repris dans next_function. Ajoutez-les de nouveau si vous en avez besoin.

Sélecteur d'inventaire facultatif (pid)

getcountries, getstates et getareas acceptent le paramètre facultatif pid qui limite les résultats à une seule source d'inventaire. Utilisez-le uniquement avec une valeur fournie par MultiTEL, soit sous sa forme numérique, soit sous sa forme hexadécimale de 32 caractères. Omettez-le pour un usage normal. Envoyez pid dans la chaîne de requête. Si le point de terminaison ne reconnaît ou n'accepte pas la valeur, il l'ignore sans erreur, et la requête se comporte comme si pid avait été omis.

Séparez la découverte des commandes

Les recherches de pays, d'États et de zones ne modifient pas votre compte. Le catalogue de numéros spéciaux (other) actualise les détails du catalogue et enregistre des devis pour votre compte, mais il ne passe aucune commande. Aucune requête de découverte ne réserve un numéro, et l'inventaire peut changer entre les requêtes. Vérifiez les exigences et le prix d'un numéro avant d'utiliser un point de terminaison de commande.

Pour les achats, les affectations, les messages, les envois de fax et les autres actions, suivez les règles de nouvelle tentative propres à chaque point de terminaison. Si une action expire après sa soumission, vérifiez son statut ou vos relevés de compte avant de la répéter. Une réponse perdue ne prouve pas que l'action a échoué.