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
username*
string
Логин
password*
boolean
Пароль
Headers
Content-Type*
string
application/vnd.api+json или application/json
Пример запроса:
Стоит учитывать, что токен имеет ограниченный срок действия - 1 час. Если он истёк, возвращается ошибка 401, и будет необходимо получить новый токен.
Клиент
Получить список клиентов
GET
https://api.loymaxsc.net/customer
Разрешено только для авторизованных пользователей с ролью API.
Headers
Content-Type*
string
application/vnd.api+json или application/json
Authorization*
string
Bearer TOKEN
Получить клиента
GET
https://api.loymaxsc.net/customer/:id
Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
id*
string
Идентификатор клиента в мастер-системе
Headers
Content-Type*
string
application/vnd.api+json или application/json
Authorization*
string
Bearer TOKEN
Зарегистрировать клиента
POST
https://api.loymaxsc.net/customer
Метод для регистрации профиля клиента клиента по его идентификатору в мастер-системе. ВАЖНО: Повторный вызов запроса для уже имеющегося в базе local_id обновляет все поля. Поля, которые не передавались в запросе, будут обновлены пустыми значениями, либо значениями по умолчанию. Помимо явно перечисленных ниже параметров запрос также может содержать любые параметры, имеющиеся в решении и/или индивидуальной конфигурации пользователя платформы. Разрешено только для авторизованных пользователей с ролью API.
Headers
Authorization*
string
Bearer TOKEN
Content-Type*
string
application/json application/vnd.api+json
Request Body
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
id
number
Идентификатор клиента в Мастер-системе
Headers
Authorization*
string
Bearer TOKEN
Content-Type*
string
application/json application/vnd.api+json
Request Body
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
local_id*
string
Идентификатор клиента в мастер-системе пользователя
Headers
Authorization*
string
Bearer TOKEN
Content-Type*
string
application/json application/vnd.api+json
Request Body
categories*
array
Массив со списком категорий в формате Категория - статус подписки. Допустимые статусы подписки: * Y - подписан; * N - не подписан; * ND - нет данных.
Обращение к категориям рассылок производится по коду категории.
Пример запроса:
Обновить статус подписки клиента
POST
https://api.loymaxsc.net/customer/:local_id/channel
Метод для изменения статуса подписок клиента.
ВАЖНО: При вызове метода не обязательно указывать все каналы подписки, достаточно указать только те, статус активности которых у клиента поменялся. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
id
number
Идентификатор клиента в Мастер-системе
Headers
Authorization*
string
Bearer TOKEN
Content-Type*
string
application/json application/vnd.api+json
Request Body
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
id*
string
идентификатор пользователя в мастер-системе
Headers
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
*
String
Идентификатор клиента в мастер-системе
Headers
Authorization*
String
Bearer TOKEN
Content-Type*
String
application/json application/vnd.api+json
device_id*
String
Уникальный идентификатор устройства
Request Body
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
id*
String
Идентификатор клиента в мастер-системе
Headers
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
*
String
Идентификатор клиента в мастер-системе
token*
String
Токен. Указывается токен от Google, Apple или Harmony в зависимости от клиентской платформы.
Headers
Authorization*
String
Bearer TOKEN
Content-Type*
String
application/json application/vnd.api+json
device_id*
String
Уникальный идентификатор устройства
Request Body
source_code
Number
Идентификатор источника событий
Бонусы клиента
Получить информацию о бонусах клиента по его идентификатору в мастер-системе
GET
https://api.loymaxsc.net/customer/:local_id/bonus
Метод возвращает информацию о бонусах клиента по его идентификатору в мастер-системе: - Количество активных бонусов; - Количество бонусов, которые ожидают активации; - Количество бонусов, которые ожидают деактивации; - Ближайшую дату деактивации бонусов; - Ближайшее количество деактивируемых бонусов. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
local_id*
number
Идентификатор клиента в мастер-системе пользователя
Headers
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
local_id*
number
Идентификатор клиента в мастер-системе пользователя
Headers
Content-Type*
string
application/vnd.api+json или application/json
Authorization*
string
Bearer TOKEN
Пример запроса:
Чек
Получить список чеков
GET
https://api.loymaxsc.net/order
Метод для получения списка чеков (заказов/транзакций). Разрешено только для авторизованных пользователей с ролью API.
Headers
Content-Type*
string
application/vnd.api+json или application/json
Authorization*
string
Bearer TOKEN
Получить чек
GET
https://api.loymaxsc.net/order/:id
Метод для получения чека (заказа/транзакции) по идентификатору в мастер-системе. Разрешено только для авторизованных пользователей с ролью API.
Path Parameters
id*
string
Идентификатор чека в мастер-системе
Headers
Content-Type*
string
application/vnd.api+json или application/json
Authorization*
string
Bearer TOKEN
Зарегистрировать чек
POST
https://api.loymaxsc.net/order
Метод для регистрации чека (заказа/транзакции), либо обновления существующего чека (заказа/транзакции) по его local_id. ВАЖНО: Повторный вызов запроса для уже имеющегося в базе local_id обновляет все поля. Поля, которые не передавались в запросе, будут обновлены пустыми значениями, либо значениями по умолчанию. Помимо явно перечисленных ниже параметров запрос также может содержать любые параметры, имеющиеся в решении и/или индивидуальной конфигурации пользователя Платформы. Разрешено только для авторизованных пользователей с ролью API.
Headers
Authorization
string
Bearer TOKEN
Content-Type
string
application/json application/vnd.api+json
Request Body
local_id
string
Идентификатор чека (заказа/транзакции) в мастер-системе пользователя
client_id
string
Идентификатор клиента в мастер-системе пользователя
number
string
Номер чека (заказа/транзакции)
status_name
string
Наименование статуса заказа, транзакции
date*
string
Дата чека (заказа/транзакции) (в строковом формате)
items_cnt
number
Количество продуктов в чеке (заказе/транзакции). Речь идёт о количестве единиц
items_sum
number
Сумма чека (заказа/транзакции)
items
array
Состав чека (заказа/транзакции)
Состав чека (строка чека):
Атрибут
Тип
Назначение
local_id
String
Идентификатор строки заказа / строки транзакции в мастер-системе пользователя
client_id
String
Идентификатор клиента в мастер-системе пользователя
product_id
String
Идентификатор продукта в мастер-системе пользователя
price
Number
Стоимость продукта
cnt
Number
Количество продукта
sum
Number
Сумма по строке
Жирным обозначены обязательные поля.
Помимо явно перечисленных выше параметров строка чека также может содержать любые параметры, имеющиеся в решении и/или индивидуальной конфигурации пользователя платформы.
Пример запроса: