Отправка уведомлений SmartPush

Обновлено 16 ноября 2023

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

Для вызова метода SmartPush вы должны быть авторизованы.

Виды запросов:

• Базовый — простая отправка push-уведомления.
• Расширенный — отправка уведомления с дополнительными функциями: отложенная отправка, отправка на все устройства и т. д.

Ограничения

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

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

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

Базовый запрос

URL для отправки базового запроса:

https://ngw.devices.sberbank.ru:9443/api/v2/smartpush/apprequest-lite

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

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

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

Параметр	Описание
RqUID Обязательное	string Уникальный UID запроса
Authorization Обязательное	string Авторизационные данные. Необходимо в поле указать «Bearer» и через пробел access_token
callbackUrl	string URL для доставки статусов уведомлений

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

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

projectId required	string Идентификатор проекта или смартапа в SmartMarket Studio
clientId required	string Уникальный идентификатор клиента. Соответствует полю sub в запросах ассистента
surface required	string Enum: "COMPANION" "SBERBOX" "STARGATE" "SATELLITE" "TIME" "TV_HUAWEI" "TV" Поверхность отправки уведомления. Возможные значения: COMPANION — мобильное приложение Салют; SBERBOX — SberBox; STARGATE — SberPortal; SATELLITE — SberBox Top; TIME — SberBox Time; TV_HUAWEI — Huawei Vision; TV — Салют ТВ.
required	object Параметры шаблона

{

• "projectId": "83cdd6c6-757a-42ce-b4fe-03912fb7d6e1",
• "clientId": "1596f2a624c003fdb31eb5000e49f1efe8ccf51fd0001f9b499c5881cdca1d95d24e4bf802c48fe0",
• "surface": "COMPANION",
• "templateContent": {

  • "id": "49061553-27c7-4471-9145-d8d6137657da",
  • "headerValues": {

    • "clientname": "Иван",
    • "bandname": "Ласковый май"

    },
  • "bodyValues": {

    • "formatname": "альбома",
    • "bandname": "Ласковый май",
    • "releasename": "Новое"

    }

  }

}

projectId required	string Идентификатор проекта или смартапа в SmartMarket Studio
clientId required	string Уникальный идентификатор клиента. Соответствует полю sub в запросах ассистента
surface required	string Enum: "COMPANION" "SBERBOX" "STARGATE" "SATELLITE" "TIME" "TV_HUAWEI" "TV" Поверхность отправки уведомления. Возможные значения: COMPANION — мобильное приложение Салют; SBERBOX — SberBox; STARGATE — SberPortal; SATELLITE — SberBox Top; TIME — SberBox Time; TV_HUAWEI — Huawei Vision; TV — Салют ТВ.
required	object Параметры шаблона

{

• "projectId": "83cdd6c6-757a-42ce-b4fe-03912fb7d6e1",
• "clientId": "1596f2a624c003fdb31eb5000e49f1efe8ccf51fd0001f9b499c5881cdca1d95d24e4bf802c48fe0",
• "surface": "COMPANION",
• "templateContent": {

  • "id": "49061553-27c7-4471-9145-d8d6137657da",
  • "headerValues": {

    • "clientname": "Иван",
    • "bandname": "Ласковый май"

    },
  • "bodyValues": {

    • "formatname": "альбома",
    • "bandname": "Ласковый май",
    • "releasename": "Новое"

    }

  }

}

Расширенный запрос

Если вы хотите автоматически отправлять уведомления по расписанию, получать информацию о статусе доставки и т. д., используйте расширенный запрос.

URL для отправки расширенного запроса:

https://ngw.devices.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 для доставки статусов уведомлений

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

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

protocolVersion required	string <= 16 characters Формат протокола
messageId required	integer <int32> Идентификатор клиентского сообщения в рамках сессии
messageName	string <= 64 characters Тип сообщения Value: "SEND_PUSH"
required	object Бизнес параметры

{

• "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"

            }

          }

        }

      ]

    }

  }

}

protocolVersion required	string <= 16 characters Формат протокола
messageId required	integer <int32> Идентификатор клиентского сообщения в рамках сессии
messageName	string <= 64 characters Тип сообщения Value: "SEND_PUSH"
required	object Бизнес параметры

{

• "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"

            }

          }

        }

      ]

    }

  }

}

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

200 Успешный ответ

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

requestId	string <= 36 characters Идентификатор запроса, переданный клиентом
responseId	string <= 36 characters Идентификатор ответа сервера
timestamp	string <date-time> <= 30 characters Время формирования ответа
code	integer HTTP-код ответа
	object Полезная нагрузка успешного ответа

{

• "requestId": "2fbe6e9f-35ad-44fe-ab4f-dde88b76bd49",
• "responseId": "536c56a9-5a9a-4862-aff6-fc03ea85df93",
• "timestamp": "2020-02-20T19:30:15Z",
• "code": 200,
• "payload": {

  • "messageId": 1111111111111,
  • "messageName": "PUSH_RESULT",
  • "protocolVersion": "V1",
  • "validation": {

    • "results": [

      • {

        • "status": {

          • "code": 0,
          • "descr": "Success"

          },
        • "surface": "COMPANION"

        }

      ]

    }

  }

}

requestId	string <= 36 characters Идентификатор запроса, переданный клиентом
responseId	string <= 36 characters Идентификатор ответа сервера
timestamp	string <date-time> <= 30 characters Время формирования ответа
code	integer HTTP-код ответа
	object Полезная нагрузка успешного ответа

{

• "requestId": "2fbe6e9f-35ad-44fe-ab4f-dde88b76bd49",
• "responseId": "536c56a9-5a9a-4862-aff6-fc03ea85df93",
• "timestamp": "2020-02-20T19:30:15Z",
• "code": 200,
• "payload": {

  • "messageId": 1111111111111,
  • "messageName": "PUSH_RESULT",
  • "protocolVersion": "V1",
  • "validation": {

    • "results": [

      • {

        • "status": {

          • "code": 0,
          • "descr": "Success"

          },
        • "surface": "COMPANION"

        }

      ]

    }

  }

}

400 Ошибка

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

requestId	string <= 36 characters Идентификатор запроса, переданный клиентом
responseId	string <= 36 characters Идентификатор ответа сервера
timestamp	string <date-time> <= 30 characters Время формирования ответа
code	integer HTTP-код ответа
	Array of objects[ items ] Блок с деталями ответа. Возвращается при неуспешном ответе

{

• "requestId": "2fbe6e9f-35ad-44fe-ab4f-dde88b76bd49",
• "responseId": "536c56a9-5a9a-4862-aff6-fc03ea85df93",
• "timestamp": "2020-02-20T19:30:15Z",
• "code": 400,
• "errors": [

  • {

    • "key": "AB127",
    • "message": "Error!"

    }

  ]

}

requestId	string <= 36 characters Идентификатор запроса, переданный клиентом
responseId	string <= 36 characters Идентификатор ответа сервера
timestamp	string <date-time> <= 30 characters Время формирования ответа
code	integer HTTP-код ответа
	Array of objects[ items ] Блок с деталями ответа. Возвращается при неуспешном ответе

{

• "requestId": "2fbe6e9f-35ad-44fe-ab4f-dde88b76bd49",
• "responseId": "536c56a9-5a9a-4862-aff6-fc03ea85df93",
• "timestamp": "2020-02-20T19:30:15Z",
• "code": 400,
• "errors": [

  • {

    • "key": "AB127",
    • "message": "Error!"

    }

  ]

}

Коды ответа HTTP

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

Код	Описание
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 одновременно указаны блоки для мобильных поверхностей и устройств
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	Превышен минутный, часовой или суточный лимит на отправку уведомлений
1015 Device filters have both deviceSerialFilter and productFilter	В запросе для отправки уведомления на устройство одновременно заполнены deviceSerialFilter и productFilter
1016 Specified template for specified project does not exist	В проекте нет такого шаблона
1017 Specified template params are invalid	Параметры запроса не соответствуют шаблону
1018 Client sending limit exceeded	Достигнут лимит на отправку push-уведомлений этому клиенту