Виды интеграции

Введение

BSG API соединяет ваш сайт или приложение с операторами по всему миру.
На определенный адрес сервера отправляются XML-документы (описание XML-документов, их назначение и адреса сервера приведены ниже). При этом используется POST-метод.

Заголовки отправляемых данных должны содержать:
Content-type: text/xml; charset=utf-8

Кодировка XML-документов: UTF-8

Отправка СМС

Обязательные параметры:

Параметр Описание
login value Логин в системе
password value Пароль в системе
type Всегда равно “sms”
phone Телефон, на который рассылается СМС
client_id_sms ID СМС на стороне партнера. Если в системе уже существует СМС с таким client_id_sms, то повторно отправлена она не будет. Параметр необязательный.
number_sms Обязательный параметр, порядковый номер абонента в XML-документе

Пример отправки:
Url: http://app.bsg.hk/xml

<? xml version = "1.0" encoding = "utf-8"?>

<request>
<message type = «sms»>
<sender> sender </ sender>
<text> sms text </ text>
<abonent phone = «380631231233» client_id_sms = «3431» number_sms = «1» />
<abonent phone = «380633213211» client_id_sms = «3425» number_sms = «2» />
</ message>
<security>
<login value = «login» />
<password value = «password» />
</ security>
</ request>

В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:

<? xml version = "1.0" encoding = "utf-8"?>

<? xml version = «1.0» encoding = «utf-8»?>
<response>
< error> error </ error>
</ response>

error – текст ошибки может принимать следующие значения:

  • Неправильный формат XML-документа
  • Ваш аккаунт заблокирован
  • Неправильный логин или пароль
  • POST данные отсутствуют

В случае получения правильного XML-документа:

 

<? xml version = «1.0» encoding = «utf-8»?>
<response>
<information number_sms = «1» id_sms = «366» id_turn = «1428476741» parts = «1»> send </ information>
<information number_sms = «2» id_sms = «367» id_turn = «1428476741» parts = «1»> send </ information>
</ response>

Параметр Описание
number_sms Порядковый номер СМС в исходном XML-документе
id_sms Внутренний ID СМС. Используется для получения отчетов о доставке. Если в процессе отправки SMS произошла ошибка, то id_sms отдается пустым
id_turn Параметр оставлен для совместимости. ID очереди отправки
parts Количество частей СМС
information Статус сообщения («send»), если SMS была отправлена

Запрос статуса SMS-сообщения

Обязательные параметры:

Параметр Описание
login value Логин в системе
password value Пароль в системе

Пример:

Url: http://app.bsg.hk/xml/stat


<? xml version = "1.0" encoding = "utf-8"?>
<request>
<get_state>
<id_sms> 202 </ id_sms>
<id_sms> 203 </ id_sms>
<id_sms> 204 </ id_sms>
</ get_state>
<security>
<login value = "login" />
<password value = "password" />
</ security>
</ request>

В случае возникновения ошибки в отправляемом XML-документе:


<? xml version = "1.0" encoding = "utf-8"?>
<response>
<error> error</error>
</response>

error – текст ошибки может принимать следующие значения:

  1. Неправильный формат XML-документа
  2. Ваш аккаунт заблокирован
  3. Неправильный логин или пароль
  4. POST-данные отсутствуют

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


<? xml version = "1.0" encoding = "utf-8"?>
<response>
<state raw_value = "0" id_sms = "202" time = "">partly_deliver</state>
<state raw_value = "0" id_sms = "203" time = "">partly_deliver</state>
</response>

partly_deliver
partly_deliver

Параметр Описание
raw_value Статус сообщения по спецификации SMPP v3.4
id_sms ID сообщения
time Время статуса. Для некоторых значений может быть пустым
state Статус сообщения:

  1. «send» – статус сообщения не получен. В этом случае передается пустой time (time=»»).
  2. «not_deliver» — сообщение не было доставлено. Конечный статус (не меняется со временем).
  3. «expired» — абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный статус (не меняется со временем).
  4. «deliver» — сообщение доставлено. Конечный статус (не меняется со временем).
  5. «partly_deliver» — сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки.

Запрос проверки баланса.

Обязательные параметры:

Параметр Описание
login value Логин в системе
password value Пароль в системе

Пример:

Url: http://app.bsg.hk/xml/balance

XML-документ:


<? xml version = "1.0" encoding = "utf-8"?>
<request>
<security>
<login value = "username" />
<password value = "password" />
</ security>
</ request>

В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:


<? xml version = "1.0" encoding = "utf-8"?>
<response>
<error> error </ error>
< response>

error — текст ошибки может принимать следующие значения:

  • Неправильный формат XML документа
  • Неправильный логин или пароль
  • POST данные отсутствуют

В случае получения правильного XML-документа:


<? xml version = "1.0" encoding = "utf-8"?>
<response>
<money> 150 </ money>
</ response>>

Параметр Описание
money Остаток средств

Запрос на получение информации по номеру телефона.

Обязательные параметры:

Параметр Описание
login value Логин в системе
password value Пароль в системе
phone Номер телефона

Пример:

Url: http://app.bsg.hk/xml/def

XML-документ:


<? xml version = "1.0" encoding = "utf-8"?>
<request>
<security>
<login value = "username" />
<password value = "password" />
</ security>
<phones>
<phone> 79612242243 </ phone>
<phone> 79612242244 </ phone>
</ phones>
</ request>

 

В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:


<? xml version = "1.0" encoding = "utf-8"?>
<response>
<error> error </ error>
</ response>

error— текст ошибки может принимать следующие значения:

  • Неправильный формат XML документа
  • Неправильный логин или пароль
  • POST данные отсутствуют

В случае получения правильного XML-документа:


<? xml version = "1.0" encoding = "utf-8"?>
<response>
<phone operator = "beeline" country = "ru"> 79612242243 </ phone>
<phone operator = "beeline" country = "ru"> 79612242244 </ phone>
</ response>

Параметр Описание
operator Оператор
country Двухбуквенный код страны.
phone Номер телефона.

Введение

BSG API соединяет ваш сайт или приложение с операторами по всему миру
HTTP – протокол для передачи гипертекста, в своей структуре имеющий заголовок и тело запроса, которые разделены пустой строкой.
Тело запроса может быть пустым. Работа по данному протоколу происходит посредством программно устанавливаемого TCP-соединения с сервером и выдаче HTTP-запроса.
После обработки сервером этого запроса происходит выдача HTTP-ответа клиенту. Чаще всего используется в качестве команды HTTP метод GET, представляющий собой запрос документа. Именно GET запросы употребляются для передачи и приёма SMS-сообщений.
Данные отправляются на адрес http://app.bsg.hk/sendsms

Отправка СМС

Используются следующие переменные:

user пользователь
pwd пароль
sadr адрес отправителя
text текст смс
dadr адрес получателя(можно несколько через запятую)

в ответ выводится ID SMS (если было отправлено несколько телефонов через запятую — то ID в ответе будут тоже через запятую. В случае, если телефон был неверный — для него вернется пустой ID)

http://app.bsg.hk/sendsms?
user=логин&pwd=пароль&sadr=tот

правитель&dadr=номер_абонента&t

ext=текст_сообщения

Пример на PHP:
$login = ‘xxxxx’;
$password = ‘xxxxxx’;
$srcaddr = urlencode(‘alphaname’);
$text = urlencode(‘Текст смс’);
$num = ‘номер телефона получателя’;
$ch = curl_init();
$data = ‘http://app.bsg.hk/sendsms?
user=’.$login.’&pwd=’.
$password.’&sadr=’.$srcaddr.’&text=’.
$text.’&dadr=’.$num;
$urlData = urlencode( $data );
curl_setopt( $ch, CURLOPT_URL, $data );
curl_setopt( $ch,
CURLOPT_RETURNTRANSFER, true );
$out = curl_exec( $ch );
echo $out;
curl_close( $ch );

Проверка статуса

Используются следующие переменные:

user пользователь
pwd пароль
smsid ID SMS

В ответе будет один из возможных статусов:

  • deliver (доставлено)
  • not_deliver (не доставлено);
  • expired (просрочено);

Статус может быть также пустым, если сообщение еще находится в очереди, или для него еще нет статуса

ERRORS

Возможные ошибки во время запросов:

invalid_login_passw ord неверный логин или пароль
account_blocked аккаунт заблокирован
invalid_request неверный запрос (например, отсутствует один из параметров)