Tester les api pour le mug

27 avril 2021 22 minutes de lecture

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 à gauche 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 vous garantit 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.

{
"code": "AUTHENTICATION_FAILED"
}

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 SMS 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": "AUTHENTICATION_FAILED"
}

{
"code": "JSON_INVALID",
"params": {"error": "should have required property 'text'"}
}

SMS reçu.

 

{
"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"
}
]}

{  
  "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"
      }
    ]
  }
}