Endpoints
Первое, что вы должны знать, это куда направить Ваш API запрос. My-Cool-SMS принимает GET, POST и JSON запросы через порт 80 или SSL через порт 443. Вы можете подключиться к следующим адресам соответственно.HTTP
API endpoint для HTTP запросов:
http://www.my-cool-sms.com/api-socket.php
HTTPS
Если Вам требуется безопасное соединение вы можете использовать API с помощью SSL, 443 порт. API endpoint для HTTPS запросов:
https://www.my-cool-sms.com/api-socket.php
API компоненты
У My-Cool-SMS есть два вида компонентов. Фунции и callbacks.Функции
Функции используются для запроса отправки сообщений SMS, поиска Вашего баланса или получения отчетов о доставке. Функция может быть запущена с помощью структуры HTTP запроса, как описано ниже.Callbacks
Callback (функция обратного выызова) - это запрос, посланный от My-Cool-SMS на ваш сервер. Функция callback запускается в режиме реального времени, когда такие имеют место такие события, как получение SMS или новый отчет о доставке и передается обратно на URL сервера для обработки.Структура запроса
Вы можете отправлять запросы через HTTP POST, GET или JSON. Хотя My-Cool-SMS не остановливает Вас от использования POST или GET, мы настоятельно рекомендуем использовать JSON запросы. JSON это легкий формат обмена данными, который легко читается и пишется и легко анализируется и создается для языка программирования вашего выбора. Прежде всего, JSON очень устойчив при отправке Unicode SMS сообщений и не требует для реализации сложного кодирования и декодирования UCS2. Если Вам когда-либо приходилось работать с Unicode, UCS2 или GSM7 кодированием и декодированием кросс-сервера, вы наверняка знаете, что это счастье, когда есть возможность этого избежать. Вы можете узнать больше о JSON здесь.Реквизиты входа в систему и переключатели функций
Запрос к My-Cool-SMS API должен всегда содержать Ваше имя пользователя, пароль и переключатель функций, который говорит API, что вы хотите сделать.JSON
Давайте посмотрим на пример JSON, который вы будете использовать при поиске Вашего баланса:
{
"username":"xxx",
"password":"yyy",
"function":"getBalance"
}
POST/GET
Один и тот же запрос с POST и GET будет выглядеть так:
username=xxx&password=yyyy&function=getBalance
Обязательные и произвольные параметры
В то время как имя пользователя, пароль и параметры функций требуются всегда, каждая функция может иметь обязательные и необязательные параметры, которые, возможно, также будет нужно указывать. Запрашивая отчет о доставке, например, укажите для какого SMS Вы его запрашиваете. Для этого вы просто добавляете дополнительный параметр, в данном случае "ID".
{
"username":"xxx",
"password":"yyy",
"function":"getDeliveryReport",
"id":"ce184cc0a6d1714d1ac763f4fe89f521"
}
Структура ответа
API запрос всегда возвращает объект JSON. Каждый ответ содержит параметр успеха, который указывает, может ли запрос быть обработан успешно или нет. Вы должны обрабатывать ответ в соответствии с тем, как настроен параметр, "верно" или "неверно" .Успешный ответ
Успешный запрос к функции getDeliveryReport вернет объект JSON, вроде следующего:
{
"success":true,
"smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
"status":"SMS_STATUS_DELIVERED"
}
Неправильный ответ
Скажем, у вас есть опечатка в параметре пароля. В этом случае API вернет объект JSON со следующей структурой:
{
"success":false,
"errorcode":"101",
"description":"Login Failed. Wrong Username or Password."
}
Обработка ответов
Прочитайте ответы
Ответ API всегда отправляется в формате JSON. Все, что нужно сделать это преобразовать данные ответа в объект. Это достаточно просто, так как прктически каждый язык программирования предлагает собственные методы как это сделать. Чтобы найти больше информации о JSON для языка программирования вашего выбора: прокрутите немного вниз эту страницу. Вам нужно сделать примерно следующее с PHP, чтобы обработать ответ 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);
}
Обработка callbacks
Прочитайте вводные данные
Callbacks не сильно отличаются от ответов на функции, и вы можете конвертировать их в объект, как указано выше. Одинственное, что Вам нужно будет знать, это, как работать с HTTP Raw Request Input. Callback не отправляется ни через GET, ни через POST, а только, как HTTP Raw Data, о чем вы можете прочитать далее. Вам нужно сделать примерно следующее с PHP, чтобы обработать callback запрос:
//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
Функция: sendSms
Давайте посмотрим, как фактически выглядит код для отправки SMS. Вам нужно использовать API с наименьшим количетвом трок кода, насколько это возможно. Итак, как бы это работало?
<?php
$oMyCoolSMS = new MyCoolSMS();
$oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');
?>
Стартовый комплект PHP SMS
Загрузить стартовый комплект PHP SMS
Стартовый комплект содержит готовые к использованию кода для вызова 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,
));
}
}
?>
<?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);
}
?>
