Français

Application Programming Interface (SMS API)

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"
}
Chaque fonction a des paramètres de réponse différents. Vous pouvez voir les détails here.

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."
}
Vous pouvez toujours compter sur un code d'erreur à trois chiffres et une description pour vous aider à localiser le problème. Ceci vous sera renvoyé si le paramètre de succès dans la réponse est faux.

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);
En Java c'est à peu près la même chose :
InputStream body = request.getInputStream();
Veuillez noter que quel que soit le langage de programmation que vous utilisez vous pouvez seulement lire cette entrée une fois. Conservez le corps du message autre part pour traiter les informations.

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!');

?>
Pas de problème ? Si c'est tout ce que vous désirez, télécharger simplement le Kit de Démarrage de SMS PHP, jetez un oeil aux commentaires dans le code, exécutez send-sms.php et vous êtes parti !

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,
        ));
        
    }

}

?>
Sauver le code au dessus dans un fichier appelé MyCoolSMS.class.php et commencer à l'utiliser comme ceci :
<?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);
}

?>

Vous pouvez y aller !

Jetez un coup d'oeil à la fonction API et à la documentation de fonction de rappel maintenant.
Avons-nous manqué quelque chose ? Avez-vous des questions ? Vous avez des conseils ou quelque chose que vous voulez ajouter ici ? Dans ce cas, faites nous savoir!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Nederlands
Polski
Português
Руccкий
繁体中文