СМС шлюз, підключення SMS через API

Ви можете безкоштовно підключитися до нашого смс-шлюзу, активація послуги не потрібна. СМС-шлюз дозволяє автоматизувати розсилку sms повідомлень і вбудувати сервіс в будь-який проект.

SMPP-шлюз

Даний шлюз відповідає всім параметрам протоколу SMPP v3.4. Для тестування нашого шлюзу необхідно зв'язатися з адміністрацією.


HTTP-шлюз

Спілкування з сервісом здійснюється за допомогою відправки HTTP-запитів на задану адресу сервісу по протоколу HTTP методами GET/POST, перевірка типу контенту та валідність кодування не здійснюється.

Кожний запит може складатися з повідомлень, що відправляються, і (або) запитів для отримання статусів.

Відправка повідомлень

    Адреса служби:
  • https://gate.smsclub.mobi/token/

Відправлення повідомлень здійснюється за допомогою завдання нижчеописаних параметрів. Параметри для обох методів однакові:

  • username – логін облікового запису користувача;
  • token – токен облікового запису користувача (можливо знайти в профілі);
  • from – альфа-ім'я, від якого йде відправка (11 англійських символів, цифри, пробіли);
  • to – список адресатів, розділені «;», після останнього номера адресата символ «;» не ставиться;
  • text – повідомлення в кодуванні Windows-1251;
  • lifetime – установка терміну життя СМС, який вказується в хвилинах.

Важливо! Обмеження:

  • для друкованих символів (ASCII 0x01-0x7E) максимальна довжина повідомлення: 1071 символ;
  • для символів, що виходять за рамки даного діапазону максимальна довжина повідомлення: 469.

Отримання відповіді

На отриманий запит сервіс повертає або україномовний текст помилки, або текст такого вигляду:

=IDS START=
000002
000003
=IDS END=
=IDS START=, =IDS END= - між даними константами розміщений список ID повідомлень/частин повідомлень, кожний ID з нового рядка (розділяється тегом <br/>).

Список формується в порядку, відповідно до списку адресатів. Для повідомлення, що складається з декількох частин, список ID формується в порядку відправки частин повідомлення одному адресату, далі - список ID в порядку відправки частин повідомлення другого адресату і т. д.

Запит статусів повідомлень

  • Метод GET, POST: https://gate.smsclub.mobi/http/state.php

Статуси повідомлень містять інформацію про поточний стан повідомлення, регулярно оновлюються і можуть бути запитані користувачем у будь-який час. Запит статусів здійснюється за допомогою нижчеописаних параметрів. Параметри для обох методів однакові:

  • username – логін облікового запису користувача;
  • token – токен облікового запису користувача;
  • smscid – список ID, розділених «;», після останнього ID символ «;» не ставиться.

На отриманий запит сервіс повертає або україномовний текст помилки, або текст такого вигляду:

=IDS START=
ID_1: STATE
ID_2: STATE
…
ID_N: STATE
=IDS END=

=IDS START=, =IDS END= - між даними константами заключений список запитуваних ID повідомлень/частин повідомлень і відповідний їм статус (після символу «:»); кожен ID з нового рядка (розділяється тегом <br/>).

Коди статусів повідомлень

Дані коди використовуються при поверненні статусів повідомлень:

  • ENROUTE – повідомлення прийнято;
  • DELIVRD – повідомлення доставлено;
  • EXPIRED – закінчився термін зберігання повідомлення;
  • UNDELIV – повідомлення не може бути доставлено;
  • REJECTD - відхилено.

Приклад GET-запиту відправки повідомлення:

https://gate.smsclub.mobi/token/?username=user&token=user_token&from=SMS CLUB&to=0675126767&text=Hello from SMS CLUB

Приклад GET-запиту на отримання звіту про доставку:

https://gate.smsclub.mobi/token/state.php?username=user&token=user_token&smscid=000000

Перевірка балансу онлайн

Даний метод дозволяє перевірити поточний баланс і величину кредиту користувача.

Приклад GET-запиту перевірки балансу:

https://gate.smsclub.mobi/token/getbalance.php?username=user&token=user_token

Приклад коду перевірки балансу:

<?php
    $ch = curl_init();
    $login = '380501234567';
    $token = '123456';
    $url = "https://gate.smsclub.mobi/http/getbalance.php?username=$login&token=$token";
    //можно и через POST
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_URL,$url);
    $result = curl_exec($ch);
    echo $result;
?>


XML-шлюз

Спілкування з сервісом здійснюється за допомогою відправки XML запитів в кодуванні UTF-8 на задану адресу сервісу по протоколу HTTP методом POST, у змінній xmlrequest перевірка типу контенту та валідність кодування не здійснюється.

Кожний запит може складатися з повідомлень, що відправляються, і (або) запитів для отримання статусів.

Відправлення повідомлень (поодиноких та масових)

Адреса служби:
https://gate.smsclub.mobi/xml/

Відправлення повідомлень здійснюється за допомогою нижчеописаної XML-структури. Всі дані, що знаходяться в тегах, обрамляються в тег <![CDATA[]]>:

<?xml version='1.0' encoding='utf-8'?>
<request_sendsms>
      <username><![CDATA[username]]></username>
      <password><![CDATA[password]]></password>
      <from><![CDATA[XML]]></from>
      <to><![CDATA[380501111111;380502222222]]></to>
      <text><![CDATA[Пример русского ЮТФ-8 текста]]></text>
</request_sendsms>
  • username – логін облікового запису користувача;
  • password – пароль облікового запису користувача;
  • from – альфа-ім'я, від якого йде відправка (11 англійських символів, цифри, пробіли);
  • to – список адресатів, розділені «;», після останнього адресата символ «;» не ставиться;
  • text – тег повідомлення в кодуванні UTF-8;
  • lifetime – установка терміну життя СМС, який вказується у хвилинах.

Важливо! Обмеження:

  • для друкованих символів (ASCII 0x01-0x7E) максимальна довжина повідомлення — 1071 символ;
  • для символів, що виходять за рамки даного діапазону, максимальна довжина повідомлення — 469;
  • в XML структурі, що відправляється на сервер www.gate.smsclub.mobi, мають бути відсутні пробіли та ентер між тегами!!!

На отриманий запит сервіс повертає XML-структуру такого вигляду:

<?xml version="1.0" encoding="utf-8"?>
<response>
       <status>STATUS</status>
       <text>RESULT_TEXT</text>
       <ids>
       <mess>ID_1</mess>
       <mess>ID_2</mess>
         …
       <mess>ID_N</mess>
       </ids>
</response>
  • status – OK (Операція завершена успішно) / ERROR (Сталася помилка);
  • text – текстове повідомлення про результат операції;
    У випадку вдалої операції, повідомлення типу: Повідомлень: N (M частин).
    У випадку помилки - суть помилки. Приклад: не знайдено відповідність пари логін\пароль.
  • ids – секція, яка містить список ID повідомлень, присвоєних SMSC;
    Список формується в порядку, відповідно до списку адресатів. Для повідомлення, що складається з декількох частин, список ID формується в порядку відправки частин повідомлення одному адресату, далі - список ID в порядку відправки частин повідомлення другому адресату і т. д.
  • mess – містить ID повідомлення/частини повідомлення.

Відправка персоналізованих повідомлень (поодиноких та масових)

Адреса служби:
https://gate.smsclub.mobi/xml/individual.php

Відправка персоналізованих повідомлень — це відправка СМС з індивідуальним текстом на кожен номер абонента, що здійснюється за допомогою нижчеописаної XML-структури. Всі дані, що знаходяться в тегах, обрамляються в тег <![CDATA[]]>. Кожне окреме СМС - це кортеж з даними в тегах <to> і <text>:

<?xml version='1.0' encoding='utf-8'?>
<request_sendsms>
      <username><![CDATA[username]]></username>
      <password><![CDATA[password]]></password>
      <from><![CDATA[XML]]></from>
      <to><![CDATA[380675126767]]></to>
      <text><![CDATA[Пример русского текста ЮТФ-8]]></text>
      ...
      <to><![CDATA[380997777662]]></to>
      <text><![CDATA[Example of text in UTF-8]]></text>
</request_sendsms>
  • username – логін облікового запису користувача;
  • password – пароль облікового запису користувача;
  • from – альфа-ім'я, від якого йде відправка (11 англійських символів, цифри, пробіли);
  • to – номер адресата;
  • text – тег повідомлення в кодуванні UTF-8.

Важливо! Обмеження:

  • для друкованих символів (ASCII 0x01-0x7E) максимальна довжина повідомлення — 1071 символ;
  • для символів, що виходять за рамки даного діапазону максимальна довжина повідомлення — 469;
  • в XML структурі, що відправляється на сервер www.gate.smsclub.mobi, мають бути відсутні пробіли та ентер між тегами!!!

На отриманий запит сервіс повертає XML-структуру такого вигляду:

<?xml version="1.0" encoding="utf-8"?>
<response>
       <status>STATUS</status>
       <text>RESULT_TEXT</text>
       <ids>
       <mess>ID_1</mess>
       <mess>ID_2</mess>
         …
       <mess>ID_N</mess>
       </ids>
</response>
  • status – OK (Операція завершена успішно) / ERROR (Сталася помилка);
  • text – текстове повідомлення про результат операції;
    У випадку вдалої операції, повідомлення типу: Повідомлень: N (M частин).
    У випадку помилки - суть помилки. Приклад: не знайдено відповідність пари логін\пароль.
  • ids – секція, яка містить список ID повідомлень, присвоєних SMSC;
    Список формується в порядку, відповідно до списку адресатів. Для повідомлення, що складається з декількох частин, список ID формується в порядку відправки частин повідомлення одному адресату, далі - список ID в порядку відправки частин повідомлення другому адресату і т. д.
  • mess – містить ID повідомлення/частини повідомлення.

Запит статусів повідомлень

Адреса служби:
https://gate.smsclub.mobi/xml/state.php

Статуси повідомлень містять інформацію про поточний стан повідомлення, регулярно оновлюються і можуть бути запитані користувачем у будь-який час. Запит статусів здійснюється за допомогою нижчеописаної XML-структури. Всі дані, що знаходяться в тегах, обрамляються в тег :

<?xml version="1.0" encoding="utf-8"?>
<request_getstate>
            <username><![CDATA[user]]></username>
            <password><![CDATA[pass]]></password>
            <smscid><![CDATA[000000;000001;000002;000003]]></smscid>
</request_getstate>
  • username – логін облікового запису користувача;
  • password – пароль облікового запису користувача;
  • smscid – список ID, розділених «;», після останнього ID символ «;» не ставиться.

У відповідь на запит сервіс повертає XML-структуру, що містить статуси для запитаних повідомлень або відповідні коди помилок такого вигляду:

    <?xml version="1.0" encoding="utf-8"?>
        <response>
        <status>OK</status>
        <text></text>
        <entries>
                 <entry>
                         <smscid>ID_1</smscid>
                         <state>STATE</state>
                 </entry>
                 <entry>
                         <smscid>ID_2</smscid>
                         <state>STATE</state>
                 </entry>
                 …
                <entry>
                        <smscid>ID_N</smscid>
                        <state>неверно указан id</state>
                </entry>
         </entries>
</response>
  • status – OK (Операція завершена успішно) / ERROR (Сталася помилка);
  • text – текстове повідомлення про результат операції;
    У випадку вдалої операції, тег не містить ніякої інформації.
    У випадку помилки - суть помилки. Приклад: не знайдено відповідність пари логін\пароль.
  • entries – секція, яка містить список запитуваних ID повідомлень, присвоєних SMS, і відповідних їм статусів;
    У разі виникнення помилки дана секція може бути відсутня.
  • entry – секція, яка містить ID і статус одного повідомлення;
  • smscid – запитуваний ID повідомлення;
  • state – відповідний йому статус.

Коди статусів повідомлень

Дані коди використовуються при поверненні статусів повідомлень:

  • ENROUTE – повідомлення прийнято;
  • DELIVRD – повідомлення доставлено;
  • EXPIRED – закінчився термін зберігання повідомлення;
  • UNDELIV – повідомлення не може бути доставлено;
  • REJECTD - відхилено.

Приклад коду відправки XML-запиту

Даний код протестований і гарантує позитивний результат. Використання інших методів - не тестувалося.

PHP-версія:

    <?php
      $xml = "
      <?xml version='1.0' encoding='utf-8'?>
      <request_sendsms>
            <username><![CDATA[username]]></username>
            <password><![CDATA[password]]></password>
            <from><![CDATA[XML]]></from>
            <to><![CDATA[380675126767]]></to>
            <text><![CDATA[Пример русского ЮТФ-8 текста]]></text>
      </request_sendsms>";
      $ch = curl_init();
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_POST, true);
      curl_setopt($ch, CURLOPT_POSTFIELDS, array("xmlrequest" => $xml));
      curl_setopt($ch, CURLOPT_URL, 'https://gate.smsclub.mobi/xml/');
      $result = curl_exec($ch);
      echo $result;
    ?>


Завантажити приклади

Тут Ви можете скачати приклади скриптів для роботи з обраним шлюзом:

Метод HTTP XML
Поодинока       java pearl
Масова
Індивідуальна
Баланс
Звіти
TOP