MANUEL INTERFACE HTTP version 2.4 (7 octobre 2005)

Transcription

1 KLUGHER MANUEL INTERFACE HTTP version 2.4 (7 octobre 2005) Introduction : L interface HTTP de klugher.com vous permet d intégrer les fonctions d envoi de SMS dans vos applications. Elle est accessible tant par la méthode POST que par la méthode GET. En GET, attention cependant à la longueur totale de votre requête qui est limitée. Le coût d utilisation de cette interface est le même que l utilisation de nos services par le site web ou par notre client Windows. Consultez notre page Internet Couverture pour plus de détails. A l heure actuelle, l interface HTTP permet l envoi de messages texte, flash et binaires, avec expédition immédiate. Vous pouvez demander un accusé de réception. Attention : si vous préciser une ORIGINE (SENDER ID) pour le message, ou si vous demandez un accusé de réception, il peut y avoir un surcoût. (voir page Couverture du site Internet). Remarque : les SENDER ID alphanumériques doivent être limités à 11 signes, les numériques (= numéro de GSM) peuvent aller jusqu à 16 signes. Ils doivent être spécifiés en format international, sans le +. Par exemple, pour le numéro , il faut spécifier Attention : tous les opérateurs n acceptent pas les SENDER ID alphanumériques. Afin d assurer une fiabilité maximale, il est conseillé d utiliser un SENDER ID numérique.

2 Historique : Version Date Commentaire Première version SENDER ID modifié et accusés de réception ajouté Liste des codes d erreur ajoutée Nouveau format de sortie du script en XML URL de notification pour accusés de réception ajoutée Modification format XML réponse Accepte les SMS binaires Possibilité d URL de notification par défaut Description des paramètres de la requête de notification Ajout d un mode TEST Ajout des paramètres NOSPAM, GATE et RELIAB Modification XML de réponse (ajout du coût et des crédits)

3 Paramètres : adresse du script : Paramètres : PARAMETRE TYPE COMMENTAIRE USER Obligatoire Nom d utilisateur Klugher PASS Obligatoire Mot de passe Klugher ORIG Optionnel Signature (expéditeur). N est pas garanti et ne fonctionne pas sur tous les réseaux. 11 caractères alphanumériques ou 16 caractères numériques maximum. Si ce paramètre est utilisé, le système cherchera automatiquement une passerelle compatible. S il n y en existe pas, le SMS ne sera pas envoyé. TO Obligatoire Destinataire. Numéro de GSM en format international, sans le + au début MSG Obligatoire Texte du Message (160 caractères). Le message doit être urlencodé. voir explications ci-dessous. CLASS Obligatoire TEXT ou UDH FLASH Optionnel Permet l envoi en mode flash (mettre à 1 ). DELREC Optionnel Demande d accusé de réception (mettre à «1») NOTIF Optionnel URL à laquelle transmettre les accusés de réception Attention : il faut que cette URL soit url-encodée. TEST Optionnel Le SMS est créé mais n est pas envoyé (mettre à «1») GATE Optionnel Paramètre précisant la passerelle à utiliser pour l envoi du message. A ne pas utiliser sauf cas très spécifique et après avoir consulté Klugher.com. NOSPAM Optionnel Mettre à «1» pour spécifier que le message ne risque absolument pas d être considéré comme du spam. Cela permet d améliorer la fiabilité des envois. ATTENTION : ce paramètre n est pas pris en compte tant que votre compte n a pas été validé pour l utiliser. Nous contacter à ce sujet. RELIAB Optionnel Valeur numérique précisant la fiabilité minimale requise pour les envois. 1 est la fiabilité maximale, 3 est la fiabilité par défaut, 5 la moins bonne. Spécifier une valeur plus basse restreint les passerelles utilisables pour l envoi de votre message. Corps du message : il doit être urlencodé, c est-à-dire que l espace doit être remplacé par un + et que les caractères autres que a-z, A-Z, 0-9 et -_. doivent être remplacés par %xx où xx est la valeur hexadécimale du caractère sur deux positions.

4 Exemples : Exemple de SMS normal, avec SENDER ID obligatoire mais sans accusé de réception : &MSG=hello+world&CLASS=TEXT Exemple de SMS FLASH : &MSG=hello+world&CLASS=TEXT&FLASH=1 Exemple de SMS normal, sans SENDER ID mais avec accusé de réception : hello+world&class=text&delrec=1&notif=http%3a%2f%2fwww.yourdomain.com %2Fscript.php Exemple de SMS binaire : B8423F0BB C F6E2F766E642E E6D6D732D6 D AF848C D67008D90890E802B D4D53008A808E020D A A2F2F E6B6C E636F6D2F6D2F3F713D D6700&CLASS=UDH Pour les envois binaires, le contenu doit être fourni sous forme hexencodée (encodage hexadécimal) et CLASS doit être égal à UDH. Remarques : Si DELREC=1 mais que NOTIF est absent ou non-valide, l accusé de réception sera seulement visible sur l interface web de notre service. Vous pouvez également nous communiquer une URL de notification par défaut. Dans ce cas, l accusé sera envoyé sur cette URL par défaut, sauf si une autre est précisée par NOTIF. Si le paramètre TEST=1, le SMS sera créé mais ne sera pas envoyé et les crédits ne seront pas débités. Ceci dit, il vous faut quand même des crédits sur votre compte pour éviter une erreur pour crédits insuffisant. Le code statut renvoyé lors d un test OK est 100. Remplacer xxx par le username et yyy par le mot de passe et mettre un destinataire correct. ATTENTION : essayer d'abord en copiant-collant dans un browser standard avant d'entreprendre les tests d'intégration. Sous UNIX : faire attention à la manière de passer les '&' de l'url, quand vous utilisez la méthode GET. Il faut souvent les "échapper" au moyen du caractère "\", sinon, ils ne passent pas et cela donne une erreur.

5 Output du script : Le script renvoie l output XML suivant : <?xml version="1.0"?> <transaction> <sms> <stamp> </stamp> <status>200</status> <statusdetails>ok</statusdetails> <price>10</price> <creditsleft>256</creditsleft> </sms> </transaction> stamp : un identifiant permettant notamment de recevoir les accuses de réception. status : 200 si OK, sinon voir liste des codes d erreur. statusdetails : explication du code d erreur. price : coût d envoi du message en crédits (vaut 0 en cas d erreur). creditsleft : crédits restant sur votre compte après cet envoi. Requête de notification pour les accusés de réception : En cas de requête pour les accusés de réception, nos serveurs font une requête de type POST sur l url spécifiée lors de votre envoi (ou sur l url par défaut le cas échéant) comprenant les paramètres suivants : sms_stamp : reprend le stamp renvoyé dans la réponse XML de notre script. sms_destination : reprend le numéro de GSM de destination sms_result : indique le résultat de l envoi sms_gmdate : indique la date et l heure (GMT) en format yyyy-mm-dd hh:mm:ss Le résultat de l envoi est «delivered» si le message a été reçu par le destinataire. Exemple : Vous spécifiez lors de l envoi de votre SMS que : NOTIF=http%3A%2F%2Fwww.yourdomain.com%2Fscript.php Alors, dès réception de l accusé (ou de l erreur), notre serveur fera une requête POST vers Cette requête comprendra les variables précisées dans la liste ci-dessus. Remarque : comme vous le voyez ici, il faut «urlencoder» votre url pour le paramètre NOTIF. Beaucoup de langages (PHP, ASP, ) possèdent une fonction urlencode à cet usage.

6 Codes d erreur : 98 Not enough credits left 100 Created but not sent 200 Sent OK 300 Connection error 301 No compatible gateway 400 Unknown class 401 Invalid parameters 402 Invalid credentials 403 Invalid destination number 408 Other error 500 Internal error