Documentation Technique

Transcription

1 Documentation Technique HTTP Application Programming Interface Page 1

2 Table des matières 1. Introduction Envoi SMS : XML HTTP POST et HTTP GET XML HTTP POST Format XML Spécification des paramètres d envoi Réponse au POST XML Exemple HTTP GET Spécification des variables d envoi Réponse à la requête GET Rapport de Délivrabilité La structure XML du Rapport de Délivrabilité Spécification des attributs des rapports de délivrabilité Exemple support@capitolemobile.com Page 2

3 1. Introduction Ce document fournit aux développeurs les commandes permettant l intégration de Services d envoi SMS en utilisant la CapitoleMobile HTTP Application Interface Programming (HTTP API). L API CapitoleMobile peut être utilisée pour l envoi de SMS ou bien la réception de rapports de délivrabilité (accusés de réception, de non réception, NPAI...etc.). Le système CapitoleMobile fournit deux methodes d envoi SMS : XML à travers le protocole HTTP (POST) Paramètres passés dans l URL via HTTP (GET) Dans ce qui suit nous verrons comment procéder à l envoi de SMS en utilisant l une et l autre de ces deux méthodes. Enfin nous verrons comment récupérer les rapports de délivrabilités (accusés de réception, de non réception, NPAI...etc.). support@capitolemobile.com Page 3

4 2. Envoi SMS : XML HTTP POST et HTTP GET 2.1. XML HTTP POST Les données XML (HTTP POST) doivent être envoyées à l URL suivante : Format XML La chaîne de caractère au format XML doit commencer par : «XML=». Vous avez ensuite le choix entre deux structures de données : Sans identification de l envoi Avec identification de l envoi <SMS> <authentification> <username></username> <password></password> </authentification> <message> <sender></sender> <text></text> <flash></flash> <type></type> </message> <recipients> <gsm></gsm> <gsm></gsm> <gsm></gsm> <gsm></gsm> </recipients> </SMS> <SMS> <authentification> <username></username> <password></password> </authentification> <message> <sender></sender> <text></text> <flash></flash> <type></type> </message> <recipients> <gsm messageid= msgid1 ></gsm> <gsm messageid= msgid2 ></gsm> <gsm messageid= msgid3 ></gsm> <gsm messageid= msgid4 ></gsm> </recipients> </SMS> support@capitolemobile.com Page 4

5 Comme décrit ci-dessus vous pouvez définir un identifiant spécifique pour chaque SMS envoyé, et ce, grâce à l attribut messageid. Cet attribut permet en particulier de tracer un groupe de SMS grâce aux rapports de délivrabilité (accusés de réception, de non réception...). En effet parmi les éléments collectés dans ces rapports, nous retrouvons le messageid, ce qui vous permettra d avoir des éléments statistiques par envoi groupé (par opération). messageid est un attribut optionnel Spécification des paramètres d envoi AUTHENTIFICATION username password Login du client (communiqué après inscription sur notre site Internet : Password du client (communiqué après inscription sur notre site Internet : Optionnel (par défaut numéro court). sender Soit numéro court («36173») ou bien sender personnalisé (ex : «CapitoleMob», 11 caractères alphanumériques max., doit avoir été préalablement validé par nos services) text Corps du message (160 caractères alphanumériques max.) MESSAGE flash Optionnel (par défaut SMS standard). «0» : SMS standard «1» : Flash SMS long Optionnel (par défaut max. 160 caractères alphanumériques) «yes» : SMS Long (jusqu'à 300 caractères alphanumériques) - Attention 2 crédits vous sont débités par envoi! gsm Numéro de téléphone mobile français (ex : , ) RECIPIENTS gsm messageid (Optionnel) Identifiant de l envoi SMS, défini par le client (récupérable dans le rapport de délivrabilité) support@capitolemobile.com Page 5

6 La création de nouveaux «Sender» doit se faire via notre service en ligne : La validation de l expéditeur par notre service de modération peut prendre entre 24h et 48h Réponse au POST XML Après le POST XML, le client reçoit instantanément un message retour relatif à l envoi : STATUS DESCRIPTION ERROR_SENDING_BETWEEN_8H_AND_22H les envois doivent se faire entre 8h et 22h NO_RECIPIENT Aucun destinataire AUTH_FAILED Erreur d authentification (login/password) NOT_ENOUGH_CREDITS Solde en crédits SMS PRO insuffisant pour réaliser l envoi EMPTY_MESSAGE Message vide TOO_LONG_MESSAGE Message comportant plus de 160 caractères (espace compris) MESSAGE_IN_MODERATION_STATUS Message en attente de modération _IS_BLACKLISTED Le numéro du destinataire a été blacklisté («STOP SMS» ) _IS_INVALID TOO_LONG_SENDER (Warning) Le numéro du destinataire est invalide L expéditeur comporte plus de 11 caractères. L envoi s effectue avec comme Sender un numéro court («36173») SENDER_NOT_VALIDATED (Warning) L expéditeur n a pas été validé par nos services. (voir espace client). L envoi s effectue avec comme Sender un numéro court («36173») SENDING_OK L envoi s est effectué avec succès support@capitolemobile.com Page 6

7 Exemple Requête POST HTTP utilisant une structure XML sans identification de l envoi : <?php // CapitoleMobile POST URL $posturl = " //Structure de Données XML $xmlstring = "<SMS> <authentification> <username>xxxx</username> <password>xxxxxx</password> </authentification> <message> <sender>un Ami</sender> <text>un message de la part d un ami!</text> </message> <recipients> <gsm> </gsm> <gsm> </gsm> <gsm> </gsm> <gsm> </gsm> </recipients> </SMS>"; // insertion du nom de la variable POST "XML" avant les données au format XML $fields = "XML=". urlencode(utf8_encode($xmlstring)); // dans cet exemple, la requête POST est realisée grâce à la librairie Curl $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $posturl); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); // Réponse de la requête POST $response = curl_exec($ch); curl_close($ch); // Ecriture de la réponse?> echo $response; support@capitolemobile.com Page 7

8 Requête POST HTTP utilisant une structure XML avec identification de l envoi : <?php // CapitoleMobile POST URL $posturl = " //Structure de Données XML $xmlstring = "<SMS> <authentification> <username>xxxx</username> <password>xxxxxx</password> </authentification> <message> <sender>un Ami</sender> <text>un message de la part d un ami!</text> </message> <recipients> <gsm messageid= 1000 > </gsm> <gsm messageid= 1001 > </gsm> <gsm messageid= 1002 > </gsm> <gsm messageid= 1004 > </gsm> </recipients> </SMS>"; // insertion du nom de la variable POST "XML" avant les données au format XML $fields = "XML=". urlencode(utf8_encode($xmlstring)); // dans cet exemple, la requête POST est realisée grâce à la librairie Curl $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $posturl); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); // Réponse de la requête POST $response = curl_exec($ch); curl_close($ch); // Ecriture de la réponse?> echo $response; Réponse, si tous les paramètres entrés sont corrects : SENDING_OK Si par exemple les identifiants username/password sont incorrects : AUTH_FAILED support@capitolemobile.com Page 8

9 2.2. HTTP GET Les requêtes HTTP GET devront être envoyées à l URL : Un exemple de SMS envoyé via une requête http GET : Spécification des variables d envoi AUTHENTIFICATION username password Login du client (communiqué après inscription sur notre site Internet : Password du client (communiqué après inscription sur notre site Internet : sender Optionnel (par défaut numéro court). Soit numéro court («36173») ou bien sender personnalisé (ex : «CapitoleMob», 11 caractères alphanumériques max., doit avoir été préalablement validé par nos services) text Corps du message (160 caractères alphanumériques max.) MESSAGE flash long Optionnel (par défaut SMS standard). «0» : SMS standard «1» : Flash SMS Optionnel (par défaut SMS standard, i.e 160 caractères max.) «no» : SMS standard «yes» : SMS "Long" (jusqu'à 300 caractères alphanumériques, 2 crédits SMS PRO par envoi) support@capitolemobile.com Page 9

10 gsm Numéro de téléphone mobile français (ex : , ) RECIPIENTS gsm messageid (Optionnel) Identifiant de l envoi SMS défini par le client (récupérable dans le rapport de délivrabilité) Réponse à la requête GET Après envoi de la requête HTTP GET, le client reçoit instantanément un message retour relatif à l envoi : STATUS DESCRIPTION ERROR_SENDING_BETWEEN_8H_AND_22H les envois doivent se faire entre 8h et 22h INVALID_HTTP_GET_FORMAT Aucun paramètre envoyé par la méthode GET MISSING_USERNAME La variable username manquante MISSING_PASSWORD La variable password manquante MISSING_SMS_TEXT La variable texte est manquante ou vide MISSING_DESTINATION_NUMBER La variable gsm est manquante AUTH_FAILED Erreur d authentification (login/password) NOT_ENOUGH_CREDITS Solde en crédits SMS PRO insuffisant pour réaliser l envoi TOO_LONG_MESSAGE Message comportant plus de 160 caractères (espace compris) MESSAGE_IN_MODERATION_STATUS Message en attente de modération _IS_BLACKLISTED Le numéro du destinataire a été blacklisté («STOP SMS» ) _IS_INVALID TOO_LONG_SENDER (Warning) Le numéro du destinataire est invalide L expéditeur comporte plus de 11 caractères. L envoi s effectue avec comme Sender un numéro court («36173») support@capitolemobile.com Page 10

11 SENDER_NOT_VALIDATED (Warning) L expéditeur n a pas été validé par nos services. (voir espace client). L envoi s effectue avec comme Sender un numéro court («36173») SENDING_OK L envoi s est effectué avec succès 3. Rapport de Délivrabilité Un «flux» XML POST est créé entre notre système et l applicatif client. Le client devra donc nous communiquer l URL vers lequel nous enverrons les Rapports de Délivrabilité La structure XML du Rapport de Délivrabilité Le rapport de délivrabilité est envoyé sous forme de données XML ayant la structure suivante : <DeliveryReport> <message id= date= gsm= status= /> <message id= date= gsm= status= /> </DeliveryReport> 3.2. Spécification des attributs des rapports de délivrabilité id Identifiant défini au moment de l envoi via l attribut messageid gsm Numéro de téléphone du destinataire date Date à laquelle le SMSC a communiqué à CapitoleMobile le rapport de délivrabilité support@capitolemobile.com Page 11

12 status NOT_SENT SENT Le message est mis en file d attente au niveau de nos serveurs mais ne peut être soumis au SMSC Le message a été envoyé en utilisant une route ne supportant pas les rapports de délivrabilité NOT_DELIVERED Le message n a pu être délivré DELIVERED Le message a été délivré au destinataire final (AR) INVALID_DESTINATION_ADDRESS Numéro invalide ou incorrect (NPAI) INVALID_MESSAGE_FORMAT Format du message invalide 3.3. Exemple Les Rapports de Délivrabilité sont envoyés au client à travers un flux XML à destination d une URL définie : ex. (scrip en PHP) Voici un exemple de ce que pourrait être le script «collector.php» <?php // Extraction de la structure XML grâce au parser PHP DOMDocument $dom = new DOMDocument(); $dom->loadxml(stripslashes($_post['xml'])); // Création d un nouvel objet XPath) $xpath = new domxpath($dom); // Extraction des elements contenus dans DeleveryReport $reports = $xpath->query("//deliveryreport/message"); foreach ($reports as $node) { $id = $node->getattribute('id'); $status = $node->getattribute('status'); $date = $node->getattribute('date'); $gsm = $node->getattribute('gsm'); }?> support@capitolemobile.com Page 12