REST API

Обзор

API реализовано в соответствии с протоколом JSONAPI.

Все методы API, кроме Token доступны только авторизованным пользователям. Для вызова этих методов необходимо отправлять HTTP заголовок, содержащий токен JWT:

Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Все данные следует передавать в кодировке utf-8.

Постраничная навигация

При запросе коллекции сущностей в /GET параметрах можно передать:

?page[number]=1&page[size]=15

Номер и размер страницы соответственно. В ответе будут возвращены дополнительные блоки:

"meta": {
  "total": 21,
  "count": 5
},
"links": {
  "self": "https://api.loymaxsc.net/event?page[number]=1&page[size]=100",
  "first": "https://api.loymaxsc.net/event?page[number]=1&page[size]=100",
  "last": "https://api.loymaxsc.net/event?page[number]=5&page[size]=100",
  "next": "https://api.loymaxsc.net/event?page[number]=2&page[size]=100"
}

Сортировка

При запросе коллекции сущностей в /GET параметрах можно передать:

?sort=[{"attribute": "name", "direction": "asc"},...]

Он представляет собой json-массив объектов с условиями сортировки:

Типы данных

Доступные типы данных:

Ограничение нагрузки на REST API

В REST API действует ограничение на количество запросов с одного IP в единицу времени. При превышении лимита в 1000 запросов в минуту возвращается ошибка 429:

HTTP/1.1 Error 429: Too Many Attempts
{
    "errors": [
        {
            "status": 429,
            "title": "Too Many Attempts."
        }
    ]
}

В случае получения такого сообщения клиент должен сделать паузу на 1 минуту и уменьшить частоту запросов.

Методы API

Токен

Получить токен

POST https://api.loymaxsc.net/token

Метод для получения авторизационного токена. Токен необходим для выполнения запросов к API. Полученный токен отправляется в заголовке запроса: Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Query Parameters

Headers

HTTP/1.1 200 OK
{
  "data": {
    "type": "user",
     "id": "1",
     "attributes": {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOmZhbHNlLCJhdWQiOiJza2VsZXRvbi5kZXYiLCJpYXQiOjE0NzY0Mjk4NjksImV4cCI6MTQ3NjQzMzQ2OX0.NJn_-lK28kEZyZqygLr6B-FZ2zC2-1unStayTGicP5g",
        "user": {
            "id": "1",
            "name": "api",
            "email": "api@example.com"
        }
     }
  }
}

HTTP/1.1 400 Bad request
Error 400: Bad Request
{
    "errors": [
        {
            "status": 400,
            "title": "Invalid Attribute"
        }
    ]
}

HTTP/1.1 500 Internal Server Error
{
    "errors": [
        {
            "status": 500,
            "title": "Internal server error"
        }
    ]
}

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

{
    "data": {
        "attributes": {
            "username": "admin@example.com",
            "password": "qwerty"
        }
    }
}

Стоит учитывать, что токен имеет ограниченный срок действия - 1 час. Если он истёк, возвращается ошибка 401, и будет необходимо получить новый токен.

Клиент

Получить список клиентов

GET https://api.loymaxsc.net/customer

Разрешено только для авторизованных пользователей с ролью API.

Headers

 HTTP/1.1 200 OK
{
  "data": [
   {
       "type": "customer",
       "id": "1",
       "attributes": {
           "id": "1",
           "uid": "dc6719706923287a20844dc0f50d9046",
           "site_user_id": "1",
           "local_id": "1",
           "full_name": "Тестовый клиент",
           "first_name": null,
           "middle_name": null,
           "last_name": null,
           "email": "mail@example.com",
           "email_validation_code": "39",
           "email_validation_date": "2017-06-20 16:06:02",
           "email_edited": "N",
           "phone": null,
           "phone_type": "10",
           "phone_validation_code": "30",
           "phone_validation_date": "2017-06-20 16:06:02",
           "phone_edited": "N",
           "timezone": null,
           "sex": null,
           "birth_date": null,
           "country": null,
           "area": null,
           "city": null,
           "zip": null,
           "register_date": "2017-06-20 16:06:02",
           "first_order_date": null,
           "first_order_number": null,
           "first_order_items_sum": "0.00",
           "last_order_date": null,
           "last_order_number": null,
           "last_order_items_sum": "0.00",
           "order_cnt": "0",
           "order_sum": "0.00",
           "order_average_check": "0.00",
           "order_cnt_rfm": "0",
           "order_sum_rfm": "0.00",
           "order_average_check_rfm": "0.00",
           "r_seg_now": "0",
           "f_seg_now": "0",
           "m_seg_now": "0",
           "r_seg_prev": "0",
           "f_seg_prev": "0",
           "m_seg_prev": "0",
           "rfm_date_upd": null,
           "active": "Y",
       },
       "links": {
           "self": "https://api.loymaxsc.net/customer/1"
       }
   },
   {
       "type": "customer",
       "id": "2",
       "attributes": {
           "id": "2",
           "uid": "sdfjkdfhsjdfhsdjkfbc734bdsmnbdsmnbdd",
           "site_user_id": "1",
           "local_id": "2",
           "full_name": "Тестовый клиент 2",
           "first_name": null,
           "middle_name": null,
           "last_name": null,
           "email": "mail@example.com",
           "email_validation_code": "39",
           "email_validation_date": "2017-06-20 16:06:02",
           "email_edited": "N",
           "phone": null,
           "phone_type": "10",
           "phone_validation_code": "30",
           "phone_validation_date": "2017-06-20 16:06:02",
           "phone_edited": "N",
           "timezone": null,
           "sex": null,
           "birth_date": null,
           "country": null,
           "area": null,
           "city": null,
           "zip": null,
           "register_date": "2017-06-20 16:06:02",
           "first_order_date": null,
           "first_order_number": null,
           "first_order_items_sum": "0.00",
           "last_order_date": null,
           "last_order_number": null,
           "last_order_items_sum": "0.00",
           "order_cnt": "0",
           "order_sum": "0.00",
           "order_average_check": "0.00",
           "order_cnt_rfm": "0",
           "order_sum_rfm": "0.00",
           "order_average_check_rfm": "0.00",
           "r_seg_now": "0",
           "f_seg_now": "0",
           "m_seg_now": "0",
           "r_seg_prev": "0",
           "f_seg_prev": "0",
           "m_seg_prev": "0",
           "rfm_date_upd": null,
           "active": "Y",
       },
       "links": {
           "self": "https://api.loymaxsc.net/customer/2"
       }
   }
  ]
}

HTTP/1.1 Error 401: Unauthorized
{
    "errors": [
        {
            "status": 401,
            "title": "Authorization failed"
        }
    ]
}

Получить клиента

GET https://api.loymaxsc.net/customer/:id

Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

HTTP/1.1 200 OK
{
  "data": {
    "type": "customer",
    "id": "1",
    "attributes": {
        "id": "1",
        "uid": "dc6719706923287a20844dc0f50d9046",
        "site_user_id": "1",
        "local_id": "1",
        "full_name": "Тестовый клиент",
        "first_name": null,
        "middle_name": null,
        "last_name": null,
        "email": "mail@example.com",
        "email_validation_code": "39",
        "email_validation_date": "2017-06-20 16:06:02",
        "email_edited": "N",
        "phone": null,
        "phone_type": "10",
        "phone_validation_code": "30",
        "phone_validation_date": "2017-06-20 16:06:02",
        "phone_edited": "N",
        "timezone": null,
        "sex": null,
        "birth_date": null,
        "country": null,
        "area": null,
        "city": null,
        "zip": null,
        "register_date": "2017-06-20 16:06:02",
        "first_order_date": null,
        "first_order_number": null,
        "first_order_items_sum": "0.00",
        "last_order_date": null,
        "last_order_number": null,
        "last_order_items_sum": "0.00",
        "order_cnt": "0",
        "order_sum": "0.00",
        "order_average_check": "0.00",
        "order_cnt_rfm": "0",
        "order_sum_rfm": "0.00",
        "order_average_check_rfm": "0.00",
        "r_seg_now": "0",
        "f_seg_now": "0",
        "m_seg_now": "0",
        "r_seg_prev": "0",
        "f_seg_prev": "0",
        "m_seg_prev": "0",
        "rfm_date_upd": null,
        "active": "Y",
    },
    "links": {
        "self": "https://api.loymaxsc.net/customer/1"
    }
  }
}

HTTP/1.1 404 Not found
{
  "errors": [
    {
      "status": "404",
       "code": "404",
       "title": "Nothing found"
    }
  ]
}

Зарегистрировать клиента

POST https://api.loymaxsc.net/customer

Метод для регистрации профиля клиента клиента по его идентификатору в мастер-системе. ВАЖНО: Повторный вызов запроса для уже имеющегося в базе local_id обновляет все поля. Поля, которые не передавались в запросе, будут обновлены пустыми значениями, либо значениями по умолчанию. Помимо явно перечисленных ниже параметров запрос также может содержать любые параметры, имеющиеся в решении и/или индивидуальной конфигурации пользователя платформы. Разрешено только для авторизованных пользователей с ролью API.

Headers

Request Body

HTTP/1.1 200 OK
{
  "data": {
    "type": "customer",
    "id": "2",
    "attributes": {
      "id": "2",
      "local_id": 724,
      "full_name": "Тестовый клиент",
      "email": "mail@example.com",
      "register_date": "2017-06-12 16:57:52",
    },
    "links": {
      "self": "https://api.loymaxsc.net/customer/2"
    }
  }
}

Изменить клиента

PATCH https://api.loymaxsc.net/customer/:id

Метод для изменения профиля клиента по его идентификатору в мастер-системе. ВАЖНО: Запрос обновляет все поля. Поля, которые не передавались в запросе, будут обновлены пустыми значениями, либо значениями по умолчанию. Помимо явно перечисленных ниже параметров запрос также может содержать любые параметры, имеющиеся в решении и/или индивидуальной конфигурации пользователя Платформы. Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

Request Body

HTTP/1.1 200 OK
{
  "data": {
    "type": "customer",
    "id": "2",
    "attributes": {
      "id": "2",
      "local_id": 724,
      "full_name": "Тестовый клиент",
      "email": "mail2@example.com",
      "register_date": "2017-06-12 16:57:52",
    },
    "links": {
      "self": "https://api.loymaxsc.net/customer/2"
    }
  }
}

HTTP/1.1 404 Not found
{
  "errors": [
    {
      "status": "404",
       "code": "404",
       "title": "Nothing found"
    }
  ]
}

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

{
    "data": {
        "attributes": {
            "local_id": "724",
            "full_name": "Тестовый клиент",
            "email": "mail2@example.com",
            "register_date": "2017-06-12 16:57:52"
        }
    }
}

Изменить подписку клиента

PATCH https://api.loymaxsc.net/customer/:local_id/subscribe

Метод для управления подпиской клиента по его идентификатору в мастер-системе. ВАЖНО: Подписка на категории рассылок, по которым код не передан не обновляется. Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

Request Body

HTTP/1.1 200 OK
{
    "data": {
        "attributes": {
            "status":"success"
        }
    }
}

Обращение к категориям рассылок производится по коду категории.

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

{
  "data": {
    "attributes": {
  		"categories": {
          "news": {"email" :"N", "sms": "Y", "push": "N"},
          "hidden-sales":  {"email" :"Y"}
		  }
    }
  }
}

Обновить статус подписки клиента

POST https://api.loymaxsc.net/customer/:local_id/channel

Метод для изменения статуса подписок клиента.

ВАЖНО: При вызове метода не обязательно указывать все каналы подписки, достаточно указать только те, статус активности которых у клиента поменялся. Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

Request Body

{
    "data": {
        "attributes": {
            "email": "Y",
            "push": "N",
            "sms": "N"
        }
    }
}

Получить список рассылок и кампаний, в которых участвовал клиент

GET https://api.loymaxsc.net/customer/:id/mailing

Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

 HTTP/1.1 200 OK
{
    "links": {
        "first": "/mailing?page%5Blimit%5D=10",
        "next": "/mailing?page%5Bnumber%5D=2&page%5Blimit%5D=10",
        "last": "/mailing?page%5Bnumber%5D=13&page%5Blimit%5D=10"
    },
    "data": [
          {
            "type": "mailing",
            "id": "705",
            "attributes": {
                "id": "705",
                "subject": "asd",
                "date": "2022-12-01 19:21:32",
                "in_control_group": "Y",
                "entity_type": "client_mailings_list",
                "type": "mailing",
                "channel": "mail",
                "contact": "test@email.com",
                "template": null,
                "context": [
                    {
                        "key" : "Audience",
                        "value" : "27200722"
                    },
                    {
                        "key" : "MechanicsCode",
                        "value" : "373673"
                    },
                ],
                "event_type": "send",
                "events": [
                    {
                        "type": "send",
                        "date": "2022-12-01 19:21:32"
                    }
                    {
                        "type": "delivered",
                        "date": "2022-12-01 19:21:56"
                    },
                ]
            },
            {
            "type": "mailing",
            "id": "705",
            "attributes": {
                "id": "705",
                "message": "",
                "sms_message": "This is a test SMS",
                "date": "2023-02-28 14:33:48",
                "in_control_group": "Y",
                "entity_type": "client_sms_list",
                "type": "mailing",
                "channel": "sms",
                "contact": "+79235227632",
                "template": "This is a test SMS",
                "context": null,
                "event_type": "send",
                "events": [
                    {
                        "type": "send",
                        "date": "2023-02-28 14:33:48"
                    }
                ]
            },
            "links": {
                "self": "/mailing/705"
            }
        },
        {
            "type": "mailing",
            "id": "440",
            "attributes": {
                "id": "440",
                "message": "This is a test PUSH",
                "date": "2023-03-13 15:14:21",
                "in_control_group": "Y",
                "entity_type": "client_push_list",
                "type": "mailing",
                "channel": "push",
                "contact": "6516626e-0681-11ed-bde6-1595aa93e5c2",
                "template": "This is a test PUSH",
                "context": null,
                "event_type": "send",
                "events": [
                    {
                        "type": "send",
                        "date": "2023-03-13 15:14:21"
                    }
                ]
            },
            "links": {
                "self": "/mailing/440"
            }
        },
        {
            "type": "mailing",
            "id": "608",
            "attributes": {
                "id": 608,
                "name": "4584_3",
                "date": "2022-11-15 15:26:45",
                "in_control_group": "N",
                "send_type": "mail",
                "entity_type": "client_campaigns_list",
                "type": "campaign",
                "channel": "mail",
                "send_type_t": "email",
                "contact": "test@email.com",
                "step_id": "4",
                "context": [
                    {
                        "key" : "Audience",
                        "value" : "27200724"
                    },
                    {
                        "key" : "MechanicsCode",
                        "value" : "373670"
                    },
                ],
                "event_type": "send",
                "template": "<head><style type=\"text/css\"></style></head><body><p>4584</p><p>{{client.links.unsubscribe}}</p></body>",
                "events": [
                    {
                        "type": "send",
                        "date": "2022-11-15 15:26:45"
                    }
                ]
            },
            "links": {
                "self": "/mailing/608"
            }
        },
    ]
}

HTTP/1.1 Error 401: Unauthorized
{
    "errors": [
        {
            "status": 401,
            "title": "Authorization failed"
        }
    ]
}

Зарегистрировать устройство

POST https://api.loymaxsc.net/customer/:local_id/device

Метод для регистрации устройства клиента. Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

Request Body

{
    // Response
}

{
    // Response
}

Получить список устройств

GET https://api.loymaxsc.net/customer/:local_id/device

Метод для получения списка устройств клиента. Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

{
    // Response
}

{
    // Response
}

Удалить устройство

DELETE https://api.loymaxsc.net/customer/:local_id/device/:token

Метод для удаления устройства клиента. Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

Request Body

{
    // Response
}

{
    // Response
}

Бонусы клиента

Получить информацию о бонусах клиента по его идентификатору в мастер-системе

GET https://api.loymaxsc.net/customer/:local_id/bonus

Метод возвращает информацию о бонусах клиента по его идентификатору в мастер-системе: - Количество активных бонусов; - Количество бонусов, которые ожидают активации; - Количество бонусов, которые ожидают деактивации; - Ближайшую дату деактивации бонусов; - Ближайшее количество деактивируемых бонусов. Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

HTTP/1.1 200 OK
{
    "data": {
        "type": "bonus",
        "id": "4615",
        "attributes": {
            "id": 4615,
            "bonus_active": 1000,
            "bonus_expect_activate": 300,
            "bonus_expect_deactivate": 100,
            "bonus_expect_deactivate_next_date": "2020-12-01 16:30:45",
            "bonus_expect_deactivate_next_value": 0
        }
    }
}

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

{
    "data": {
        "attributes": {
            "bonus_active": 1, //бонусов активно, money
            "bonus_expect_activate": 1, //бонусов ожидает активации, money (может быть пустым)
            "bonus_expect_deactivate": 1, //бонусов ожидает деактивации, money (может быть пустым)
            "bonus_expect_deactivate_next_date": "2020-08-01 16:30:45", //ближайшая дата деактивации бонусов, yyyy-mm-dd hh:mm:ss, string (может быть пустым);
            "bonus_expect_deactivate_next_value": 1, //ближайшее количество деактивируемых бонусов, money (может быть пустым).
        }
    }
}

Изменить информацию о бонусах клиента по его идентификатору в мастер-системе

PATCH https://api.loymaxsc.net/customer/:local_id/bonus

Метод для изменения бонусов клиента по его идентификатору в мастер-системе пользователя. ВАЖНО: Запрос обновляет все поля. Поля, которые не передавались в запросе, будут обновлены пустыми значениями, либо значениями по умолчанию. Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

HTTP/1.1 200 OK
{
    "data": {
        "type": "bonus",
        "id": "4615",
        "attributes": {
            "id": 4615,
            "bonus_active": 1000,
            "bonus_expect_activate": 300,
            "bonus_expect_deactivate": 100,
            "bonus_expect_deactivate_next_date": "2020-12-01 16:30:45",
            "bonus_expect_deactivate_next_value": 0
        }
    }
}

HTTP/1.1 Error 404: Not Found
{
    "title": "Nothing found|Not Found",
    "status": 404
}

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

{
    "data": {
        "attributes": {
            "bonus_active": 1, //бонусов активно, money
            "bonus_expect_activate": 1, //бонусов ожидает активации, money (может быть пустым)
            "bonus_expect_deactivate": 1, //бонусов ожидает деактивации, money (может быть пустым)
            "bonus_expect_deactivate_next_date": "2020-08-01 16:30:45", //ближайшая дата деактивации бонусов, yyyy-mm-dd hh:mm:ss, string (может быть пустым);
            "bonus_expect_deactivate_next_value": 1, //ближайшее количество деактивируемых бонусов, money (может быть пустым).
        }
    }
}

Чек

Получить список чеков

GET https://api.loymaxsc.net/order

Метод для получения списка чеков (заказов/транзакций). Разрешено только для авторизованных пользователей с ролью API.

Headers

HTTP/1.1 200 OK
{
  "data": [
   {
       "type": "order",
       "id": "1",
       "attributes": {
           "id": "1",
           "local_id": "177",
           "status_name": "Отмена",
           "delivery_country": null,
           "delivery_area": null,
           "delivery_city": null,
           "delivery_zip": null,
           "date": "2017-06-20 16:06:02",
           "items":  [
               {
                   "local_id": "577",
                   "product_id": 789,
                   "product_name": "Зубной порошок",
                   "price": 120,
                   "cnt": 1,
                   "sum": 120
               }
           ]
       },
       "links": {
           "self": "https://api.loymaxsc.net/order/1"
       }
   },
   {
       "type": "order",
       "id": "2",
       "attributes": {
           "id": "2",
           "local_id": "754",
           "status_name": "Продажа",
           "delivery_country": null,
           "delivery_area": null,
           "delivery_city": null,
           "delivery_zip": null,
           "date": "2017-06-21 16:06:02",
           "items":  [
               {
                   "local_id": "577",
                   "product_id": 789,
                   "product_name": "Зубной порошок",
                   "price": 120,
                   "cnt": 1,
                   "sum": 120
               }
           ]
       },
       "links": {
           "self": "https://api.loymaxsc.net/order/2"
       }
   }
  ]
}

HTTP/1.1 Error 401: Unauthorized
{
    "errors": [
        {
            "status": 401,
            "title": "Authorization failed"
        }
    ]
}

Получить чек

GET https://api.loymaxsc.net/order/:id

Метод для получения чека (заказа/транзакции) по идентификатору в мастер-системе. Разрешено только для авторизованных пользователей с ролью API.

Path Parameters

Headers

HTTP/1.1 200 OK
{
  "data": {
    "type": "order",
    "id": "1",
    "attributes": {
         "id": "1",
         "local_id": "177",
         "status_name": "Отмена",
         "delivery_country": null,
         "delivery_area": null,
         "delivery_city": null,
         "delivery_zip": null,
         "date": "2017-06-20 16:06:02",
         "items": [
             {
                 "local_id": "577",
                 "product_id": 789,
                 "product_name": "Зубной порошок",
                 "price": 120,
                 "cnt": 1,
                 "sum": 120
             }
         ]
    },
    "links": {
        "self": "https://api.loymaxsc.net/order/1"
    }
  }
}

HTTP/1.1 Error 401: Unauthorized
{
    "errors": [
        {
            "status": 401,
            "title": "Authorization failed"
        }
    ]
}

HTTP/1.1 404 Not found
{
  "errors": [
    {
      "status": "404",
       "code": "404",
       "title": "Nothing found"
    }
  ]
}

Зарегистрировать чек

POST https://api.loymaxsc.net/order

Метод для регистрации чека (заказа/транзакции), либо обновления существующего чека (заказа/транзакции) по его local_id. ВАЖНО: Повторный вызов запроса для уже имеющегося в базе local_id обновляет все поля. Поля, которые не передавались в запросе, будут обновлены пустыми значениями, либо значениями по умолчанию. Помимо явно перечисленных ниже параметров запрос также может содержать любые параметры, имеющиеся в решении и/или индивидуальной конфигурации пользователя Платформы. Разрешено только для авторизованных пользователей с ролью API.

Headers

Request Body

HTTP/1.1 200 OK
{
    "data": {
      "attributes": {
        "local_id": "1050",
        "client_id": "724",
        "status_name": "Создан",
        "items": [
            {
             "local_id": "577",
             "product_id": "789",
             "price": 120,
             "cnt": 1,
             "sum": 120
            }
        ]
      }
    },
    "links": {
      "self": "https://api.loymaxsc.net/order/2"
    }