Ketchup loyalty marketing Ukraine
Описание REST API
Ketchup SMS&Viber
Описание REST API



Общие принципы.

Протокол KetchUp Loyalty API работает с использованием объектов JSON посредством http запросов, используя архитектуру REST. Каждый запрос содержит в себе заголовок X-API-KEY , содержащий в себе один из ключей – тестовый или рабочий. Тестовый ключ предназначен для отладки системы, все запросы с использованием тестового ключа возвращают случайную информацию. Для всех запросов, если в описании функции не указана другая информация, используется:

Content-type: text/json.

API URL

URL для передачи параметров выглядит как https://api.smsketchuployalty.com.ua /rest/{module}/{functionName} , где

{functionName} – это название вызываемого метода (полный список методов находится далее в документации),

{module} – модуль API (на данный момент поддерживается HLR).

Ответ на корректный запрос создания объектов (HLR-запросов, SMS-сообщений, адресных книг, итд) содержит в себе поле error:0, для запросов объектов это поле отсутствует. Если же поле есть в ответе, и значение этого поля ненулевое, то дополнительно будет передано поле errorDescription, в котором будет краткое описание ошибки, а все возможные коды ошибок смотрите в приложении 1.


HLR API

HLR (Home Location Register) — это централизованная база данных, которая содержит подробную информацию о каждом абоненте данной сети GSM-оператора.

Список функций:

Отправка HLR запроса

PUT (поддерживается так же и POST)

Endpoint URL: https://api.smsketchuployalty.com.ua /hlr/create

Header: X-API-KEY: live_asdfasdfq234

content-type: multipart/form-data



JSON Body RAW:

{

"msisdn":"380505142320",

"reference":"sendHLR0407",

"tariff":9

"callback_url":"https://somelink.com/hlr

}



вариант 1: для создания одного HLR-запроса

Внимание! Для данного запроса Content-type должен быть установлен в multipart/form-data!

в этом варианте передается 2 параметра (и два опциональных):

Required:

msisdn – номер телефона, на который отправляется HLR-запрос

reference – внешний id HLR-запроса

Optional:

tariff — номер тарифа. По умолчанию — 0. Целое число от 0 до 9.

callback_url – переопределяет ссылку, по которой будут передана информация об HLR запросе (см. ниже).



В случае некорректности данного параметра ошибка не генерируется, а используется callback_url из настроек пользователя (если он установлен).



Пример правильного ответа:

{"error":"0",

"id":"12123",

"price":"0.002",

"currency":"EUR"}

В случае наличия ошибки в запросе:

{"error":"11",

"errorDescription":"Incorrect msisdn"}



вариант2: создание нескольких запросов

передается параметр payload, содержащий JSON-encoded массив следующей структуры:



Header: X-API-KEY: live_asdfasdfq234

content-type: multipart/form-data

JSON Body RAW:

[

{"msisdn":"380972920000",

"reference":"extid13423now"

],

"tariff":9,

"callback_url":"http://someurl.com/callback/?id=12345"},

[

{"msisdn":"380972920000",

"reference":"extid13425"

],

"tariff":9,

"callback_url":"http://someurl.com/callback/?id=12346"}

]





Параметры tariff, callback_url являются опциональными.

В этом случае пример правильного ответа:

{"result":

[

{"reference":"extid13423now",

"id":"12345",

"error":"0",

"price":"0.002",

"currency":"EUR"},

{"reference":"extid13425",

"id":"12346",

"error":"0",

"price":"0.002",

"currency":"EUR"}

],

"error":"0",

"totalprice":"0.004",

"currency":"EUR"}

При ошибке в данных будет возвращен ответ примерно такого вида

{"error":"14",

"errorDescription":"Incorrect payload: missing msisdn"

}

В случае передачи одного или более уже существующих в системе внешних id HLR-запросов, ответ может выглядеть примерно так:

{"result":

[

{"reference":"extid13423now",

"id":"12345",

"error":"13",

" errorDescription":"HLR already exists"

}, {"reference":"extid13425",

"id":"12346",

"error":"0",

"price":"0.002",

"currency":"EUR"}

],

"error":"0",

"totalprice":"0.002",

"currency":"EUR"}

То есть, для всех HLR запросов с не уникальными (т.е. с теми, что уже существуют в системе) id, будет возвращена ошибка 13.



Внимание! При ошибке 14 HLR запросы не создаются, даже если в payload были и правильно переданные данные.




Получение таблицы цен HLR-запросов

GET /hlr/prices/{tariff}



Endpoint URL: https://api.smsketchuployalty.com.ua /hlr/prices/{tariff}



Необязательный параметр tariff указывает номер тарифной сетки. По умолчанию (в случае отсутствия) он принимается равным 9 (Best quality tariff)

Пример правильного ответа:

{"error":"0",

"prices":

[

{"type":"hlr",

"country":" AE",

"country_name":"United Arab Emirates",

"mcc":" 424","

price":"0.002",

"currency":"EUR"},

[

{"type":"hlr",

"country":" AF",

"country_name":"Afghanistan",

"mcc":" 412",

"price":"0.002",

"currency":"EUR"

}

]

}

В ответе будут перечислены все страны, для которых возможны HLR-запросы, вместе с ценами.

В случае наличия ошибки в запросе:

{"error":"6","errorDescription":"Invalid tariff code"}






Получение информации об HLR запросе

GET /hlr/{id}



Endpoint URL: https://api.smsketchuployalty.com.ua /hlr/{id}



Где {id} – id записи, полученной из метода /hlr/create



GET /hlr/reference/{reference}

Endpoint URL: https://api.smsketchuployalty.com.ua /hlr/{reference}



Где {reference} – внешний id сообщения



В ответ будет получен JSON примерно следующей структуры:



{

"id":"34298934543",

"reference":"1234567",

"msisdn":"380932990000",

"network":"unknown",

"status":"unknown",

"details":{"ported":"0","roaming":"0"},

"createdDatetime":"2015-08-04T06:50:19+00:00",

"statusDatetime":"2015-08-04T06:50:19+00:00"

}



id – внутренний id hlr

reference – внешний id hlr

msisdn – номер телефона, для которого производится hlr-запрос

network – mccmnc номера (для статусов absent, active)

status – статус запроса. Возможные значения: sent, absent, active, unknown, failed

details – детали hlr запроса (полная информация доступна при статусе active)

ported – признак, портирован телефон или нет (1 - портирован, 0 - нет)

roaming – признак, в роуминге телефон или нет. (1 - в роуминге, 0 - нет)



Или, при ошибке:

{"error":"10",

"errorDescription":"HLR not found"}






Отправка информации об HLR на указанный URL

Данный способ дополняет получение информации об HLR и является опциональным. Для его использования в настройках ЛК (личного кабинета) введите URL своего сервера, который будет принимать и обрабатывать запросы от нашей системы.

Пакет с информацией об HLR присылается через HTTP RAW POST запрос и содержит в себе ту же информацию, что и в разделе «Получение информации об HLR запросе». Запрос считается успешным, если сервер отдал HTTP заголовок с кодом 2xx, иначе будет произведено 5 попыток доставить информацию (через минуту, через 6 минут, через час, через 12 часов и через 24 часа).




SMS API

Список функций

Отправка SMS

PUT (поддерживается так же и POST) /sms/create

Поддерживается создание одиночной смс("destination":"phone"), массовой рассылки("destination":"phones") и индивидуальных смс (("destination":"individual"). В будущем будет добавлена возможность создать по API рассылку с адресной книги("destination":"addresbook").



Передаваемый параметр payload для "destination":"phone" содержащий JSON-encoded массив следующей структуры: Пример кода: PUT (POST)

Endpoint URL: https://api.smsketchuployalty.com.ua /rest/sms/create



Header: X-API-KEY: live_qwefqw41234

Content-type: application/json



JSON Body RAW:

{"originator":"test",

"body":"test sms",

"validity": 72,

"tariff":9,

"destination":"phone",

"msisdn": "380972000000",

"reference":"12erdgm9",

"send_time" : "ISO 8601 date"}



Required:

destination – устанавливается в значение "phone"

originator — отправитель. Строка до 14 символов.

body — текст сообщения. Текст

msisdn – номер телефона, на который отправляется sms

reference — внешний id sms. Строка до 32 символов, содержащих /a-zA-Z0-9/

Optional:

validity — время действия смс (по умолчанию — 72 часа). Целое число от 1 до 72

tariff — номер тарифа. По умолчанию — 0. Целое число от 0 до 9.

send_time – время отправки смс (для планирования смс рассылок)



Пример правильного ответа 200 OK / Response:

{"error":"0",

"id":"22125",

"reference":"12erdgm9",

"price":"0.02",

"currency":"EUR"}



В случае наличия ошибки в запросе / Error Response:

{"error":"11",

"errorDescription":"Incorrect msisdn"}



Для случая destination = phones (один текст для всех номеров): Пример кода:



Header: X-API-KEY: live_qwefqw41234

Content-type: application/json



JSON Body RAW:

{"destination":"phones",

"phones":[

{"msisdn": "380972000001","reference":"12erdgm9"},

{"msisdn": "380972000002","reference":"12erdgn0"}

],

"originator":"test",

"body":"test sms",

"validity": 72,

"tariff":9,

"send_time" : "ISO 8601 date"}



передаются следующие параметры (курсивом выделены необязательные):

Required:

destination – устанавливается в значение "phones"

phones – массив значений:

msisdn – номер телефона, на который отправляется sms

reference — внешний id sms. Строка до 32 символов, содержащих /a-zA-Z0-9/

originator — отправитель. Строка до 14 символов.

body — текст сообщения. Текст

Optional:

validity — время действия смс, часы (по умолчанию — 72 часа). Целое число от 1 до 72

tariff — номер тарифа. По умолчанию — 0. Целое число от 0 до 9.

send_time – время отправки смс (для планирования смс рассылок)



В этом случае пример правильного ответа / Response:



{"result":

[

{"reference":"12erdgm9",

"id":"12345",

"error":"0",

"price":"0.02",

"currency":"EUR"},

{"reference":"12erdgn0",

"id":"12346",

"error":"0",

"price":"0.02",

"currency":"EUR"}

],

"error":"0",

"totalprice":"0.04",

"currency":"EUR",

"task_id":"21902"}



Параметр task_id служит для запроса статуса по всей рассылке.



При ошибке в данных будет возвращен ответ примерно такого вида

{"error":"25",

"errorDescription":"Invalid originator"}

Для случая destination = individual



{"validity": 72,

"tariff":9,

"destination":"individual",

"phones":

[

{"originator":"test1",

"body":"test sms1",

"msisdn":"380972000001",

"reference": "12erdgm9"},

{"originator":"test2",

"body":"test sms2",

"msisdn": "380972000002",

"reference": "12erdgn0"}

],

"scheduledDatetime" : "ISO 8601 date"}



передаются следующие параметры (курсивом выделены необязательные):

destination – устанавливается в значение "phones"

validity — время действия смс (по умолчанию — 72 часа). Целое число от 1 до 72

tariff — номер тарифа. По умолчанию — 0. Целое число от 0 до 9.

phones – массив значений:

msisdn – номер телефона, на который отправляется sms

reference — внешний id sms. Строка до 32 символов, содержащих /a-zA-Z0-9/

originator — отправитель. Строка до 14 символов.

body — текст сообщения. Текст

scheduledDatetime – время отправки смс (для планирования смс рассылок)



В этом случае пример правильного ответа:



{"result":

[

{"reference":"12erdgm9",

"id":"12345",

"error":"0",

"price":"0.02",

"currency":"EUR"},

{"reference":"12erdgn0",

"id":"12346",

"error":"0",

"price":"0.02",

"currency":"EUR"}

],

"error":"0",

"totalprice":"0.04",

"currency":"EUR",

"task_id":"21902"}



Параметр task_id служит для запроса статуса по всей рассылке

При ошибке в данных будет возвращен ответ примерно такого вида

{"error":"24",

"errorDescription":"Invalid request payload"}






View an SMS status

GET /sms/{id}

или

GET /sms/{reference}

или

GET /sms/{task_id}



GET /sms/{id}

{id} уникальный случайный ID, что был создан на платформе, и вернулся в ответ на запрос отправки сообщения. Int значение.



Пример респонса

{ "error":0,

"errorDescription":"No errors",

"id":"211″,

"msisdn":"380972000001″,

"reference":"ext_id_19″,

"time_in":"2017-01-17 09:11:41″,

"time_sent":"2017-01-17 09:11:41″,

"time_dr":"2017-01-17 09:11:41″,

"status":"delivered",

"price":0.23,

"currency":"EUR"

}





GET /sms/{reference}

{reference} Референс Клиента



GET /sms/{task_id}

{task_id} Уникальный случайный ID который был создан для массового запроса.



Пример ответа

{ "originator":"alpha_name",

"body":"message text",

"validity":72,

"totalprice":0.23,

"currency":"EUR",

"sent":1,

"delivered":1,

"expired":0,

"undeliverable":0,

"unknown":0

}

Пример ошибки для запроса информации о рассылке

{ "error": 30,

"errorDescription":"Task not found"

}

Получение цены смс

PUT (поддерживается так же и POST) /sms/price



Параметры аналогичные отправке смс. В ответ может быть получена одна из ошибок или структура следующего содержания:

{error":"0", "totalprice":"0.004","currency":"EUR"}

Получение статусов смс

GET /sms/{id}

Где {id} – id записи, полученной из метода /sms/create

GET /sms/reference/{reference}

Где {reference} – внешний id сообщения

В ответ будет получен JSON примерно следующей структуры:

{ "error":"0","msisdn": "380972000000","reference":"12erdgm9", "time_in":"2016-01-01 00:00:01","time_sent":"2016-01-01 00:00:02","time_dr":"2016-01-01 00:01:01","status":" delivered ","price":"0.02","currency":"EUR"}

При ошибке в данных будет возвращен ответ примерно такого вида

{"error":"20","errorDescription":"SMS not found"}



Для смс, которые были созданы с ключом destination = phones, можно запрашивать расширенную статистику:

GET /sms/task/{id}

Где {id} – task_id из ответа

В ответ будет получен JSON примерно следующей структуры:

{"error":"0","originator ":"test","body":"test sms", "validity": 72, "sent":"2","delivered":"1","undeliverable":"1", "expired": "0", "unknown":"0","totalprice":"0.04","currency":"EUR"

}



При ошибке в данных будет возвращен ответ примерно такого вида

{"error":"30","errorDescription":"Task not found"}








Получение таблицы цен SMS

GET /sms/prices/{tariff}

Необязательный параметр tariff указывает номер тарифной сетки. По умолчанию (в случае отсутствия) он принимается равным 0 (Global tariff)

Пример правильного ответа:

{"error":"0","prices":[{"type":"sms","country":" AE","country_name":"United Arab Emirates","mcc":" 424","price":"0.02","currency":"EUR"}, ":[{"type":"sms", "country":" AF","country_name":"Afghanistan","mcc":" 412","price":"0.05","currency":"EUR"}]}

В ответе будут перечислены все страны, для которых возможа отправка sms-сообщений, вместе с ценами.

В случае наличия ошибки в запросе:

{"error":"6","errorDescription":"Invalid tariff code"}






Viber API

Список функций

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

PUT (поддерживается так же и POST) /viber/create

Передается JSON-encoded массив следующей структуры:



Endpoint: https://api.smsketchuployalty.com.ua /rest/viber/create



Header: X-API-KEY: live_qwer234

Content-type: application/json



{

"tariff" :9,

"validity": 24,

"messages":[

{

"to": [

{"msisdn": "380972920283", "external_id": "example_12"},

{"msisdn": "380972920282", "external_id": "example_13"}

],

"text" : "My Viber messages is shinier than your SMS messages",

"callback_url": "https://my-cool-webpage.com/viber-dlr",

"alpha_name": "My Company",

"is_promotional": false,

"options" : {

"viber": {

"img": "http://my-cool-webpage.com/logo.png",

"caption": "Join us!",

"action": "http://my-cool-webpage.com"

}

},

"scheduledDatetime" : "ISO 8601 date"

}

]

}



validity — время действия сообщения Viber, в секундах (по умолчанию — 24 часа). Целое число от 15 до 86400

tariff — номер тарифа. По умолчанию — 0. Целое число от 0 до 9.

result – массив объектов сообщений. Содержит 1+ объектов следующей структуры:

to – массив получателей. При этом задается обязательный параметр phone и необязательный external_id

text – текст вайбер сообщения

callback_url – ссылка для автоматической отправки отчетов до доставке. Внимание, отчёт отправляется только в том случае, если для получателя указан external_id.

alpha_name – отправитель

is_promotional – признак, рекламное сообщение, или транзакционное

options – дополнительные опции. На данный момент проверяются опции, которые присутствуют в теге viber

scheduledDatetime – время отправки смс (для планирования смс рассылок)



Пример правильного ответа:

[{"error":"0", "messages" : [{"id":"22125","reference":"example_12","price":"0.02","currency":"EUR"},{"id":"22126","price":"0.02","currency":"EUR"}], "total_price": "0.04", "currency":"EUR"}]

В случае наличия ошибки в запросе:

{"error":"11","errorDescription":"Incorrect msisdn"}






Получение цены Viber-сообщения

PUT (поддерживается так же и POST) /viber/price

Параметры аналогичные отправке смс. В ответ может быть получена одна из ошибок или структура следующего содержания:

{error":"0", "totalprice":"0.004","currency":"EUR"}



Получение статусов Viber-сообщения

GET /viber/{id}

Где {id} – id записи, полученной из метода /viber/create

GET /viber/reference/{reference}

Где {reference} – внешний id сообщения

В ответ будет получен JSON примерно следующей структуры:

{ "error":"0","msisdn": "380972000000","reference":"12erdgm9", "time_in":"2016-01-01 00:00:01","time_sent":"2016-01-01 00:00:02","time_dr":"2016-01-01 00:01:01","status":"read","price":"0.02","currency":"EUR"}

При ошибке в данных будет возвращен ответ примерно такого вида

{"error":"40","errorDescription":"Message not found"}



Получение таблицы цен Viber

GET /viber/prices/{tariff}

Необязательный параметр tariff указывает номер тарифной сетки. По умолчанию (в случае отсутствия) он принимается равным 0 (Global tariff)

Пример правильного ответа:

{"error":"0","prices":[{"type":"viber","country":" AE","country_name":"United Arab Emirates","mcc":" 424","price":"0.01","currency":"EUR"}, ":[{"type":" viber ", "country":" AF","country_name":"Afghanistan","mcc":" 412","price":"0.01","currency":"EUR"}]}

В ответе будут перечислены все страны, для которых возможа отправка sms-сообщений, вместе с ценами.

В случае наличия ошибки в запросе:

{"error":"6","errorDescription":"Invalid tariff code"}


Детальная статистика сообщений

Общие принципы.

Передачи детальной статистики сообщений через API. Работает с использованием объектов JSON посредством http запросов, используя архитектуру REST. Каждый запрос содержит в себе заголовок X-API-KEY, содержащий в себе один из ключей – тестовый или рабочий. Тестовый ключ предназначен для отладки системы, все запросы с использованием тестового ключа возвращают случайную информацию.



Ответ на корректный запрос выгрузки содержит в себе поле error:0. Если же поле есть в ответе, и значение этого поля ненулевое, то дополнительно будет передано поле errorDescription, в котором будет краткое описание ошибки, а все возможные коды ошибок смотрите в приложении 1.



Данные выгрузки храним на сервере один месяц от даты создания запроса. Один клиент может иметь на сервере только 5 запрошенных выгрузок. Чтобы сделать шестую, предыдущую необходимо удалить отдельным методом. В запросе на формирование выгрузки строка с null равняется не указанному параметру и наоборот.



Запрос на выгрузку статистики



URL для передачи параметров выглядит как



POST https://api.smsketchuployalty.com.ua /rest/stat/create



Header: X-API-KEY: live_asdfasdfq234

content-type: application/json



JSON Body RAW:

{

"message_id": [

"1530913625",

"1530913626"

]

"msisdn": [

"380505142322",

"380505142323"

]

"originator": "testsms",

"source_type": "web",

"message_type": "sms",

"time_in_from": "2020-10-22 17:28:45",

"time_in_to": "2020-10-22 17:28:45",

"time_sent_from": null,

"time_sent_to": null,

"country_name": "Ukraine",

"operator_id": null,

"status": null,

"sl_clicks": null,

"sl_clicks_comp": null,

"sl_clicks_count": null,

"callback_url":"https://somelink.com/message_report

}



передаются следующие параметры:

Required. Одно из следующих:

message_id – устанавливается в значение "message_id". Если задано это значение, все последующие поля не учитываются, даже если там указаны данные. Массив. 300 значений в массиве максимум. В случае если указан пустой массив, или есть параметр, но ключ указан не массив, то параметр игнорируется.

ИЛИ промежуток времени

time_in_from - дата и время поступления на платформу сообщений.

time_in_to - дата и время поступления на платформу сообщений



Optional:

msisdn - массив значений для указания номеров. В случае если указан пустой массив, или есть параметр, но ключ указан не массив, то параметр игнорируется.

originator - имя отправителя

source_type - источник сообщений, откуда сообщение поступило на платформу. Может принимать одно из следующих значений: api, web, smpp, xml, http, json

message_type - тип сообщения. Может принимать следующие значения: sms, hlr, viber

time_sent_from - время отправки сообщений с платформы "от"

time_sent_to - время отправки сообщений с платформы "до"

country_name - название страны для поиска.

operator_id - указание оператора страны, при наличии поля Country_name. Если указан оператор без страны - игнорируется

status - статус сообщений, которые нужно отобразить. Может принимать значения: Delivered, Rejected, Scheduled, Moderation, Accepted, Sending, Sent, Expired, Failed, Undelivered, Unknown, Read, not-viber-user

sl_clicks - нужно учитывать кол-во кликов или нет. Поле доступно только клиентам, у которых есть подключенные шорт линки.

sl_clicks_comp - оператор сравнения со значением количества кликов. Может принимать значения: "<", ">", "=". Поле доступно только клиентам, у которых есть подключенные шорт линки.

sl_clicks_count - значение, которое сравнивается. Верхний лимит символов - 999999. Поле доступно только клиентам, у которых есть подключенные шорт линки.



Пример правильного ответа 200 OK / Response:

{

"error":0,

"key": {}

}


Получение запрошенной информации о сообщениях





GET https://api.smsketchuployalty.com.ua /rest/stat/file/id/{file_key}/format/{file_format}

{file_key} - имя файла, которое вернулось в предыдущем методе

{file_format} - допустимые варианты: json, xml, csv (доступно, только при выбранном параметре message_type)



Header: X-API-KEY: live_asdfasdfq234





Пример правильного ответа 200 OK / Response:

Only SMS messages:

{"error": 0

[

{"message_ID": 1529112192,

"message_type": "sms",

"msisdn": 380505142320,

"Country_name": "Ukraine",

"brand_name": "Vodafone - VF Ukraine JSC",

"mcc": 255,

"mnc": 01,

"originator": "testsms",

"price": "0.0000000 EUR",

"Incoming date": "2020-10-22 17:28:45",

"Sending date": "2020-10-22 17:28:45",

"DLR Date": "2020-10-22 17:28:45",

"Status": "Delivered"

"body": "testing message"

},

{

similar data for another message_ID

}

]





Одно из сообщений - HLR.

{"error": 0

[

{"message_ID": 1529112192,

"message_type": "sms",

"msisdn": 380505142320,

"Country_name": "Ukraine",

"brand_name": "Vodafone - VF Ukraine JSC",

"mcc": 255,

"mnc": 01,

"originator": "testsms",

"price": "0.0000000 EUR",

"Incoming date": "2020-10-22 17:28:45",

"Sending date": "2020-10-22 17:28:45",

"DLR Date": "2020-10-22 17:28:45",

"Status": "Delivered"

"body": "testing message"

},

{"message_ID": 1529112192,

"message_type": "hlr",

"msisdn": 380505142320,

"Country_name": "Ukraine",

"brand_name": "Vodafone - VF Ukraine JSC",

"mcc": 255,

"mnc": 01,

"originator": "HLR",

"price": "0.0000000 EUR",

"Incoming date": "2020-10-22 17:28:45",

"Sending date": "2020-10-22 17:28:45",

"DLR Date": "2020-10-22 17:28:45",

"Status": "Delivered"

"body": {

"Country_name": "Ukraine"

"Brand": "Kyivstar"

"Operator": "Kyivstar GSM JSC"

"MCC": 255

"MNC": 03

"Status": "Active"

"IMSI": 255039900000000

"Ported": 1

"Roaming": 0

}

}

]



В случае message_type Viber ответ может включать в себя данные по альтернативным СМС. Данные такие же как и для обычного отчета по СМС.



{"error": 0,

message_data:

[

{"message_ID": 1529112192,

"message_type": "sms",

"msisdn": 380505142320,

"Country_name": "Ukraine",

"brand_name": "Vodafone - VF Ukraine JSC",

"mcc": 255,

"mnc": 01,

"originator": "testsms",

"price": "0.0000000 EUR",

"Incoming date": "2020-10-22 17:28:45",

"Sending date": "2020-10-22 17:28:45",

"DLR Date": "2020-10-22 17:28:45",

"Status": "Delivered"

"body": "testing message"

},

{"message_ID": 1529112193,

"message_type": "hlr",

"msisdn": 380505142320,

"Country_name": "Ukraine",

"brand_name": "Vodafone - VF Ukraine JSC",

"mcc": 255,

"mnc": 01,

"originator": "HLR",

"price": "0.0000000 EUR",

"Incoming date": "2020-10-22 17:28:45",

"Sending date": "2020-10-22 17:28:45",

"DLR Date": "2020-10-22 17:28:45",

"Status": "Delivered"

"body": {

"Country_name": "Ukraine"

"Brand": "Kyivstar"

"Operator": "Kyivstar GSM JSC"

"MCC": 255

"MNC": 03

"Status": "Active"

"IMSI": 255039900000000

"Ported": 1

"Roaming": 0

}

},

{"message_ID": 1529112194,

"message_type": "viber",

"msisdn": 380505142320,

"Country_name": "Ukraine",

"brand_name": "Vodafone - VF Ukraine JSC",

"mcc": 255,

"mnc": 01,

"originator": "testsms",

"price": "0.0000000 EUR",

"Incoming date": "2020-10-22 17:28:45",

"Sending date": "2020-10-22 17:28:45",

"DLR Date": "2020-10-22 17:28:45",

"Status": "not-viber-user",

"body": "testing message",

"img": "https://site.com/image.png",

"Caption": "КУПИ!",

"Action": "https://site.com/buy.html",

"alternativeSMS": {

"message_ID": 1529112195,

"message_type": "sms",

"msisdn": 380505142320,

"Country_name": "Ukraine",

"brand_name": "Vodafone - VF Ukraine JSC",

"mcc": 255,

"mnc": 01,

"originator": "testsms",

"price": "0.0000000 EUR",

"Incoming date": "2020-10-22 17:28:45",

"Sending date": "2020-10-22 17:28:45",

"DLR Date": "2020-10-22 17:28:45",

"Status": "Delivered"

"body": "testing message for Viber undeliv"

}

}

]



В случае наличия ошибки в запросе / Error Response:

{"error":"60",

"errorDescription":"Message_id do not exist"}


Отправка данных на указанный URL

In Progress

Данный способ дополняет получение информации о сообщениях и является опциональным. Для его использования в настройках ЛК (личного кабинета) введите URL своего сервера, который будет принимать и обрабатывать запросы от нашей системы.

Пакет с информацией о сообщениях присылается через HTTP RAW POST запрос и содержит в себе ту же информацию, что и в разделе «Получение запрошенной статистики». Запрос считается успешным, если сервер отдал HTTP заголовок с кодом 2xx, иначе будет произведено 5 попыток доставить информацию (через минуту, через 6 минут, через час, через 12 часов и через 24 часа).


Удаление предыдущих запрошенных файлов

DELETE https://api.smsketchuployalty.com.ua /rest/message/list/{file_key}

{file} - имя файла, которое вернулось в методе запроса выгрузки



Header: X-API-KEY: live_asdfasdfq234



Запрос списка существующих файлов

GET https://api.smsketchuployalty.com.ua /rest/stat/list

Header: X-API-KEY: live_asdfasdfq234












Приложение 1. Коды ошибок

Общие ошибки (0-9)

0 – нет ошибки

1 – неверный ключ

3 – пользователь заблокирован

2 – недостаточно параметров

4 – запрашиваемая функция не поддерживается

5 – неизвестная ошибка

6 – указан несуществующий номер тарифной сетки

7 – неверные параметры

8 – недостаточно денег

9 – тарифная сетка неактивна

10 – неверное время отправки

11 – превышено максимальное число одновременно обрабатываемых на отправку сообщений

12 – превышен максимальный размер пакета сообщений



Ошибки HLR (60-79)

60 – HLR не найден

61 – неверный номер телефона

62 – отсутствует внешний ID HLR-запроса

63 – HLR с таким ID уже присутствует

64 – неверный payload запроса

65 — неверный внешний ID HLR-запроса

66 – телефон уже присутствует в запросе

Ошибки SMS (20-39)

20 — SMS не найдена

21 — неверный номер телефона

22 – отсутствует внешний ID SMS-запроса

23 – SMS с таким ID уже присутствует

24 – неверный payload запроса

25 — неверный originator

26 — пустой или слишком длинный текст смс

27 — неверный внешний ID SMS

28 — неверное значение времени действия SMS

29 – id задачи неверный

30 – задача не найдена

31 – телефон уже присутствует в рассылке

32- sender not allowed





Ошибки Viber (40-59)

40 – Сообщение Viber не найдено

41 – неверный номер телефона

43 – Viber сообщение с таким ID уже присутствует

44 – неверный payload запроса

45 — отправитель не зарегистрирован

46 — пустой или слишком длинный текст Viber сообщения

47 — неверный внешний ID Viber сообщения

48 — неверное значение времени действия Viber сообщения

49 – неверные дополнительные опции Viber сообщения

51 – телефон уже присутствует в рассылке





Ошибки запроса генерации статистики (80-100):

80 - invalid message_id (не числовое значение)

81 - invalid message_type

82 - invalid source_type

83 - invalid status

84 - invalid country_name

85 - invalid sl_clicks_comp

86 - invalid time frame

87 - 89 - reserved for future use





Ошибки запроса файла статистики:

90 - file not found

91 - file not ready

92 - Maximum count of exports reached

93 - File is empty

Made on
Tilda