Polski

Application Programming Interface (SMS API)

Punkty końcowe

Pierwszą rzeczą, którą musisz wiedzieć, to gdzie wysłać wniosek API. My-Cool-SMS akceptuje GET, POST i żądania JSON przez port 80 lub SSL na port 443. Można podłączyć odpowiednio do następujących adresów URL.

HTTP

Punkt końcowy API dla żądań HTTP to:
http://www.my-cool-sms.com/api-socket.php

HTTPS

Jeśli potrzebujesz bezpiecznego połączenia, możesz użyć API za pomocą SSL na port 443.
Punkt końcowy API dla żądań HTTPS to:
https://www.my-cool-sms.com/api-socket.php

Składniki API

My-Cool-SMS posiada dwa rodzaje składników API. Funkcje oraz Wywołania zwrotne.

Funkcje

Funkcje są używane np. po to, aby zażądać wysłanie wiadomości tekstowej SMS, sprawdzić Twoje saldo pozostałych środków lub aby pobrać raporty doręczenia. Funkcja może być wywołana, używając strukturę żądania HTTP, tak jak zakreślono poniżej.

Wywołania zwrotne

Wywołania zwrotne to żądania przesyłania wysyłane przez My-Cool-SMS na Twój serwer. Wywołanie zwrotne jest wywoływane w czasie rzeczywistym, gdy otrzymujesz wiadomość SMS lub nowy raport doręczenia i jest wysyłane spowrotem na adres URL na Twoim serwerze, aby zostało przetworzone.

Struktura Żądania

Możesz wysyłać żądania za pomocą HTTP POST, GET lub JSON. Mimo że My-Cool-SMS nie powstrzyma Ciebie przed użyciem POST lub GET, używanie żądań JSON jest wysoce zalecane. JSON jest lekkim formatem wymiany danych, który jest łatwy do czytania i pisania przez ludzii oraz łatwy do analizowania i generowania dla wybranego języka programowania.
Ponadto, JSON jest bardzo odporny, gdy wysyła się wiadomość tekstową SMS w postaci znaków Unicode i nie wymaga wdrażania skomplikowanych procedur kodowania i dekodowania UCS2. Jeśli kiedykolwiek wykorzystywałeś do pracy cross-serwer Unicode, ​​kodowanie i dekodowanie UCS2 lub GSM7, to wiesz już pewnie, że możliwość uniknięcia powyższych czynności jest prawdziwym błogosławieństwem. Możesz się dowiedzieć więcej o JSON tu.

Identyfikatory Logowania oraz Selektory Funkcji

Żądanie wysłane do API My-Cool-SMS musi zawsze zawierać Twoje imię, hasło oraz selektor funkcji który powie API, co ty chcesz uczynić.

JSON

Spójrzmy na przykład JSON, który byś użył, gdybyś chciał sprawdzić swoje saldo pozostałych środków:
{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

POST/GET

Za pomocą POST lub GET to samo żądanie by wyglądało następująco:
username=xxx&password=yyyy&function=getBalance

Obligatoryjne i Opcjonalne Parametry

Podczas gdy login, hasło i parametry funkcji są zawsze wymagane, każda funkcja może mieć szczególne parametry obligatoryjne i opcjonalne, które może trzeba by było również wprowadzić.
Gdy np. pobieramy raport doręczenia, wtedy również chcemy sprecyzować, dla której wiadomości SMS chcemy owy raport doręczenia. Czynimy to poprzez proste dodanie dodatkowego parametru, w tym przypadku "id".
{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Struktura Odpowiedzi

Wniosek API zawsze zwraca obiekt JSON. Każda odpowiedź zawiera parametr powodzenia, który wskazuje, czy wniosek mógł być przetworzony z powodzeniem czy nie. W zależności od tego czy ten parametr jest prawdziwy lub fałszywy, będziesz traktował odpowiedzi w różny sposób.

Odpowiedź Powodzenia

Udane żądanie funkcji getDeliveryReport zwróciłoby obiekt JSON taki, jak następujący :
{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}
Każda funkcja ma różne parametry odpowiedzi. Możesz zobaczyć szczegółową specyfikację tu.

Odpowiedź Błędu

Załóżmy, że masz literówkę w parametrze hasła. W tym przypadku API zwróci obiekt JSON o następującej strukturze:
{
    "success":false,
    "errorcode":"101",
    "description":"Login Failed. Wrong Username or Password."
}
Zawsze możesz spodziewać się trzycyfrowego kodu błędu i opisu pomagającego zlokalizować problem, który musi zostać zwrócony, gdy parametr powodzenia w odpowiedzi jest fałszywy.

Obsługa Odpowiedzi

Czytaj Odpowiedź

Odpowiedź API zawsze wysyłana jest w formacie JSON. Jedyne co musisz zrobić z tym, to skonwertować dane odpowiedzi w obiekt. To jest naprawdę proste, ponieważ praktycznie każdy język programowania oferuje alternatywne metody, aby dokładnie to samo zrobić.
Aby uzyskać więcej informacji o JSON dla wybranego języka programowania, idź na tą stronę i zjedź kursorem trochę na dół.
W PHP zrobisz coś z następujących wierszy, aby przetworzyć odpowiedź 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);
}

Obsługa Wywołań Zwrotnych

Czytaj Dane Wejściowe

Wywołania zwrotne nie różnią się znacząco od odpowiedzi funkcji i mogą skonwertować je w obiekt w taki sam sposób jak powyżej. Musisz jednak wiedzieć o tym, w jaki sposób przechwycić HTTP Raw Request Input. Wywołanie zwrotne nie jest wtedy wysyłane za pomocą GET czy POST, lecz jako HTTP Raw Data, które możesz czytać tak, jak następująco zarysowano.
W PHP zrobisz coś z następujących wierszy, aby przetworzyć żądanie wywołania zwrotnego:
//capture the raw data input stream
$oCallback = json_decode(file_get_contents("php://input"));

//$oCallback is now an object.
print_r($oCallback);
W języku JAVA wygląda to prawie tak samo:
InputStream body = request.getInputStream();
Należy pamiętać, że jakikolwiek język programowania używasz, dane wejściowe możesz przeczytać tylko raz. Zapisz treść gdzie indziej w celu przetworzenia.

Przykłady PHP

Funkcja: sendSms

Zobaczmy, jak może wyglądać właściwy kod do wysyłania wiadomości SMS. Prawdopodobnie chcesz wdrożyć API przy jak najmniejszej ilości linii kodu. Zatem jak odpowiada Tobie następujące?
<?php

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

?>
Całkiem nieźle? Jeżeli to jest wszystko, co potrzebujesz, po prostu ściągnij Zestaw Startowy PHP SMS, spójrz na komentarze w kodzie, uruchom send-sms.php i możesz zaczynać.

Zestaw Startowy PHP SMS

Ściągnij Zestaw Startowy PHP SMS
Zestaw startowy zawiera gotowe do użycia kody do wywoływania funkcji API oraz obsługiwania wywołań zwrotnych.

Dla Techników

Jeżeli jesteś trochę bardziej techniczny, warto spojrzeć na właściwą klasę, która obsługuje żądanie:
<?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,
        ));
        
    }

}

?>
Zapisz powyższy kod jako plik o nazwie MyCoolSMS.class.php i zacznij używać go w ten oto sposób:
<?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);
}

?>

Możesz zaczynać!

Spójrzmy teraz na funkcje API oraz dokumentację wywołań zwrotnych.
Czy o czymś zapomnieliśmy? Masz jakieś pytania? Chcesz się podzielić dobrą radą czy powiedzieć nam, że czegoś tu brakuje? Jeżeli tak, daj nam znać!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Nederlands
Português
Руccкий
繁体中文