Описание API SmartPush

Push-уведомления отправляются только по заранее согласованному шаблону. Подробнее в разделе Шаблон уведомлений.

Формат запроса

Для вызова метода SmartPush вы должны быть авторизованы. Все запросы необходимо отправлять на URL:

https://salute.online.sberbank.ru:9443/api/v2/smartpush/apprequest

Тип запроса: POST application/JSON.

SCOPE для доступа при запросе access_token = SMART_PUSH.

Ограничения

Сервис устанавливает ограничения на отправку уведомлений в разрезе времени и пользователей:

  • Общее количество сообщений за минуту, час или сутки.
  • Количество сообщений уникальному пользователю за минуту, час или сутки.

Лимиты устанавливаются в зависимости от потребностей смартапа и по согласованию с модераторами.

Параметры заголовка

Параметр Описание

RqUID

Обязательное

string

Уникальный UID запроса

Authorization

Обязательное

string

Авторизационные данные. Необходимо в поле указать «Bearer» и через пробел access_token

callbackUrl

string

URL для доставки статусов уведомлений

Параметры тела запроса


Поле Описание
requestPayload

Обязательное

object

Объект с телом запроса


protocolVersion

Обязательное

string (16)

Версия протокола


messageId

Обязательное

long

Идентификатор клиентского сообщения в рамках сессии

messageName

string (64)

Тип сообщения — SEND_PUSH

payload

Обязательное

object

Бизнес параметры

sender

Обязательное

object

Информация об отправителе

projectId

Обязательное

string

Идентификатор проекта или смартапа в SmartMarket Studio.
Например: 3fa85f64-5717-4562-b3fc-2c963f66afa6

application

object

Информация о приложении

appId

Обязательное

string

Идентификатор смартапа.
Например: 3fa85f64-5717-4562-b3fc-2c963f66afa7

versionId

Обязательное

string

Идентификатор версии смартапа.
Например: fcac2f61-57a7-4d6d-b3fc-2c963f66a111

recipient

Обязательное

object

Информация о получателе

clientId

Обязательное

object

Информация о клиенте

idType

Обязательное

string (256)

Тип идентификатора клиента. Принимает значение SUB

id

Обязательное

string (256)

Идентификатор клиента. Длина не менее 16 символов.
Например: NAHUI2424BNKBK23432423KKKBKJ45345HK345HK34G5K34G5K34

deliveryConfig

object

Настройки доставки

deliveryMode

Обязательное

string

Тип доставки:
• broadcast — отправка на все устройства;
• sequential — отправка на устройства или мобильное приложение в зависимости от приоритета

destinations

Обязательное

list

Настройки получателя

channel

Обязательное

string (128)

Канал получателя. Например: B2C

surface

Обязательное

string (128)

Поверхность получателя. Например: COMPANION

templateContent

object

Содержимое настроек для получателя под текущим номером

id

Обязательное

string (36)

Идентификатор шаблона

headerValues

object

Переменные заголовка push-уведомления для подстановки в шаблон

bodyValues

object

Переменные текста push-уведомления для подстановки в шаблон

mobileAppParameters

object

Блок с параметрами для отправки в мобильное приложение Салют

deeplinkAndroid

string (350)

Сценарий для Android-устройств

deeplinkIos

string (350)

Сценарий для iOS-устройств

timeFrame

object

Настройки времени для отложенной отправки push-уведомления под текущим номером. Дата и время передаются в формате ISO

startTime

Обязательное

string

Стартовое время отправки push-уведомления. Например: 13:30:00

finishTime

Обязательное

string

Финальное время отправки push-уведомления. Передается в формате hh:mm:ss. Если endDate превышает текущий день, а finishTime превышает текущее время, то уведомление не отправится

timeZone

Обязательное

string

Часовой пояс пользователя в формате GMT+hh:mm (если известен). Можно указать этот параметр, чтобы уведомления отправлялись в удобное для пользователя время

startDate

Обязательное

string

Стартовая дата отправки push-уведомления. Передается в формате yyyy-mm-dd. Например: 2020-06-04

endDate

string (30)

Финальная дата отправки push-уведомления. Передается в формате yyyy-mm-dd. При отсутствии подставляется дата из startDate

Пример тела запроса

{
	"requestPayload": {
		"protocolVersion": "V1",
		"messageId": 37284759,
		"messageName": "SEND_PUSH",
		"payload": {
			"sender": {
				"projectId": "3fa85f64-5717-4562-b3ab-2c963f66baa6",
				"application": {
					"appId": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
					"versionId": "fcac2f61-57a7-4d6d-b3fc-2c963f66a111"
				}
			},
			"recipient": {
				"clientId": {
					"idType": "SUB",
					"id": "6852d76cea737bb751f89e82523a2d97f9765c0d7b8a6eaf821497c1b17df87ba3028e64eea639f7"
				}
			},
			"deliveryConfig": {
				"deliveryMode": "BROADCAST",
				"destinations": [{
						"channel": "COMPANION_B2C",
						"surface": "COMPANION",
						"templateContent": {
							"id": "49061553-27c7-4471-9145-d8d6137657da",
							"headerValues": {
								"clientname": "Иван",
								"bandname": "Ласковый май"
							},
							"bodyValues": {
								"formatname": "альбома",
								"bandname": "\"Ласковый май\"",
								"releasename": "\"Новое\""
							},
							"mobileAppParameters": {
								"deeplinkAndroid": "laskoviyi-mai-listen-android",
								"deeplinkIos": "laskoviyi-mai-listen-ios"
							},
							"timeFrame": {
								"startTime": "13:30:00",
								"finishTime": "15:00:00",
								"timeZone": "GMT+03:00",
								"startDate": "2020-06-04",
								"endDate": "2020-06-05"
							}
						}
					},
					{
						"channel": "B2C",
						"surface": "STARGATE",
						"templateContent": {
							"id": "49061553-27c7-4471-9145-d8d6137657da",
							"headerValues": {
								"clientname": "Иван",
								"bandname": "Ласковый май"
							},
							"bodyValues": {
								"formatname": "альбома",
								"bandname": "\"Ласковый май\"",
								"releasename": "\"Новое\""
							}
						}
					}
				]
			}
		}
	}
}

Формат ответа

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

Поле Описание
requestId

string $uuid (36)

Идентификатор запроса, переданный клиентом

responseId

string $uuid (36)

Идентификатор ответа сервера

timeStamp

string $date-time (30)

Время формирования ответа

payload

object

Блок с деталями ответа. Возвращается при успешном ответе

messageId

long

Идентификатор клиентского сообщения в рамках сессии

messageName

string (64)

Идентификатор ответа сервера

protocolVersion

string

Версия протокола. Например: V1

validation

string

Бизнес параметры

code

integer

Код ответа (HTTP)

errors

list

Блок с деталями ответа. Возвращается при неуспешном ответе


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

{
  	"requestId": "2fbe6e9f-35ad-44fe-ab4f-dde88b76bd49",
  	"responseId": "536c56a9-5a9a-4862-aff6-fc03ea85df93",
    "timestamp": "2020-02-20T19:30:15Z",
  	"payload": 
	{
		"messageId": 1111111111111,
		"messageName": "PUSH_RESULT",
		"protocolVersion": "V1",
		"validation": {
			"results": [{
				"status": {
					"code": 0,
					"descr": "ok"
				},
				"surface": "COMPANION"
			}]
		}
	}
}

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

{
  "requestId": "123e4567-e89b-12d3-a456-426614174333",
  "responseId": "123e4567-e89b-12d3-a456-426614174000",
  "timeStamp": "2020-02-20T19:30:15Z",
  "code": 400,
  "errors": [
    {
      "key": "AB127",
      "message": "Error!"
    }
  ]
}

Коды ответа

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

Код Описание

200

Запрос обработан успешно

400

Неверный формат запроса. Необходимо проверить поля на соответствие формату API

401

Ошибка авторизации. В ответе с таким кодом должен присутствовать заголовок «Authenticate: error="invalid_request"»

500

Необрабатываемые ошибки или внутренние ошибки подключения, доступности серверов, логики обработки

Коды ошибок

Код Значение Описание

0

Success

Успешно

1000

Schema validation error

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

1001

Message validation error

Ошибка в целостности данных входящего запроса (в одном уведомлении указаны блоки PushContent и TemplateContent, destination пустой, неправильные времена в start_time и finish_time или неправильный message_name)

1002

Client id type is invalid

Указан недопустимый тип clientId

1003

Delivery type error

Ошибка в параметрах типа отправки

1004

Unknown surface of channel

Нет указанного channel или указанного surface

1005

Surface is not defined

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

1006

Destination has both mobile app and device parameters

В блоке destination одновременно указаны блоки для мобильных поверхностей и устройств

1007

Unknown origin surface

Не определена поверхность из запроса

1008

Specified time validation error

Указано невалидное время

1009

Surface parameters error

Для отправки на мобильное приложение переданы параметры для устройства или наоборот

1012

Sub format is invalid

В запросе указан sub не по формату

1013

Sending notifications for this project/app forbidden

Для данного навыка не включена возможность отправлять push-уведомления

1014

Sending limit exceeded

Превышен лимит на отправку push-уведомлений (минутный, часовой или суточный)

1015

Device filters have both deviceSerialFilter and productFilter

В запросе на устройство одновременно заполнены deviceSerialFilter и productFilter

1016

Specified template for specified project does not exist

Указанный шаблон для данного projectId не существует

1017

Specified template params are invalid

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

1018

Client sending limit exceeded

Достигнут лимит на отправку push-уведомлений этому клиенту

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней