Nederlands

Application Programming Interface (SMS API)

Eindpunten

Wat je ten eerste moet weten, is waarnaartoe je jouw API verzoek moet sturen. My-Cool-SMS accepteert GET, POST en JSON verzoeken via port 80 of SSL op port 443. Je kunt respectievelijk verbinding maken met de volgende URL's.

HTTP

Het API eindpunt voor HTTP verzoeken is:
http://www.my-cool-sms.com/api-socket.php

HTTPS

Indien je een beveiligde verbinding benodigt, kun je de API via SSL op port 443 gebruiken.
Het API eindpunt voor HTTPS verzoeken is:
https://www.my-cool-sms.com/api-socket.php

API Componenten

My-Cool-SMS heeft twee soorten van API componenten. Functies en Callbacks.

Functies

Functies worden gerbuikt om bijv. een SMS tekstbericht verzending te verzoeken, jouw saldo te bekijken of om afleveringsrapporten op te halen. Een functie kan opgeroepen worden door een HTTP verzoek structuur zoals beneden geschetst te gerbuiken.

Callbacks

Callbacks zijn doorstuur verzoeken verstuurd door My-Cool-SMS naar jouw server. Een callback wordt in real-time opgeroepen zodra iets gebeurt zoals een SMS of een nieuwe afleveringsrapport ontvangen. De callback wordt voor verwerking geretourneerd naar een URL op jouw server.

Verzoek Structuur

Je kunt verzoeken via HTTP POST, GET of JSON sturen. Hoewel My-Cool-SMS jou tegen het gebruiken van POST of GET niet tegenhoudt, is het ten zeerste aanbevolen JSON verzoeken te gebruiken. JSON is een lichte gegevens-uitwisseling formaat welke makelijk voor mensen te lezen en te schrijven en makkelijk te ontleden en te genereren voor de programmeertaal van uw keuze is.
JSON is bovendien zeer robuust bij het versturen van Unicode SMS tekstberichten en vereist geen invoeren van ingewikkelde UCS2 codeer- en decodeerprocedures. Als je ooit met en cross-server Unicode moest werken, is het een zegen al bekende UCS2 or GSM7 codering en decodering te voorkomen. Meer informatie over JSON hier.

Inloggegevens en Functie Selectors

Een verzoek aan de My-Cool-SMS API moet altijd jouw gebruikersnaam, wachtwoord en een functie selector bevatten, die aan de API doorgeeft wat je wil doen.

JSON

Laten we eens kijken naar een JSON voorbeeld dat je zou gebruiken bij het bekijken van jouw saldo:
{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

POST/GET

Hetzelfde verzoek met POST of GET zou als volgend eruitzien:
username=xxx&password=yyyy&function=getBalance

Verplichte en Optionele Parameters

De gebruikersnaam, het wachtwoord en de functie parameters zijn altijd verplicht, elke functie kan echter specifieke verplichte en optionele parameters hebben, van welke de functie moet voorzien zijn.
Bij het ophalen van een afleveringsrapport bijvoorbeeld, ga je ook willen specificeren voor welke SMS je een afleveringsrapport wil. Je doet dat indien je gewoon een additionele parameter toevoegt, in dit geval "id".
{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Respons Structuur

Een API verzoek retourneerd altijd een JSON object. Elke respons bevat een succes parameter welke aangeeft of het verzoek met succes kon worden verwerkt of niet. Afhankelijk daarvan of deze parameter true of false is, ga je de respons op verschillende manier willen behandelen.

Gelukte Respons

Een met succes gestelde verzoek aan de getDeliveryReport functie, gaat een JSON object retourneren zoals het volgende:
{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}
Elke functie heeft verschillende respons parameters. Je kunt de gedetailleerde specificatie hier bekijken.

Fout Respons

Aangenomen, je hebt een typo in de wachtwoord parameter gemaakt. In dit geval gaat de API een JSON object met de volgende structuur retourneren:
{
    "success":false,
    "errorcode":"101",
    "description":"Login Failed. Wrong Username or Password."
}
Je kunt altijd op een driecijferig foutcode rekenen, alsmede een beschrijving die je helpt het teruggestuurd moeten worden probleem vast te stellen, als de succes parameter in de respons false is.

Omgang Responsen

Read Respons

De API respons wordt altijd in JSON formaat verstuurd. Alles wat je moet doen is de responsgegevens in een object te converteren. Dat is echt eenvoudig, omdat vrijwel elke programmeertaal natieve methoden om precies dat te doen aanbiedt.
Om meer informatie over JSON voor de programmeertaal van jouw keuze te vinden, ga naar deze pagina en scroll een beetje naar beneden.
In PHP ga je iets van de volgende rijen doen om de API respons te verwerken:
// 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);
}

Omgang Callbacks

Read Input

Callbacks verschillen niet zo zeer van functie responsen en je kunt ze in een object converteren precies zoals boven. Wat je wel moet weten is hoe men de HTTP Raw Request Input inneemt. De callback wordt ook niet via GET of POST verzonden maar als HTTP Raw Data welke je kunt lezen zoals volgend geschetst.
In PHP ga je iets van de volgende rijen doen om de callback verzoek te verwerken:
//capture the raw data input stream
$oCallback = json_decode(file_get_contents("php://input"));

//$oCallback is now an object.
print_r($oCallback);
In Java is het bijna hetzelfde:
InputStream body = request.getInputStream();
Weet wel dat welke programmeertal je ook gebruikt, je kunt de input alleen maar een keer lezen. Sla de kern ergens anders op.

PHP Voorbeelden

Functie: sendSms

Laat ons even bekijken hoe een eigenlijke code om een SMS te sturen eruitziet. Je wil zeker de API zo implementeren, dat je zo weinig mogelijk lijnen van code gebruikt. Dus, wat denk je van het volgende?
<?php

$oMyCoolSMS = new MyCoolSMS();
$oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');

?>
Keurig, hoor? Als het dat is wat je nodig hebt, download gewoon de PHP SMS Starter Kit, bekijk even de commentaren in de code, run send-sms.php en je bent klaar te starten.

PHP SMS Starter Kit

Download PHP SMS Starter Kit
De starter kit bevat good-to-go code om API functies op te roepen en callbacks te hanteren.

Voor Techies

Ben je een beetje meer tech-savvy, misschien wil je dan even een eigenlijke klas welke verzoeken hanteert bekijken:
<?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,
        ));
        
    }

}

?>
Sla de boven vermelde code als MyCoolSMS.class.php bestand op en begin het als volgend te gebruiken:
<?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);
}

?>

Je bent klaar om te starten!

Laat ons nu even de API functie en callback documentatie bekijken.
Hebben we iets vergeten? Heb je vragen? Heb je een tip voor ons of zullen we hier iets toevoegen? Indien ja, laat ons weten!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Polski
Português
Руccкий
繁体中文