Если вы принимаете платежи в смартапе, то вы можете получать информацию по реализованным товарам и услугам. Сделать это можно через SmartStore — сервис управления товарами смартапа. SmartStore является частью сервиса приема платежей SmartPay, поэтому для его использования достаточно создать смартап и получить токен для SmartPay.
Пока SmartStore предоставляет API только для получения информации о купленных товарах. В дальнейшем возможности сервиса будут расширяться.
Перед использованием
Авторизация
В сервисе SmartStore можно авторизоваться по эксплуатационному токену от SmartPay. Токен передается в заголовке каждого запроса:
Тип токена: Bearer
Имя заголовка: Authorization
Подробнее о параметрах авторизации смотрите в разделе Проект SmartPay.
URL для запросов
Все запросы к SmartStore необходимо отправлять на следующий URL:
https://smartpay.devices.sberbank.ru/api/smart-store/items
Список купленных товаров
Вы можете получить информацию о купленных товарах, если:
- при оплате из смартапа был указан идентификатор пользователя user_id;
- купленные товары перешли в статус confirmed (id=0).
Получить информацию о купленных товарах можно по идентификатору пользователя, идентификатору смартапа и коду товара. Если был частичный возврат, вы получите информацию только по тем товарам, что остались у клиента.
Список купленных товаров формируется из корзины, которая передается в запросах к SmartPay:
- для SmartApp API — при создании счета (POST /invoices);
- для Code — при формировании корзины ($payment.addItem);
- для Graph — при добавлении товара в счет ($payment.addItem).
Информация по всем товарам
Метод GET /items возвращает информацию по всем товарам, которые пользователь купил внутри смартапа. Информация возвращается в виде списка, к которому можно применить постраничную выгрузку и сортировку.
Параметры заголовка
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
| user_id | object | Да | Блок с информацией о пользователе |
| encrypted_sub_id | string | Да | Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub |
Параметры запроса
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
| page | numeric | Нет | Номер страницы. Передается, если необходимо получить информацию с определенной страницы вывода результатов |
| size | numeric | Нет | Количество записей на одной странице |
| sort | string | Нет | Параметр сортировки результата. Допустимые значения: • ASC (по возрастанию) • DESC (по убыванию) Пример передачи параметра: sort=item_code, DESC При передаче в строке запроса символ «,» должен экранироваться: sort=item_code%2CDESC |
Пример запроса
curl -X GET "http://................./items?page=1&size=20&sort=item_code%2CDESC"
-H "accept: application/json"
-H "authorization: Bearer $BEARER_TOKEN"
-H "user_id: {"encrypted_sub_id": "wE8B12AKT5tbzBOFSM+wk8kK0Xzh/i8J2WRZvP+39b+uv…………"}"
Параметры ответа
| Название | Тип | Описание |
|---|---|---|
| success | boolean | Результат обработки запроса. Значения: • true — данные получены • false — данные не получены |
| message | string | Текстовое описание ошибки |
| body | object | Блок с результатом поиска |
| content | list | Список найденных покупок с характеристиками |
| item_code | string | Код товара. Возвращается то же значение, что было передано при регистрации заказа |
| quantities | object | Информация о количестве купленных товаров |
| quantity_value | numeric | Количество купленных товаров |
| quantity_measure | string | Единицы товара. Например: шт., кг и пр. |
| image_url | string | Ссылка на логотип товара. Берется последнее значение, которое было передано при регистрации заказа |
| 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": true,
"message": "",
"body": {
"totalElements": 0,
"totalPages": 0,
"number": 0,
"sort": {
"unsorted": true,
"sorted": false,
"empty": false
},
"size": 0,
"content": [
{
"item_code": "com.MashaAndTheBear.HairSalon.crystal100",
"quantities": [
{
"quantity_value": 3.5,
"quantity_measure": "кг"
}
],
"image_url": "https://developers.sber.ru/docs/img/fork-page/assistant-salute-grey.png"
}
],
"pageable": {
"sort": {
"unsorted": true,
"sorted": false,
"empty": false
},
"offset": 0,
"pageNumber": 1,
"pageSize": 1,
"paged": true,
"unpaged": false
},
"numberOfElements": 0,
"first": true,
"last": false,
"empty": false
}
}
Информация по товару
Метод GET /items/{code} возвращает информацию о конкретном товаре, который пользователь купил внутри смартапа.
Параметры заголовка
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
| user_id | object | Да | Блок с информацией о пользователе |
| encrypted_sub_id | string | Да | Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub |
Параметры запроса
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
| code | string | Да | Код товара (item_code), по которому необходимо получить информацию |
Пример запроса
curl -X GET "http://............/items/com.MashaAndTheBear.HairSalon.crystal100"
-H "accept: application/json"
-H "authorization: Bearer $BEARER_TOKEN"
-H "user_id: { "encrypted_sub_id": "wE8B12AKT5tbzBOFSM+wk8kK0Xzh……."}"
Параметры ответа
| Название | Тип | Описание |
|---|---|---|
| success | boolean | Результат обработки запроса. Значения: • true — данные получены • false — данные не получены |
| message | string | Текстовое описание ошибки |
| body | object | Блок с результатом поиска |
| item_code | string | Код товара. Возвращается то же значение, что было передано при регистрации заказа |
| quantities | object | Информация о количестве купленных товаров |
| quantity_value | numeric | Количество купленных товаров |
| quantity_measure | string | Единицы товара. Например: шт., кг и пр. |
| image_url | string | Ссылка на логотип товара. Берется последнее значение, которое было передано при регистрации заказа |
Пример ответа
{
"success": true,
"message": "",
"body": {
"item_code": "com.MashaAndTheBear.HairSalon.crystal100",
"quantities": [
{
"quantity_value": 3.5,
"quantity_measure": "кг"
}
],
"image_url": "https://developers.sber.ru/docs/img/fork-page/assistant-salute-grey.png"
}
}
Коды ошибок
В ответ на каждый запрос могут возвращаться следующие коды ошибок:
| Код | Описание |
|---|---|
| 400 | Некорректный запрос. Например, в запросе отсутствует авторизационный токен смартапа или указан некорректный идентификатор пользователя («Invalid user_id header received») |
| 401 | Неавторизованный запрос. Например, токену смартапа не предоставлены права или токен недействителен («The Token has expired on dd.mm.yyyy») |
| 403 | Запрещенный запрос. Например, некорректно заполнен параметр encrypted_sub_id или сервису не удалось расшифровать sub_id |
| 502 | Сервис недоступен. Ошибка на стороне SmartStore |