ym88659208ym87991671
Управление подписками в SmartPay | Документация SmartMarket
Skip to main content

Управление подписками

Перед подключением

Авторизация

В заголовке каждого запроса необходимо передавать токен API Key в следующем формате:

  • Тип токена: JWT
  • Имя заголовка: token

Подробнее о получении параметров авторизации в разделе Получение токена.

URL для запросов

Все запросы необходимо отправлять на следующий URL:

https://smartmarket.online.sberbank.ru/api/subscription-market/

Продление подписки

Продление подписки происходит автоматически без участия смартапа и пользователя. При наступлении даты очередного платежа сервис подписок инициирует списание средств с привязанной карты. Информация о результатах списания приходит в смартап в виде callback-уведомлений.

Отмена продления подписки

Для отмены продления подписки используйте метод DELETE /subscriptions/{id}. Отмена означает, что автоматическое продление подписки отменится и, когда наступит дата продления, средства не спишутся с карты пользователя. По окончании текущего периода подписка будет закрыта и в смартап придет callback-уведомление с типом CLOSED.


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


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

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

string

Токен для авторизации запроса. Подробнее в разделе Получение токена

user_id

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

object

Блок с информацией о пользователе


encrypted_sub_id

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

string

Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub


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


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

id

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

numeric

Идентификатор подписки. Совпадает со значением, которое приходит в ответе на запросы:
POST /v2/subscriptions — параметр orderId
GET /subscriptions — параметр subscriptionId


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

curl -X DELETE 'https://.../subscriptions/123'
-H 'token: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9…'
-H 'user_id: { "encrypted_sub_id": "123" }'

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


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

boolean

Результат обработки запроса. Значения:

  • true — данные получены
  • false — данные не получены
message

string

Текстовое описание ошибки

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

{
"success": false,
"message": "Неизвестная ошибка"
}

Список подписок пользователя

Вы можете получить список активных и неактивных подписок пользователя. Для этого используйте метод GET /subscriptions.


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


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

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

string

Токен для авторизации запроса. Подробнее в разделе Получение токена

user_id

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

object

Блок с информацией о пользователе


encrypted_sub_id

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

string

Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub


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


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

serviceId

numeric

Идентификатор сервиса, который был выдан смартапу вместе с токеном авторизации. Подробнее в разделе Получение токена

present

boolean

Признак активности подписки:
• true — вернутся активные подписки в статусах DEPOSITED, ACTIVATED, REPEATING, CONNECT_TO_PROVIDER
• false — вернутся неактивные подписки в статусах ACCEPTED, CLOSED, CANCELLED, REFUNDED, DECLINED, ERROR

Подробнее о статусах в разделе Статусы подписок

dateFrom

string

Фильтр по дате создания подписки — начало выборки. Передается в формате yyyy-mm-dd. Например: 2020-10-30

dateTo

string

Фильтр по дате создания подписки — окончание выборки. Передается в формате yyyy-mm-dd. Например: 2020-11-30

page

string

Номер запрашиваемой страницы с результатами выборки подписок

size

numeric

Количество записей на одной странице

sort

string

Параметр сортировки результата. Допустимые значения:
• ASC — по возрастанию
• DESC — по убыванию
Пример передачи параметра: sort=created, DESC


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

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

boolean

Результат обработки запроса. Значения:

  • true — данные получены
  • false — данные не получены
message

string

Текстовое описание ошибки

body

object

Блок с информацией о подписках


content

array

Список найденных подписок



serviceName

string

Наименование смартапа, к которому привязана подписка



subscriptionId

numeric

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



addParameters

object

Список дополнительных параметров, которые передавались в запросе на подключение подписки



productId

numeric

Идентификатор параметров подписки. Выдается при запросе доступа к подпискам



productName

string

Наименование подписки. Передается значение из заявки на получение доступа к подпискам



productCode

string

Код подписки. Передается значение из заявки на получение доступа к подпискам



recurrent

boolean

Признак автоматического продления подписки:
• true — подписка продлевается автоматически (по умолчанию)
• false — подписка отменяется после истечения первого периода или при отмене



countOfDay

numeric

Количество дней, оставшихся до следующего регулярного платежа



periodType

string

Единица измерения продолжительности периода подписки:
• DAY — дни
• MONTH — месяцы



periodDuration

numeric

Продолжительность периода подписки



nextPaymentDate

string

Дата следующего продления подписки. Указывается в формате yyyy-mm-dd



price

numeric

Стоимость периода подписки. Указывается в копейках:
• Если есть PROMO период — цена 0
• Если нет PROMO, но есть START — цена стартового периода
• Если предусмотрен только STANDARD — цена стандартного периода



currency

string

Валюта списания. По умолчанию возвращается значение RUB



state

string

Текущий статус подписки. Подробнее в разделе Статусы подписок



currentPeriod

string

Название текущего периода подписки:
• PROMO — бесплатный
• START — с пониженной стоимостью
• STANDARD — период по умолчанию, действует до конца подписки


totalElements

numeric

Общее количество найденных записей


totalPages

numeric

Количество страниц для отображения результатов


number

numeric

Номер текущей отображаемой страницы


sort

object

Информация о сортировке вывода результатов



unsorted

boolean

Признак сортировки списка:
• true — список не отсортирован
• false — список отсортирован



sorted

boolean

Признак сортировки списка:
• true — список отсортирован
• false — список не отсортирован



empty

boolean

Признак пустоты списка:
• true — список пустой, параметр sort не передавался в запросе
• false — список непустой


size

numeric

Количество найденных записей на странице


numberOfElements

numeric

Общее количество найденных записей


first

boolean

Признак первой страницы:
• true — получена информация с первой страницы
• false — получена информация не с первой страницы


last

boolean

Признак последней страницы:
• true — получена информация с последней страницы
• false — получена информация не с последней страницы


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


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

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

string

Токен для авторизации запроса. Подробнее в разделе Получение токена

user_id

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

object

Блок с информацией о пользователе


encrypted_sub_id

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

string

Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub


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


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

id

numeric

Идентификатор подписки. Совпадает со значением, которое приходит в ответе на запросы:
POST /v2/subscriptions — параметр orderId
GET /subscriptions — параметр subscriptionId


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

curl -X GET 'https://.../subscriptions/123'
-H 'token: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9…'
-H 'user_id: {"encrypted_sub_id": "123"}'

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


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

boolean

Результат обработки запроса. Значения:

  • true — данные получены
  • false — данные не получены
message

string

Текстовое описание ошибки

body

object

Блок с информацией о подписках


serviceName

string

Наименование смартапа, к которому привязана подписка


subscriptionId

numeric

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


addParameters

object

Список дополнительных параметров, которые передавались в запросе на подключение подписки


productId

numeric

Идентификатор параметров подписки. Выдается при запросе доступа к подпискам


productName

string

Наименование подписки. Передается значение из заявки на получение доступа к подпискам


productCode

string

Код подписки. Передается значение из заявки на получение доступа к подпискам


recurrent

boolean

Признак автоматического продления подписки:
• true — подписка продлевается автоматически (по умолчанию)
• false — подписка отменяется после истечения первого периода или при отмене


countOfDay

numeric

Количество дней, оставшихся до следующего регулярного платежа


periodType

string

Единица измерения продолжительности периода подписки:
• DAY — дни
• MONTH — месяцы


periodDuration

numeric

Продолжительность периода подписки


nextPaymentDate

string

Дата следующего продления подписки. Указывается в формате yyyy-mm-dd


price

numeric

Стоимость периода подписки. Указывается в копейках:
• Если есть PROMO период — цена 0 или 100
• Если нет PROMO, но есть START — цена стартового периода
• Если предусмотрен только STANDARD — цена стандартного периода


currency

string

Валюта списания. По умолчанию возвращается значение RUB


state

string

Текущий статус подписки. Подробнее в разделе Статусы подписок


currentPeriod

string

Название текущего периода подписки:
• PROMO — бесплатный
• START — с пониженной стоимостью
• STANDARD — период по умолчанию, действует до конца подписки
• GRACE — период повторных попыток списания с карты пользователя в случае неуспешной оплаты при продлении подписки. В течение периода контент не блокируется
• HOLD — период повторных попыток списания с карты пользователя в случае неуспешной оплаты при продлении подписки. В течение периода контент блокируется


description

string

Описание подписки. Передается значение из заявки на получение доступа к подпискам


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


{
"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Недоступен сетевой шлюз или ошибка на стороне сервиса подписок
Обновлено 27 апреля 2022

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

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