CardsMobile#
Тип сообщения CardsMobile относится только к приложению “Кошелёк“.
В сообщениях типа CardsMobile доступна передача заголовка, текста и, опционально, изображения.
Отправка сообщений#
1 {
2 "login": "Login",
3 "password": "Password",
4 "destAddr": "79211234567",
5 "message": {
6 "type": "CARDSMOBILE",
7 "data": {
8 "text": "Hello, world!",
9 "title": "Super Title!",
10 "serviceNumber": "0000",
11 "ttl": 3600,
12 "ttlUnit": "SECONDS",
13 "content": {
14 "contentUrl": "http://ya.ru/123.jpg"
15 },
16 "target": "campaign",
17 "campaignId": "123",
18 "pushType": "PROMO"
19 }
20 }
21 }
Обязательные параметры выделены жирным шрифтом.
Параметр |
Тип данных |
Описание |
---|---|---|
login |
string |
Имя Партнера в системе. |
password |
string |
Пароль Партнера в системе. |
extraParam |
string |
Дополнительные параметры, передаваемые в виде param1=value1,param2=value2,
где
Символ запятой в название параметра входить не может, но может входить
в его значение – в этом случае он должен удваиваться.
Пример: строка место=абзаково,название=гостевой дом-2,координаты=53.8085896,,
58.6362112,c=23.02.09,по=05.03.09.
|
useTimeDiff |
boolean |
Учитывание часового пояса при запуске рассылки.
Если true, то отправка сообщения осуществляется абоненту согласно
расписанию рассылки и его часовому поясу.
Если false, то сообщение отправляется согласно расписанию инициатора
рассылки UTC+3, без учёта часового пояса получателя сообщения.
Значение по умолчанию: false.
|
scheduleInfo |
object |
Расписание рассылки. Если не указано, отправляется сразу же, в момент
получения запроса.
|
scheduleInfo/timeBegin |
string |
Время начала, например, «10:00». |
scheduleInfo/timeEnd |
string |
Время окончания, например, «21:00». |
scheduleInfo/weekdaysSchedule |
string |
Дни рассылки. Задаются цифрами от 1 (понедельник) до 7 (воскресение),
например, «12345».
Если ограничений по дням недели нет, то данный параметр может быть пустой
или не передан в запросе.
|
scheduleInfo/deadline |
string |
Дата окончания рассылки, например, 2024-09-10T16:29:30+0300. |
id |
string |
Уникальный идентификатор на стороне Партнёра.
Данный параметр нужен для контроля повторных отправок и дублирования
(сервис контроля включается отдельно).
Партнёр может вызывать Сервис-провайдера (запрос на отправку сообщения)
с одним и тем же id несколько раз. При этом: отправка сообщения абоненту
будет выполнена только один раз (по первому запросу).
В ответах на запросы Сервис-провайдер вернет Партнёру один и тот же
идентификатор сообщения в системе Сервис-провайдера (тот же, что на
первый запрос).
Сервис-провайдер опционально возвращает Партнёру данный идентификатор
при его наличии в отчёте о доставке сообщения.
|
destAddr |
string |
Номер телефона абонента. Содержит код страны, код оператора и номер телефона.
Для РФ код может быть „8“, „7“ или „+7“.
Примеры номеров: 72101234567, +72101234567, 8-210-123-45-67, 82101234567.
|
message |
object |
Параметры отправляемого сообщения. |
message/type |
enum |
Тип сообщения. Передается значение CARDSMOBILE. |
message/data |
object |
Параметры отправляемых данных. |
message/data/ttl |
integer |
Срок жизни сообщения. Допустимый диапазон, секунд: от 30 до 86400.
Примечания. При ttl = 0 или отсутствии параметра в запросе берётся значение
из настроек по умолчанию, которые задаются при настройке интеграции отдельно
для каждого клиента.
Если ttl не указан в данных местах, то запрос будет отклонён
системой и будет выведена ошибка.
|
message/data/ttlUnit |
enum |
Единица измерения периода доставки сообщения. Передается только вместе
с ttl.
Допустимые значения:
|
message/data/serviceNumber |
string |
Сервисное имя, от которого осуществляется отправка сообщения.
Для сообщений с типом CardsMobile данный параметр не является обязательным.
Если в запросе данный параметр не передан, то берется значение из настроек
интеграции.
Также, если в настройках нет значения данного параметра,
то будет использоваться сервисное имя “CARDSMOBILE“.
|
message/data/text |
string |
Текст отправляемого сообщения. Количество символов, не более: 150. |
message/data/title |
string |
Заголовок для текстового сообщения. Количество символов, не более: 50. |
message/data/target |
enum |
Текстовая константа для сообщений с типом CardsMobile.
Определяет экран приложения, к которому должен быть осуществлен переход
при нажатии на сообщение.
Возможные значения:
Значение по умолчанию: card. |
message/data/campaignId |
string |
Текстовый идентификатор промо-акции для перехода.
Обязателен, если target=campaign.
Указывается ID акции в системе партнера или в Личном кабинете партнера
в системе «Кошелёк для бизнеса».
Количество символов, не более: 128.
|
message/data/pushType |
enum |
Текстовая константа для сообщений с типом CardsMobile.
Определяет тип трафика, присвоенный сообщению партнером.
Возможные значения:
|
message/data/content |
object |
Параметры для отправки изображений. |
message/data/content/ contentCategory |
enum |
Категория содержимого по ссылке contentUrl.
Возможное значение: IMAGE – для передачи в contentUrl ссылки
на изображение.
|
message/data/content/contentUrl |
string |
URL-адрес изображения. Максимальная длина ссылки, символов: 512.
Требования к изображению:
|
registeredDelivery |
integer |
Необходимость отчётов о доставке.
Возможные значения:
|
notifyUrl |
string |
Hostname входящего api для получения отчета о доставке (см.
Сервис получения статусов доставки сообщений).
Этот параметр в запросе необязательный, но при его отправке нужно учесть
следующее:
При невыполнении любого из указанных условий будет сгенерирована ошибка,
запрос не будет выполнен.
|
Ответ на запрос#
После отправки сообщения Сервис-провайдер синхронно возвращает ответ. В случае успешной отправки возвращается HTTP-code 200 OK.
Ответ при успешной отправке#
1 {
2 "mtNum": "7390612217"
3 "id": "8770599"
4 }
Параметр |
Тип данных |
Описание |
---|---|---|
mtNum |
string |
Идентификатор цепочки отправки, присваиваемый платформой Сервис-провайдера. |
id |
string |
Уникальный идентификатор на стороне Партнёра. Присутствует, если был передан при отправке. |
Ошибки при отправке#
Для ошибочных результатов HTTP-код ответа будет отличный от 200 (см. Коды ошибок отправки).
1 {
2 "error": {
3 "code": 1,
4 "description": "Service is unavailable"
5 }
6 }
Параметр |
Тип данных |
Описание |
---|---|---|
error |
object |
Информация об ошибке. |
error/code |
int |
Код ошибки. |
error/description |
string |
Краткое описание ошибки. |
extendedDescription |
string |
Подробное описание ошибки (необязательный параметр). |
Коды ошибок отправки#
Код |
Описание |
HTTP-код |
---|---|---|
1 |
Service is unavailable |
503 |
2 |
Invalid IP-address |
403 |
3 |
Too many connections |
429 |
4 |
Invalid request |
400 |
5 |
Invalid login |
401 |
6 |
Invalid password |
401 |
7 |
serviceNumber is not defined |
400 |
8 |
destAddr is not correct |
406 |
9 |
Message type is not correct |
406 |
10 |
Prohibited sending duplicates |
409 |
11 |
Invalid TTL |
406 |
100 |
100 |
500 |
Статусы доставки сообщений CardsMobile#
Для получения статусов сообщений CardsMobile необходимо настроить Сервис получения статусов доставки сообщений.