Перед подключением
Авторизация
В заголовке каждого запроса необходимо передавать токен API Key в следующем формате:
- Тип токена: JWT
- Имя заголовка: token
Подробнее о получении параметров авторизации в разделе Получение токена.
URL для запросов
Все запросы необходимо отправлять на следующий URL:
https://smartpay.devices.sberbank.ru/api/subscription-market/
Продление подписки
Продление подписки происходит автоматически без участия смартапа и пользователя. При наступлении даты очередного платежа сервис подписок инициирует списание средств с привязанной карты. Информация о результатах списания приходит в смартап в виде callback-уведомлений.
Отмена продления подписки
Для отмены продления подписки используйте метод DELETE /subscriptions/{id}
. Отмена означает, что автоматическое продление подписки отменится и, когда наступит дата продления, средства не спишутся с карты пользователя. По окончании текущего периода подписка будет закрыта и в смартап придет callback-уведомление с типом CLOSED.
Параметры заголовка
Поле | Описание | |
---|---|---|
token Обязательное |
Токен для авторизации запроса. Подробнее в разделе Получение токена | |
user_id Обязательное |
Блок с информацией о пользователе | |
encrypted_sub_id Обязательное |
Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub |
Параметры запроса
Параметр | Описание |
---|---|
Обязательное |
Идентификатор подписки. Совпадает со значением, которое приходит в ответе на запросы: |
Пример запроса
curl -X DELETE 'https://.../subscriptions/123'
-H 'token: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9…'
-H 'user_id: { "encrypted_sub_id": "123" }'
Параметры ответа
Поле | Описание |
---|---|
success |
Результат обработки запроса. Значения:
|
message |
Текстовое описание ошибки |
Пример ответа
{
"success": false,
"message": "Неизвестная ошибка"
}
Список подписок пользователя
Вы можете получить список активных и неактивных подписок пользователя. Для этого используйте метод GET /subscriptions
.
Параметры заголовка
Поле | Описание | |
---|---|---|
token Обязательное |
Токен для авторизации запроса. Подробнее в разделе Получение токена | |
user_id Обязательное |
Блок с информацией о пользователе | |
encrypted_sub_id Обязательное |
Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub |
Параметры запроса
Параметр | Описание |
---|---|
|
Идентификатор сервиса, который вы получили в письме о подключении подписок. Подробнее в разделе Доступ к подпискам |
|
Признак активности подписки: |
|
Фильтр по дате создания подписки — начало выборки. Передается в формате yyyy-mm-dd. Например: 2020-10-30 |
|
Фильтр по дате создания подписки — окончание выборки. Передается в формате yyyy-mm-dd. Например: 2020-11-30 |
|
Номер запрашиваемой страницы с результатами выборки подписок |
|
Количество записей на одной странице |
|
Параметр сортировки результата. Допустимые значения: |
Пример запроса
curl -X 'GET' 'https://.../subscriptions?serviceId=1&present=true&dateFrom=2021-03-24&dateTo=2021-03-25&page=0&size=20&sort=created%2CDESC' \
-H 'accept: /' \
-H 'token: eyJhbGciOiJIUzUxMiIsI…' \
-H 'user_id: { "encrypted_sub_id": "123" }'
Параметры ответа
Поле | Описание | |||
---|---|---|---|---|
success |
Результат обработки запроса. Значения:
| |||
message |
Текстовое описание ошибки | |||
body |
Блок с информацией о подписках | |||
content |
Список найденных подписок | |||
serviceName |
Наименование смартапа, к которому привязана подписка | |||
subscriptionId |
Идентификатор подписки пользователя | |||
addParameters |
Список дополнительных параметров, которые передавались в запросе на подключение подписки | |||
productId |
Идентификатор параметров подписки. Выдается при запросе доступа к подпискам | |||
productName |
Наименование подписки. Передается значение из заявки на получение доступа к подпискам | |||
productCode |
Код подписки. Передается значение из заявки на получение доступа к подпискам | |||
recurrent |
Признак автоматического продления подписки: | |||
countOfDay |
Количество дней, оставшихся до следу ющего регулярного платежа | |||
periodType |
Единица измерения продолжительности периода подписки: | |||
periodDuration |
Продолжительность периода подписки | |||
nextPaymentDate |
Дата следующего продления подписки. Указывается в формате yyyy-mm-dd | |||
price |
Стоимость периода подписки. Указывается в копейках: | |||
currency |
Валюта списания. По умолчанию возвращается значение RUB | |||
state |
Текущий статус подпи ски. Подробнее в разделе Статусы подписок | |||
currentPeriod |
Название текущего периода подписки: | |||
totalElements |
Общее количество найденных записей | |||
totalPages |
Количество страниц для отображения результатов | |||
number |
Номер текущей отображаемой страницы | |||
sort |
Информация о сортировке вывода результатов | |||
unsorted |
Признак сортировки списка: | |||
sorted |
Признак сортировки списка: | |||
empty |
Признак пустоты списка: | |||
size |
Количество найденных записей на странице | |||
numberOfElements |
Общее количество найденных записей | |||
first |
Признак первой страницы: | |||
last |
Признак последней страницы: |
Пример ответа
{
"success": false,
"message": "Неизвестная ошибка",
"body": {
"totalPages": 0,
"totalElements": 0,
"sort": {
"sorted": true,
"unsorted": true,
"empty": true
},
"first": true,
"number": 0,
"size": 0,
"content": [
{
"serviceName": "Фирма 1",
"subscriptionId": 100,
"addParameters": "{\"something\":\"unknown\"}",
"productId": 1,
"productType": "string",
"productName": "Тариф Middle",
"productCode": "Middle",
"recurrent": false,
"countOfDay": 10,
"periodType": "DAY | MONTH",
"periodDuration": 30,
"nextPaymentDate": "2021-03-23",
"price": 10000,
"currency": "RUB",
"state": "ACCEPTED | DEPOSITED | DECLINED | CANCELED | ACTIVATED | CLOSED | REPEATING | REFUNDED | ERROR",
"currentPeriod": "PROMO"
}
],
"numberOfElements": 0,
"last": true
}
}
Информация об одной подписке
Вы можете получить информацию по конкретной подписке пользователя. Для этого используйте метод GET /subscriptions/{id}
.
Параметры заголовка
Поле | Описание | |
---|---|---|
token Обязательное |
Токен для авторизации запроса. Подробнее в разделе Получение токена | |
user_id Обязательное |
Блок с информацией о пользователе | |
encrypted_sub_id Обязательное |
Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub |
Параметры запроса
Параметр | Описание |
---|---|
|
Идентификатор подписки. Совпадает со значением, которое приходит в ответе на запросы: |
Пример запроса
curl -X GET 'https://.../subscriptions/123'
-H 'token: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9…'
-H 'user_id: {"encrypted_sub_id": "123"}'
Параметры ответа
Поле | Описание | |
---|---|---|
success |
Результат обработки запроса. Значения:
| |
message |
Текстовое описание ошибки | |
body |
Блок с информацией о подписках | |
serviceName |
Наименование смартапа, к которому привязана подписка | |
subscriptionId |
Идентификатор подписки пользователя | |
addParameters |
Список дополнительных параметров, которые передавались в запросе на подключение подписки | |
productId |
Идентификатор параметров подписки. Выдается при запросе доступа к подпискам | |
productName |
Наименование подписки. Передается значение из заявки на получение доступа к подпискам | |
productCode |
Код подписки. Передается значение из заявки на получение доступа к подпискам | |
recurrent |
Признак автоматического продления подписки: | |
countOfDay |
Количество дней, оставшихся до следующего регулярного платежа | |
periodType |
Единица измерения продолжительности периода подписки: | |
periodDuration |
Продолжительность периода подписки | |
nextPaymentDate |
Дата следующего продления подписки. Указывается в формате yyyy-mm-dd | |
price |
Стоимость периода подписки. Указывается в копейках: | |
currency |
Валюта списания. По умолчанию возвращается значение RUB | |
state |
Текущий статус подписки. Подробнее в разделе Статусы подписок | |
currentPeriod |
Название текущего периода подписки: | |
description |
Описание подписки. Передается значение из заявки на получение доступа к подпискам |
Пример ответа
{
"success": true,
"message": "",
"body": {
"serviceName": "Фирма 1",
"subscriptionId": 100500,
"addParameters": "{\"something\":\"unknown\"}",
"productId": 1,
"productType": "string",
"productName": "Тариф Middle",
"productCode": "Middle",
"recurrent": false,
"countOfDay": 10,
"periodType": "DAY | MONTH",
"periodDuration": 30,
"nextPaymentDate": "2021-03-23",
"price": 10000,
"currency": "RUB",
"state": "NEW | ACCEPTED | DEPOSITED | DECLINED | CANCELED | ACTIVATED | CLOSED | REPEATING | REFUNDED | ERROR",
"currentPeriod": "PROMO",
"description": "Тариф Middle — базовое предложение..."
}
}
Коды ошибок
Код | Описание |
---|---|
400 | Некорректный запрос. Например: • в запросе отсутствует авторизационный токен смартапа, • указан некорректный идентификатор пользователя («Invalid user_id header received»), • токену смартапа не предоставлены права на запрашиваемый ресур с, • токен недействителен («The Token has expired on dd.mm.yyyy») |
403 | Запрещенная операция. Например, некорректно заполнен параметр encrypted_sub_id или сервису не удалось расшифровать sub_id |
404 | Данные не найдены |
502 | Недоступен сетевой шлюз или ошибка на стороне сервиса подписок |