Assistance en ligne

DMC – Tester les API pour le MUG

Tutoriel 22 minutes de lecture imprimer

Le MUG, Message Unitaire Garanti. Cet article décrit les étapes détaillées afin que vous puissiez envoyer des SMS au travers des API du Mug.

Définition du MUG

Le MUG, Message Unitaire Garanti, est une Offre SFR Business qui répond aux besoins des Clients qui souhaitent transmettre des SMS transactionnels le plus rapidement possible. SFR Business garantit au client ayant souscrit à l’offre MUG que le temps de traitement et de transmission à l’opérateur final (pour la France) de leurs SMS sera inférieur à 5 secondes. 

Présentation

Afin de pouvoir envoyer des requêtes sur les API du Mug, vous devez, au préalable, souscrire à l’offre DMC-MUG. Vous obtiendrez ainsi un couple identifiant / mot de passe qui vous permettra d’envoyer des SMS.

Documentation

Vous trouverez la documentation en cliquant sur le bouton en bas à droite de la page https://www.dmc.sfr-sh.fr/mug/api/V1/api-docs.

Utilisation

Les API Mug requièrent une authentification basée sur les standards (oAuth 2.0) au format REST. Cela consiste à effectuer des requêtes HTTP (GET ou POST) en utilisant la norme SSL, avec des paramètres en en-tête pour sécuriser vos appels.

Limitation

Par défaut, le nombre d’appels simultanés des différentes méthodes des API du Mug est limité à 20 par seconde. Toute demande supplémentaire sera rejetée. Les trois méthodes « Token », « POST Message » et
« GET Message » comptent pour un appel. Si vous rencontrez des besoins particuliers nécessitants d’augmenter cette limite, nous vous invitons à vous rapprocher de nos équipes pour étudier une offre sur mesure. 

Garantie

L’utilisation des API du MUG peut vous garantir un délai d’envoi de 5 secondes. Ce délai correspond au temps de traitement par la plateforme, de la date de création du message (état « NEW ») à la date de soumission du SMS à l’opérateur (état « SENT »). Aucune garantie n’est fournie sur la date de réception du SMS par le mobile (hors réseau, mobile éteint, …)  

Tout SMS traité par la plateforme 20 secondes après sa date de création ne sera pas envoyé (et non facturé).  

Tout SMS envoyé après le délai garanti et avant le délai d’expiration de 20 secondes ne sera pas facturé.

Utilisation

Les exemples ci-dessous sont réalisés via la page swagger mis à votre disposition pour tester les fonction de nos API. Nous ne traitons aucun langage de programmation.

Obtenir un Token

Pour commencer, vous devez générer un token valide afin d’appeler les API Mug. Pour cela, vous devez utiliser la méthode POST /services/{service_id}/token via le site

Cliquez  sur le bouton « Try it out », puis replissez les champs indiqués après avoir appuyé sur le bouton « Edit » :

  1. Mettre l’identifiant du service (voir votre mémento)
  2. Mettre le mot de passe MUG fourni dans votre mémento.
  3. Cliquez sur le bouton « Execute ».

Vous obtiendrez la requête à exécuter avec curl (A) et la réponse fournie cette requête, dans le cas ci-dessus le token (B) à utiliser pour les autres fonctions (à renseigner via bouton « Autorize » en haut de l’écran).

Si la méthode POST est un succès, un code 201 est retourné et la réponse (JSON) , comme ci-dessous.

Si la méthode POST est un échec, un code 401 est retourné et la réponse (JSON) doit ressembler à :
{
"code": "AUTHENTICATION_FAILED"
}
  !   Un token reste valide pendant une durée de 30 minutes. Passé ce délai, un nouveau token doit être généré en rappelant la méthode POST /services/{service_id}/token.
 

Renseigner le token :

Cliquez sur le bouton

Copier votre

Envoyer un SMS

 

Afin d’envoyer un SMS depuis l’API Mug, vous devez utiliser le token que vous venez de générer dans l’en-tête « Autorization » (voir ci-dessus) et appeler la méthode POST /services/{service_id}/messages :
 

Les paramètres obligatoires sont :

  • To : Numéro de téléphone du destinataire au format 06/07xxxxxxxx ou +32xxxxxxxx pour l’international.
  • Text : Contenu du message à envoyer. Le nombres de SM envoyés dépends de la longueur du texte  (voir longueur SMS).

Les paramètres optionnels sont :

  • From : OADC à utiliser pour surcharger le Short Code (surcoût eventuel)
  • extRef : La référence externe issue de votre SI. Cette référence sera remontée dans les comptes rendus
  • unicode : Permet d’envoyer des SMS encodés en utf8. Par défaut l’encodage utiliséest l’ISO8859-1
  • flash : Permet d’envoyer des SMS flash, SMS non stockés dans la mémoire de l’appareil
     

Si la méthode POST est un succès, un code 201 est retourné et la réponse (JSON) doit ressembler à :

{
"id": "5bb31c2f911ea924bdd42d75"
}

Si la méthode POST est un échec, un code de type 400 est retourné et la réponse (JSON) doit ressembler à :

Code 401 (token expiré)
{
"code": "AUTHENTICATION_FAILED"
}
Code 400 (parameter manquant)
{
"code": "JSON_INVALID",
"params": {"error": "should have required property 'text'"}
}
  !   Pour les comptes de test, il existe une limitation sur la durée de validité et sur le nombre de SMS autorisés par mois.
 

SMS reçu.


 

Compte rendu

 
Pour connaitre le résultat de l’envoi d’un SMS, vous devez utiliser le token que vous venez de générer dans l’en-tête « Autorization », indiquer l’identifiant du message reçu lors de l’envoi du SMS et appeler la méthode GET /services/{service_id}/messages/{message_id} :
 
 
Si la méthode GET est un succès, un code 200 est retourné et la réponse (JSON) doit ressembler à :
 
{
"from": "Mug",
"to": "0601020304",
"text": "Test MUG",
"unicode": false,
"flash": false,
"id": "5bb5bdce911ea924bddaa243",
"date": "2018-10-04T07:14:22.000Z",
"history": [
{
"date": "2018-10-04T07:14:22.000Z",
"status": "NEW"
},
{
"date": "2018-10-04T07:14:23.000Z",
"status": "SENT",
"infos": "submitted with sender Mug"
},
{
"date": "2018-10-04T07:14:24.000Z",
"status": "RECEIVED"
}
]}
 
Si la méthode GET est un échec, un code de type 400 est retourné et la réponse (JSON) doit ressembler à :
Code 401 (token expiré)
{
« code »: « AUTHENTICATION_FAILED »
}
 

Liste des états

 
Un SMS envoyé via l’API MUG passera successivement par plusieurs états :
 
NEW : réception par les API d’une nouvelle demande d’envoi de SMS. Cet état correspond au début du calcul de la garantie.
CRA_SMS_SENT : le SMS a été soumis à l’opérateur. Cet état correspond à la fin du calcul de la garantie.
 
Après l’état « CRA_SMS_SENT », le SMS peut passer en état «CRA_SMS_RECEIVED» (qui indique que le SMS a été délivré sur le mobile du destinataire) ou en état « ERREUR » dont les différents cas de figure sont décrits ci-dessous :
 
  • CRA_SMS_ERROR : Une erreur est survenue lors de l’envoi du SMS
  • CRA_SMS_OPINVALID : Opérateur du destinataire invalide
  • CRA_SMS_BLACKLIST : Destinataire blacklisté sur la plateforme
  • CRA_SMS_OPBLACKLIST : Destinataire blacklisté par l’opérateur
  • CRA_SMS_INVALIDFROM : Champ OADC invalide
  • CRA_SMS_WRONGNUMBER : Format de numéro invalide
  • CRA_SMS_FALSENUMBER : Abonné absent ou numéro non attribué
  • CRA_SMS_OPERROR : Problème lors de la communication vers l’opérateur
  • CRA_SMS_OPFAILURE : Erreur de transmission du message à l’opérateur
  • CRA_SMS_OPFULL : Surcharge du SMS-C (lien opérateur)
  • CRA_SMS_COUNTRY : Pays de destination non supporté
  • CRA_SMS_FULLSIM : Carte SIM du destinataire pleine
  • CRA_SMS_LOTOFMSG : Trop de messages envoyés vers ce numéro
  • CRA_SMS_REJECTED : Message rejeté par l’opérateur
  • CRA_SMS_BLOCKED : Appel bloqué par l’opérateur

 

Push_CRA

 
Le Push_Cra est le mécanisme qui consiste à envoyer en temps réel tous les comptes rendus de vos SMS sur une URL de votre choix.
 
Les comptes rendus sont au format json et contiennent l’ensemble des états par lesquels est passé le SMS :
  • SENT : Le SMS a été pris en compte par l’opérateur
  • RECEIVED : Le SMS a été reçu sur le mobile du destinataire
  • ANSWERED : Le destinataire a répondu au SMS
  • ERROR : Une erreur est survenue lors de l’envoi du SMS
Chaque compte rendu contient :
  • Username : l’identifiant du service utilisé pour envoyer le SMS
  • To : numéro du destinataire au format international
  • Date : date de l’évènement auquel correspond le compte rendu
  • Call_id : identifiant de l’envoi (à fournir pour diagnostique en cas de problème)
  • Ref_externe : référence externe fournie lors de la soumission du SMS
  • Status_list : liste des états horodatés par lesquels sont passés le SMS
  • status : état du SMS au moment de la génération du compte rendu

Exemples :

{  
  "status_report":{  
    "username":"123456789",
    "sms":[  
      {  
        "to":"+33601020304",
        "date":"2018-10-19 11:48:38 CEST",
        "call_id":"5bc9a8751a34791aff429efe",
        "ref_ext erne":"123456",
        "status_list":[  
          {  
            " date":"2018-10-19 11:48:38 CEST",
            "type":"SENT"
          }
        ],
        "s tatus":"SENT"
      }
    ]
  }
}2018-10-1909:48:41{  
  "status_report":{  
    "username":"123456789",
    "sms":[  
      {  
        "t o":"+33601020304",
        "date":"2018- 10-19 11:48:39 CEST",
        "call_id":"5bc9a8751a34791aff429efe",
        "ref_ext erne":"123456",
        "status_list":[  
          {  
            " date":"2018-10-19 11:48:39 CEST",
            "type":"RECEIVED"
          }
        ],
        "status":"RECEIVED"
      }
    ]
  }
}2018-10-1910:03:28{  
  "status_report":{  
    "username":"123456789",
    "sms":[  
      {  
        "t o":"+33601020304",
        "date":"2018- 10-19 12:03:25 CEST",
        "call_id":"5bc9a8751a34791aff429efe",
        "ref_ext erne":"123456",
        "status_list":[  
          {  
            " date":"2018-10-19 12:03:25 CEST",
            "type":"ANSWERED",
            "info":"Bien reçu"
          }
        ],
        "status":"ANSWERED"
      }
    ]
  }
}2018-10-1910:03:29{  
  "status_report":{  
    "username":"123456789",
    "sms":[  
      {  
        "t o":"+33601020304",
        "date":"2018- 10-19 12:03:21 CEST",
        "call_id":"5bc9a8751a34791aff429efe",
        "ref_ext erne":"123456",
        "status_list":[  
          {  
            " date":"2018-10-19 12:03:21 CEST",
            "type":"ANSWERED",
            "info":"Ok"
          }
        ],
        "status":"ANS WERED"
      }
    ]
  }
}

Ces informations vous ont-elles aidé ?

Merci pour votre vote

Laurent

Voir ses articles