繁体中文

應用程式編輯程式介面(SMS API)

端點

第一件您必須知道的事是您要將API請求發送至何處. My-Cool-SMS接受經由 port 80 或是 SSL on port 443的GET, POST和JSON請求. 您可以分別連結至以下的URL

HTTP

針對HTTP請求的API端點為:
http://www.my-cool-sms.com/api-socket.php

HTTPS

您可以經由SSL on port 443使用API來要求一個安全的連接
針對HTTP請求的API端點為:
https://www.my-cool-sms.com/api-socket.php

API組件

My-Cool-SMS有2種API組件. 功能和回調

功能

功能是來要求一個簡訊的發送,查詢餘額或是取得傳送報告. 可以藉由使用以下概述的HTTP請求架構來操作一個功能

回調

Callbacks are push requests sent from My-Cool-SMS to your server. A callback is invoked in real-time when events like receiving an SMS or a new delivery report happen and is posted back to an URL your server for processing.

請求架構

You can send requests via HTTP POST, GET or JSON. Although My-Cool-SMS won't stop you from using POST or GET it is highly recommended to use JSON requests. JSON is a light-weight data-interchange format that is easy for humans to read and write and easy to parse and generate for the programming language of your choice.
Above all JSON is very robust when sending Unicode SMS text messages and doesn't require you to implement complex UCS2 encoding and decoding procedures. If you ever had to work with cross-server Unicode, UCS2 or GSM7 encodings and decoding you might know already that being able to avoid it is a blessing. You can find out more about JSON here.

登入憑據和功能選擇器

一個對於 My-Cool-SMS API 的請求必須 總是 包含你的使用者名稱, 密碼 和一個告知API你打算做什麼的 功能選擇器

JSON

讓我們一起來看看一個當查詢餘額時會用到的JSON範例
{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

POST/GET

當POST 或 GET的時候, 相同的請求會呈現如下:
username=xxx&password=yyyy&function=getBalance

指令和自選參數

除了使用者名稱,密碼和功能參數是必要的,每個功能可能會有特定的指令和可能需要提供的自選參數
例如當取得一個傳送報告的時候, 您也要指定您要的是哪一則簡訊的傳送報告. 您只要額外再新增一個"id"的參數
{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

回應架構

一個API請求總是會回傳一個JSON物件. 每一個回應包含了一個顯示請求是否成功被處理成功參數. 視這個參數是否為true還是false, 您可能需要做不同的處理

成功回應

一個針對getDeliveryReport功能的成功請求可能會回傳一個類似以下的JSON物件:
{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}
每一個功能有不同的回應參數. 您可以檢視詳細規格 here

錯誤回應

假設您在密碼參數中有一個錯字, API將會回傳一個JSON物件包含以下架構:
{
    "success":false,
    "errorcode":"101",
    "description":"Login Failed. Wrong Username or Password."
}
您可以總是得到一組三位數的錯誤代碼和錯誤說明,當成功參數的回應為false時,那可以幫助您找出問題

處理回應

讀回應

API回應都是以JSON格式發送.您只需要轉換回應資料為物件. 那很簡單,因為幾乎每一種程式語言都能提供特定的方法來完成
欲了解更多關於您選擇的JSON的編程語言,請至此頁並將頁面往下拉一點
在PHP裡,
// 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);
}

處理回調

讀輸入

回調和功能回應沒有太大的不同,並且您可以將它們用以上同樣的方式轉換為物件. 但有件必須注意的事是如何捉取 HTTP Raw請求輸入. 回調不是經由GET和POST發送的,但就如同您下一個會讀到的HTTP Raw Data概述
In PHP you'd do something amongst the lines of the following to process the callback request:
//capture the raw data input stream
$oCallback = json_decode(file_get_contents("php://input"));

//$oCallback is now an object.
print_r($oCallback);
這和在Java裡是幾乎相同的:
InputStream body = request.getInputStream();
請注意無論任何您使用的編程語言,您只能讀輸入一次. 將內文儲存至其他地方做處理

PHP範例

功能: sendSms

讓我們來看看實際的代碼去發送一則簡訊可能會看起來如何. 您大概希望儘可能的使用最少的代碼列來執行API. 所以,以下對您的幫助有多少?
<?php

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

?>
很整齊嗎? 若那是你全部所需的,只要簡單地下載PHP簡訊入門工具,查看一下代碼中的意見,執行send-sms.php,您就準備好了!

PHP簡訊入門工具

下載PHP簡訊入門工具
入門工具包含了good-to-go 代碼來使用API功能和處理回調

針對技術高手

如果您是一個更高的科技知識份子,您可能會希望看看處理請求的實際階級
<?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,
        ));
        
    }

}

?>
儲存以下的代碼至MyCoolSMS.class.php的檔案夾並開始像這樣來使用:
<?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);
}

?>

您可以開始了!

現在讓我們來看看API功能和回調使用說明
我們有漏掉些什麼嗎? 您有任何問題嗎? 您有任何建議或是還有其他我們該增加的? 如果有, 請與我們聯繫!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Nederlands
Polski
Português
Руccкий