Инструкция по подключению сайта/ПО к сервису, по протоколу HTTP

Вступление

HTTP API предоставляет возможность отправки СМС сообщения и получения статуса доставки сообщения. Взаимодействие с API осуществляется по протоколу HTTP или HTTPS (рекомендуется), параметры передаются методом GET или POST. Чтобы обратиться к API- функции, нужно вызвать ее по определенному адресу, который формируется из:

  • – основного адреса шлюза: https://smsbat.com/api/http.php
  • – названия функции.

Отправка сообщения

Для отправки сообщения необходимо:

  • – сформировать адрес для запросов: https://smsbat.com/api/http.php
  • – включить необходимые параметры:
    • version=http
    • login={LOGIN}
    • pass={PASSWORD}
    • key = {API/KEY}
    • from={FROM_ADDR}
    • to={TO_ADDR}
    • message={MESSAGE_TEXT}

где:

  • VERSION – указываем протокол http или https;
  • LOGIN — Ваш логин на сайте;
  • PASSWORD — Ваш пароль на сайте;
  • API/KEY – ключ;
  • FROM_ADDR — адрес отправителя;
  • TO_ADDR — номер телефона получателя сообщения;
  • MESSAGE_TEXT — текст сообщения;
  • Command=send- где send – отправка одного сообщения.

Пример строки запроса с использованием логина и пароля:https://smsbat.com/api/http.php?version=http&login=LOGIN&password=PASS&command=send&from=test&to=380501234567&message=test

Пример строки запроса с использованием ключа:https://smsbat.com/api/http.php?version=http&key=api/key&command=send&from=test&to=380501234567&message=test

Для того, чтобы найти ключ, необходимо зайти:

  • – мой офис – настройки – API.

Основные критерии и правила которые необходимо соблюдать:

Параметр Обязательно Описание
from Да Имя (телефон) отправителя. Латинские символы или числа до 11 символов, а так же точка, тире, подчеркивание.
to Да Телефон получателя в международном формате. Для Украины можно в локальном.
message Да Текст сообщения в кодировке UTF8
wap Нет Ссылка на сайт. Для отправки Wap-Push сообщений.
flash Нет Отправить сообщение как Flash-сообщение
ask_date Нет Дата и время отправки сообщения в формате ISO-8601: 2009-08-15T15:52:01+0200

После отправки сообщения, в окне браузера, Мы видим:

  • id:{MESSAGE_ID}

где {MESSAGE_ID} – выступает в качестве идентификатора сгенерированным SMS шлюзом.

Пример:

br>id:84523377 sms_count:1

Отправка сообщения Viber

Для отправки сообщения необходимо:

  • – сформировать адрес для запросов: https://smsbat.com/api/http.php
  • – включить необходимые параметры:
    • version=http
    • login={LOGIN}
    • pass={PASSWORD}
    • key = {API/KEY}
    • from={FROM_ADDR}
    • to={TO_ADDR}
    • message={MESSAGE_TEXT}

где:

  • VIBER_TEXT – текст сообщения для Viber;
  • FROM_ADDR _VIBER — имя отправителя для Viber;
  • N — срок жизни сообщения Viber в секундах (от 60 до 86400);

Основные критерии и правила которые необходимо соблюдать:

Параметр Обязательно Описание
from
Да Имя (телефон) отправителя. Латинские символы или числа до 11 символов, а так же точка, тире, подчеркивание.
to Да Телефон получателя в международном формате. Для Украины можно в локальном.
message Да Текст сообщения в кодировке UTF8
wap Нет Ссылка на сайт. Для отправки Wap-Push сообщений.
flash Нет Отправить сообщение как Flash-сообщение
ask_date Нет Дата и время отправки сообщения в формате ISO-8601: 2009-08-15T15:52:01+0200
viber Да Фиксированное значение – 1 или true
viber_type Да Тип сообщения (допустимое значение – text, image, button)
viber_message Да Текст сообщения в кодировке UTF8 До 1000 символов.
viber_from Да Согласованное имя отправителя.
viber_lifetime Да Срок жизни сообщения Viber в секундах (от 60 до 86400)
viber_sms Да Значение 1 (если переотправлять сообщение по SMS в случае невозможности доставить через Viber)
viber_image Да Ссылка на изображение (должна содержать .jpg, .jpeg, .png или .gif в качестве расширения)
viber_url Да Ссылка на ресурс для перехода по нажатию на картинку или кнопку
viber_button Да Текст кнопки, от 1 до 19 символов

Ошибки которые могут возникнуть, после отправки SMS сообщения

errors:{ERROR1_TEXT}

errors:{ERROR2_TEXT}

errors:{ERROR#_TEXT}

Причины возникновения ошибок:

  • – неправильно указан телефон получателя;
  • – не написали сообщение в теле message;
  • – SMS сообщение слишком длинное;
  • – отсутствуют деньги на балансе.

Получение текущего статуса сообщения

Для получения статуса сообщения необходимо ввести следующую строку запроса: https://smsbat.com/api/http.php?version=http&login=LOGIN&password=PASS&command=receive&id=номер

После, в строке браузера, Мы видим:

status: Доставлено code:3 status_time:год/месяц/время.

receive: –получение текущего статуса сообщения

Параметр Описание
id Номер сообщения, выданный при успешной отправке командой «send»

Статусы SMS сообщения и ошибки которые могут возникнуть при проверке

Статусы сообщения:

  • 0 – Ожидает
  • 1 – Отправляется
  • 2 – Отправлено
  • 3 – Доставлено
  • 5 – Нет на связи
  • 10 – Удалено
  • 50 – Частично доставлено
  • 96 – Сбой сети при доставке SMS
  • 99 – Ошибка в номере
  • 99 – Номер не обслуживается

В случае ошибок:

  • errors:{ERROR1_TEXT}

Причины возникновения ошибок:

  • – SMS сообщение не найдено.

Удаление SMS сообщения из очереди

SMS сообщения удаляется из очереди, только в том случае, если сообщение было запланировано (указано конкретно дату и время отправки SMS сообщения).

Пример запланированного SMS сообщения:

https://smsbat.com/api/http.php?version=http&login=LOGIN&password=test&command=send&from=test&to=380501234567&message=test&ask_date=ISO-8601:2013-01-21T16:35:00+0200

ask_date – дата и время отправки сообщения в формате ISO-8601: 2009-08-15T15:52:01+0200

Пример строки запроса в случае удаления SMS сообщения из очереди:

https://smsbat.com/api/http.php?version=http&login=LOGIN&password=PASS&command=delete&id=test

delete: – удаление сообщения из очереди

Параметр Описание
id Номер сообщения, выданный при успешной отправке командой «send»

После отправки сообщения, в окне браузера, Мы видим:

  • status:{STATUS_TEXT}
  • code:{STATUS_CODE}
  • где {STATUS_TEXT} – статус сообщения в кодировке UTF8, {STATUS_CODE} – код сообщения.

Статусы SMS сообщения и ошибки которые могут возникнуть при проверке

Статусы сообщения:

  • 0 – Ожидает
  • 1 – Отправляется
  • 2 – Отправлено
  • 3 – Доставлено
  • 5 – Нет на связи
  • 10 – Удалено
  • 50 – Частично доставлено
  • 96 – Сбой сети при доставке SMS
  • 99 – Ошибка в номере
  • 99 – Номер не обслуживается

В случае ошибок:

  • errors:{ERROR1_TEXT}

Причины возникновения ошибок:

  • – SMS сообщение не может быть удалено.

Получения стоимости отправки SMSсообщения на указанный номер

Пример строки запроса в случае получения стоимости отправки SMS сообщения:

https://smsbat.com/api/http.php?version=http&login=LOGIN&password=PASS&command=price&to=380501234567

где, price: – получения стоимости отправки SMSсообщения на указанный номер

Параметр Описание
phone Телефон получателя в международном формате. Для Украины можно в локальном.

После отправки сообщения, в окне браузера, Мы видим:

  • price:{SMS_PRICE}
  • currency:{CURRENCY_CODE}
  • где, {SMS_PRICE} – цена за SMS сообщения, {CURRENCY_CODE} – валюта стоимости SMS сообщения.

Примечание:

Если цена не указана – доставка на запрашиваемый номер не производится.

Проверка баланса

Пример строки запроса в случае проверки баланса:

https://smsbat.com/api/http.php?version=http&login=LOGIN&password=PASS&command=balance

где, balance: – получения баланса пользователя в валюте Украины (гривна).

После отправки сообщения, в окне браузера, Мы видим:

  • balane:{AMOUNT}

Причины возникновения ошибок:

  • – неправильный логин / пароль;
  • – неизвестная команда.