Endpoints
La première chose que vous devez savoir est où envoyer votre requête API. My-Cool-SMS accepte les requêtes GET, POST et JSON via port 80 ou via SSL port 443. Vous pouvez vous connecter respectivement aux URLs suivantes.HTTP
Le point d'arrivée API pour les requêtes HTTP est :
http://www.my-cool-sms.com/api-socket.php
HTTPS
Si vous avez besoin d'une connexion sécurisée vous pouvez utiliser l'API via SSL sur le port 443. Le point d'arrivée API pour les requêtes HTTP est :
https://www.my-cool-sms.com/api-socket.php
API Components
My-Cool-SMS possède deux constituants API. Fonctions et fonctions de rappel.Fonctions
Fonctions est utilisé pour, i.e. demander l'envoi d'un message texte SMS, vérifier votre solde ou obtenir des rapports d'envoi. Une fonction peut-être invoquée en faisant appel à la requête de structure HTTP comme expliqué au dessous.Fonctions de rappel
Fonctions de rappel sont des requêtes push envoyées depuis My-Cool-SMS vers votre serveur. Une fonction de rappel est invoquée en temps réel lors d'événements comme la réception d'un SMS ou d'un nouveau rapport d'envoi et est renvoyée vers une URL de votre serveur pour traitement.Request Structure
Vous pouvez envoyer des requêtes via HTTP POST, GET ou JSON. Même si My-Cool-SMS ne vous empêche pas d'employer POST ou GET il est vivement recommandé d'utiliser les requêtes JSON. JSON est un format léger d'échange de données, facile à lire et écrire pour les humains et facile à analyser et à générer pour le langage de programmation de votre choix. Avant tout JSON est très fiable lors de l'envoi de messages texte SMS en Unicode et ne requiert pas que vous implémentiez des procédures complexes d'encodage ou de décodage UCS2. Si vous avez déjà travaillé avec les encodages et décodages Unicode, UCS2 ou GSM7 cross-serveurs, vous devez déjà savoir à quel point il est préférable de s'épargner cela. Vous pouvez en savoir plus sur JSON ici.Justificatifs pour la connexion et sélecteurs de fonction
Une requête vers l'API de My-Cool-SMS doit toujours contenir vosnom d'utilisateur, mot de passe et un sélecteur de fonction afin de dire à l'API ce que vous voulez faire.JSON
Let's have a look at a JSON example that you would use when looking up your balance:
{
"username":"xxx",
"password":"yyy",
"function":"getBalance"
}
POST/GET
With POST or GET the same request would look as follows:
username=xxx&password=yyyy&function=getBalance
Paramètres obligatoires et optionnels
Même si le nom d'utilisateur, le mot de passe et les paramètres de fonction sont toujours requis, chaque fonction peut avoir des paramètres spécifiques, obligatoires et optionnels; qu'il est peut-être nécessaire de fournir. En demandant un rapport d'envoi par exemple, vous voudrez aussi pouvoir spécifier pour quel SMS vous désirez ce rapport d'envoi. Il suffit d'ajouter un paramètre supplémentaire, en ce cas "id".
{
"username":"xxx",
"password":"yyy",
"function":"getDeliveryReport",
"id":"ce184cc0a6d1714d1ac763f4fe89f521"
}
Response Structure
Une requête API renvoie toujours un objet JSON. Chaque réponse contient un paramètre de succès qui indique si la requête peut être traitée avec succès ou non. Selon que le paramètre est vrai ou faux vous aurez besoin de traiter la réponse différemment.Réponse de succès
Une requête réussie vers la fonction obtenir un rapport d'envoi renverra un objet JSON comme le suivant :
{
"success":true,
"smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
"status":"SMS_STATUS_DELIVERED"
}
Réponse d'erreur
Disons que vous avez une coquille dans le paramètre mots de passe. Dans ce cas l'API renverra un objet JSON avec la structuration suivante :
{
"success":false,
"errorcode":"101",
"description":"Login Failed. Wrong Username or Password."
}
Handling Responses
Lire la réponse
La réponse API est toujours envoyée en format JSON. Il vous suffit de convertir la donnée de réponse en objet. C'est très simple puisque pratiquement tous les langages de programmation offrent des méthodes natives à cet effet. Afin de trouver plus d'informations sur JSON pour le langage de programmation de votre choix allez sur cette page et déroulez un peu vers le bas. En PHP vous intégreriez quelque chose aux lignes suivantes pour traiter la réponse API :
// Let's assume you sent a getDeliveryReport request and
// the HTTP response is stored in $response...
// Now simply convert the response into a PHP object
$oResponse = json_decode($response);
//$oResponse is now an object
if($oResponse->success) {
//Great. It worked!
echo($oResponse->smsid);
echo($oResponse->status);
} else {
//Oops. something went wrong.
echo($oResponse->errorcode);
echo($oResponse->description);
}
Handling Callbacks
Lire l'entrée
Les fonctions de rappel ne sont pas très différents des fonctions de réponses et vous pouvez les convertir en objet exactement de la même façon que décrit au dessus. Vous devez cependant être capable de saisir l'input de requête brute HTTP. La fonction de rappel n'est pas renvoyée via GET ou POST mais en tant que donnée brute HTTP comme vous pouvez le lire à la suite. En PHP vous intégreriez quelque chose aux lignes suivantes pour traiter la réponse API :
//capture the raw data input stream
$oCallback = json_decode(file_get_contents("php://input"));
//$oCallback is now an object.
print_r($oCallback);
InputStream body = request.getInputStream();
PHP Examples
Fonction: sendSms
Regardons de quoi a l'air un véritable code pour envoyer un SMS. Vous préférez probablement implémenter l'API en utilisant aussi peu de lignes de code que possible. Ainsi, comment allez-vous vous débrouiller avec le suivant ?
<?php
$oMyCoolSMS = new MyCoolSMS();
$oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');
?>
PHP SMS Starter Kit
Télécharger le Kit de Démarrage de SMS PHP
Le Kit de Démarrage contient des codes pour invoquer les fonctions API et gérer les fonctions de rappel.
Pour techniciens
Si vous êtes un peu branché technique vous voulez peut-être jeter un oeil à la catégorie qui gérer vraiment la requête :
<?php
class MyCoolSMS {
function __construct() {
$this->username = 'xxx'; //your username here...
$this->password = 'yyy'; //your password here...
$this->endpoint = 'http://www.my-cool-sms.com/api-socket.php';
}
public function sendSms($number, $message, $senderid='MyNumber') {
return($this->request(json_encode(array(
'username' => $this->username,
'password' => $this->password,
'function' => 'sendSms',
'number' => $number,
'senderid' => $senderid,
'message' => $message
))));
}
public function getDeliveryReport() {}
public function getBalance() {}
//add more functions as you please...
private function request($oRequest) {
$oCurl = curl_init($this->endpoint);
curl_setopt($oCurl, CURLOPT_POST, 1);
curl_setopt($oCurl, CURLOPT_POSTFIELDS, $oRequest);
curl_setopt($oCurl, CURLOPT_RETURNTRANSFER, 1);
if(curl_errno($oCurl) == 0) {
$oResponse = json_decode(curl_exec($oCurl));
if(!is_object($oResponse)) {
$oResponse = $this->getError('001', 'Bad Response');
}
} else {
$oResponse = $this->getError(curl_error($oCurl));
}
curl_close($oCurl);
return $oResponse;
}
private function getError($error = '000', $description = NULL) {
return json_encode(array(
'success' => false,
'error' => $error,
'description' => $description,
));
}
}
?>
<?php
require_once('MyCoolSMS.class.php');
$oMyCoolSMS = new MyCoolSMS();
$oResponse = $oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');
if($oResponse->success) {
//Great, it worked!
print_r($oResponse);
} else {
//Oops, Something went wrong...
print_r($oResponse);
}
?>
