REST API
Обзор
API реализовано в соответствии с протоколом JSONAPI.
Все методы API, кроме Token доступны только авторизованным пользователям. Для вызова этих методов необходимо отправлять HTTP заголовок, содержащий токен JWT:
Все данные следует передавать в кодировке utf-8.
Постраничная навигация
При запросе коллекции сущностей в /GET параметрах можно передать:
Номер и размер страницы соответственно. В ответе будут возвращены дополнительные блоки:
Сортировка
При запросе коллекции сущностей в /GET параметрах можно передать:
Он представляет собой json-массив объектов с условиями сортировки:
Параметр | Описание | Возможные значение |
attribute | Имя атрибута модели | |
direction | Направление сортировки | asc, desc |
Типы данных
Доступные типы данных:
Тип | Примечание |
String | Строка |
Int | Целое число |
Float | Дробное число. Используется разделитель точка. |
Boolean | Допустимые значения "Y", "N", "" (если нет данных) |
Object | Вложенная структура, в ней допустимы все перечисленные выше типы данных |
Ограничение нагрузки на REST API
В REST API действует ограничение на количество запросов с одного IP в единицу времени. При превышении лимита в 1000 запросов в минуту возвращается ошибка 429:
В случае получения такого сообщения клиент должен сделать паузу на 1 минуту и уменьшить частоту запросов.
Методы API
Токен
Получить токен
POST
https://api.loymaxsc.net/token
Метод для получения авторизационного токена. Токен необходим для выполнения запросов к API. Полученный токен отправляется в заголовке запроса: Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Query Parameters
Name | Type | Description |
---|---|---|
username* | string | Логин |
password* | boolean | Пароль |
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string | application/vnd.api+json или application/json |
Пример запроса:
Стоит учитывать, что токен имеет ограниченный срок действия - 1 час. Если он истёк, возвращается ошибка 401, и будет необходимо получить новый токен.
Клиент
Получить список клиентов
GET
https://api.loymaxsc.net/customer
Разрешено только для авторизованных пользователей с ролью API.
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string | application/vnd.api+json или application/json |
Authorization* | string | Bearer TOKEN |
Получить клиента
GET
https://api.loymaxsc.net/customer/:id
Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
id* | string | Идентификатор клиента в мастер-системе |
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string | application/vnd.api+json или application/json |
Authorization* | string | Bearer TOKEN |
Зарегистрировать клиента
POST
https://api.loymaxsc.net/customer
Метод для регистрации профиля клиента клиента по его идентификатору в мастер-системе. ВАЖНО: Повторный вызов запроса для уже имеющегося в базе local_id обновляет все поля. Поля, которые не передавались в запросе, будут обновлены пустыми значениями, либо значениями по умолчанию. Помимо явно перечисленных ниже параметров запрос также может содержать любые параметры, имеющиеся в решении и/или индивидуальной конфигурации пользователя платформы. Разрешено только для авторизованных пользователей с ролью API.
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Bearer TOKEN |
Content-Type* | string | application/json application/vnd.api+json |
Request Body
Name | Type | Description |
---|---|---|
local_id* | string | Идентификатор клиента в мастер-системе пользователя |
full_name | string | Полное имя клиента |
first_name | string | Имя |
middle_name | string | Отчество |
last_name | string | Фамилия (Из данных 4 полей хотя бы одно должно быть заполнено) |
string | ||
phone | string | Телефон |
sex | string | Пол Допустимые значения: "M","F", "" (если нет данных) |
birth_date | string | Дата рождения (в строковом формате) |
country | string | Страна |
city | string | Город |
zip | string | Индекс |
register_date* | string | Дата регистрации (в строковом формате) |
Изменить клиента
PATCH
https://api.loymaxsc.net/customer/:id
Метод для изменения профиля клиента по его идентификатору в мастер-системе. ВАЖНО: Запрос обновляет все поля. Поля, которые не передавались в запросе, будут обновлены пустыми значениями, либо значениями по умолчанию. Помимо явно перечисленных ниже параметров запрос также может содержать любые параметры, имеющиеся в решении и/или индивидуальной конфигурации пользователя Платформы. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
id | number | Идентификатор клиента в Мастер-системе |
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Bearer TOKEN |
Content-Type* | string | application/json application/vnd.api+json |
Request Body
Name | Type | Description |
---|---|---|
local_id* | string | Идентификатор клиента в мастер-системе пользователя |
full_name | string | Полное имя клиента |
first_name | string | Имя |
middle_name | string | Отчество |
last_name | string | Фамилия (Из данных 4 полей хотя бы одно должно быть заполнено) |
string | ||
phone | string | Телефон |
push-id | string | Идентификатор устройства для push-рассылок |
sex | string | Пол Допустимые значения: "M", "F", "" (если нет данных) |
birth_date | string | Дата рождения (в строковом формате) |
country | string | Страна |
city | string | Город |
zip | string | Почтовый индекс |
register_date* | string | Дата регистрации (в строковом формате) |
Пример запроса:
Изменить подписку клиента
PATCH
https://api.loymaxsc.net/customer/:local_id/subscribe
Метод для управления подпиской клиента по его идентификатору в мастер-системе. ВАЖНО: Подписка на категории рассылок, по которым код не передан не обновляется. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
local_id* | string | Идентификатор клиента в мастер-системе пользователя |
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Bearer TOKEN |
Content-Type* | string | application/json application/vnd.api+json |
Request Body
Name | Type | Description |
---|---|---|
categories* | array | Массив со списком категорий в формате Категория - статус подписки. Допустимые статусы подписки: * Y - подписан; * N - не подписан; * ND - нет данных. |
Обращение к категориям рассылок производится по коду категории.
Пример запроса:
Обновить статус подписки клиента
POST
https://api.loymaxsc.net/customer/:local_id/channel
Метод для изменения статуса подписок клиента.
ВАЖНО: При вызове метода не обязательно указывать все каналы подписки, достаточно указать только те, статус активности которых у клиента поменялся. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
id | number | Идентификатор клиента в Мастер-системе |
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Bearer TOKEN |
Content-Type* | string | application/json application/vnd.api+json |
Request Body
Name | Type | Description |
---|---|---|
boolean | E-mail-рассылка. Допустимые значения "Y", "N", "" (если нет данных) | |
sms | boolean | SMS-рассылка. Допустимые значения "Y", "N", "" (если нет данных) |
push | boolean | PUSH-рассылка. Допустимые значения "Y", "N", "" (если нет данных) |
Получить список рассылок и кампаний, в которых участвовал клиент
GET
https://api.loymaxsc.net/customer/:id/mailing
Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
id* | string | идентификатор пользователя в мастер-системе |
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string | application/vnd.api+json или application/json |
Authorization* | string | Bearer TOKEN |
Зарегистрировать устройство
POST
https://api.loymaxsc.net/customer/:local_id/device
Метод для регистрации устройства клиента. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
* | String | Идентификатор клиента в мастер-системе |
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer TOKEN |
Content-Type* | String | application/json application/vnd.api+json |
device_id* | String | Уникальный идентификатор устройства |
Request Body
Name | Type | Description |
---|---|---|
token* | String | Токен. Указывается токен от Google, Apple или Harmony в зависимости от клиентской платформы. |
platform* | String | Клиентская платформа. Возможные значения: Ios, Android, Harmony. |
source_code | Number | Идентификатор источника событий |
Получить список устройств
GET
https://api.loymaxsc.net/customer/:local_id/device
Метод для получения списка устройств клиента. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
id* | String | Идентификатор клиента в мастер-системе |
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer TOKEN |
Content-Type* | String | application/json application/vnd.api+json |
Удалить устройство
DELETE
https://api.loymaxsc.net/customer/:local_id/device/:token
Метод для удаления устройства клиента. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
* | String | Идентификатор клиента в мастер-системе |
token* | String | Токен. Указывается токен от Google, Apple или Harmony в зависимости от клиентской платформы. |
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer TOKEN |
Content-Type* | String | application/json application/vnd.api+json |
device_id* | String | Уникальный идентификатор устройства |
Request Body
Name | Type | Description |
---|---|---|
source_code | Number | Идентификатор источника событий |
Бонусы клиента
Получить информацию о бонусах клиента по его идентификатору в мастер-системе
GET
https://api.loymaxsc.net/customer/:local_id/bonus
Метод возвращает информацию о бонусах клиента по его идентификатору в мастер-системе: - Количество активных бонусов; - Количество бонусов, которые ожидают активации; - Количество бонусов, которые ожидают деактивации; - Ближайшую дату деактивации бонусов; - Ближайшее количество деактивируемых бонусов. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
local_id* | number | Идентификатор клиента в мастер-системе пользователя |
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string | application/vnd.api+json или application/json |
Authorization* | string | Bearer TOKEN |
Пример запроса:
Изменить информацию о бонусах клиента по его идентификатору в мастер-системе
PATCH
https://api.loymaxsc.net/customer/:local_id/bonus
Метод для изменения бонусов клиента по его идентификатору в мастер-системе пользователя. ВАЖНО: Запрос обновляет все поля. Поля, которые не передавались в запросе, будут обновлены пустыми значениями, либо значениями по умолчанию. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
local_id* | number | Идентификатор клиента в мастер-системе пользователя |
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string | application/vnd.api+json или application/json |
Authorization* | string | Bearer TOKEN |
Пример запроса:
Чек
Получить список чеков
GET
https://api.loymaxsc.net/order
Метод для получения списка чеков (заказов/транзакций). Разрешено только для авторизованных пользователей с ролью API.
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string | application/vnd.api+json или application/json |
Authorization* | string | Bearer TOKEN |
Получить чек
GET
https://api.loymaxsc.net/order/:id
Метод для получения чека (заказа/транзакции) по идентификатору в мастер-системе. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
Name | Type | Description |
---|---|---|
id* | string | Идентификатор чека в мастер-системе |
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string | application/vnd.api+json или application/json |
Authorization* | string | Bearer TOKEN |