Бекенд
Налаштування API
Запит на API
На всі API надходитимуть запити, які обов'язково міститимуть такі поля:
Крім того, якщо вдалося визначити мову, у запит додатково потрапить поле "lang" (код мови). Спочатку перевіряється атрибут "data-lurazon-lang" на тезі, у якому генерується каталог (див. розділ Рендер шаблону), і лише якщо він не вказаний - атрибут "lang" кореневого тегу "html" сторінки. Якщо жодного значення не знайдено - поле "lang" не передається:
У цьому випадку поле "lang" міститиме:
У прикладах коду нижче (а також у прикладах бекенд-запитів та відповідей далі в документації) повторюються одні й ті самі ідентифікатори - це зроблено навмисно, щоб показати, що йдеться про одні й ті самі фільтри, опції та сутності в різних прикладах:
"FilterVehicleType" - фільтр "Вид транспорту" (тип "Чекбокси")
"OptionSUV" - опція "Позашляховик" фільтра "Вид транспорту"
"FilterBrand" - фільтр "Марка" (тип "Радіокнопки")
"OptionAudi" - опція "Audi" фільтра "Марка"
"FilterPrice" - фільтр "Ціна" (тип "Числовий")
"new" - опція сортування "Найновіші"
"12" - опція кількості відображених результатів "12 продуктів"
API налаштувань
Якщо в шаблоні заповнене поле "API налаштувань", тоді необхідно створити дане API на тому самому домені та за тим самим шляхом, що вказано в полі. Дане API має використовувати метод POST
Запит на API
На це API надходитимуть запити з наступними ключами - за ними бекенд визначає, для якої сторінки він відповідає:
"template" - ідентифікатор шаблону
"domain" - домен сторінки, на якій будується шаблон
"path" - шлях сторінки: з власним API маршрути сайту не використовуються, тож саме за ним працює власна маршрутизація
"lang" - ідентифікатор мови сторінки, передається лише на багатомовному сайті, коли мова сторінки є однією з мов сайту
API відповідь
Дане API має відповісти наступними полями, за необхідності:
"filters" - упорядкований масив фільтрів, кожен фільтр масиву має бути словником, що містить наступні ключі:
"id" - є обов'язковим полем, вказує ідентифікатор поля фільтру (його ключ у "fields"), має передаватися як рядкове значення
"type" - є обов'язковим полем, вказує тип фільтру, має передаватися як рядкове значення та бути одним із перерахованих нижче значень:
"c" - тип фільтру "Чекбокси"
"r" - тип фільтру "Радіокнопки"
"n" - тип фільтру "Числовий"
"fields" - словник полів, які використовує сторінка: поля фільтрів та поля-селектори, які виводять елементи "Поле об'єкта: Селектори". Його ключі - ідентифікатори полів, кожне поле має бути словником, що містить наступні ключі:
"label" - є обов'язковим полем для поля фільтру, вказує заголовок фільтру, має передаватися як рядкове значення
"key" - не є обов'язковим полем, вказує унікальний ключ поля, використовується замість ідентифікатору в посиланні та лише для фільтрів типу: "Чекбокси" та "Радіокнопки". Має передаватися як рядкове значення
"range" - не є обов'язковим полем, використовується лише для фільтрів типу "Числовий", вказує найменше та найбільше значення фільтру, має передаватися як масив із двох чисел. Якщо передано - повзунок діапазону фільтру бере їх одразу, і вони не запитуються окремо
"dependField" та "dependOption" - не є обов'язковими полями, роблять фільтр поля залежним: він має стан "Фільтр недоступний", доки у фільтрі поля "dependField" не обрано опцію "dependOption" (або вкладену в неї). Мають передаватися як рядкові значення. Якщо це поле не є фільтром сторінки, залежність ігнорується
"options" - не є обов'язковим полем, вказує всі опції даного поля, використовується для фільтрів типу: "Чекбокси" та "Радіокнопки" і для елементів "Поле об'єкта: Селектори". Має передаватися як упорядкований масив опцій поля, кожна опція масиву має бути словником, що містить наступні ключі:
"id" - є обов'язковим полем, вказує унікальний, для цього поля, ідентифікатор опції, має передаватися як рядкове значення
"label" - є обов'язковим полем, вказує заголовок опції, має передаватися як рядкове значення
"key" - не є обов'язковим полем, вказує унікальний ключ опції, використовується замість ідентифікатору в посиланні, має передаватися як рядкове значення
"children" - не є обов'язковим полем, вказує дочірні опції, використовується лише для фільтрів типу: "Чекбокси" та для елементів "Поле об'єкта: Селектори". Має передаватися як упорядкований масив опцій
"sort" - словник налаштування сортування, що містити наступні ключі:
"options" - є обов'язковим полем, вказує всі опції для сортування, має передаватися як упорядкований масив опцій, кожна опція масиву має бути словником, що містить наступні ключі:
"id" - є обов'язковим полем, вказує унікальний ідентифікатор опції сортування, має передаватися як рядкове значення
"label" - є обов'язковим полем, вказує заголовок опції, має передаватися як рядкове значення
"limit" - словник налаштування кількості відображених результатів на сторінці, що містити наступні ключі:
"options" - є обов'язковим полем, вказує всі опції для лімітування кількості відображених результатів, має передаватися як упорядкований масив опцій, кожна опція масиву має бути словником, що містить наступні ключі:
"id" - є обов'язковим полем, вказує унікальний ідентифікатор опції лімітування кількості відображених результатів, має передаватися ціле число у вигляді рядкового значення
"label" - є обов'язковим полем, вказує заголовок опції, має передаватися як рядкове значення
API результатів
Якщо в шаблоні заповнене поле "API результатів", тоді необхідно створити дане API на тому самому домені та за тим самим шляхом, що вказано в полі. Дане API має використовувати метод POST
Запит на API
На це API надходитимуть запити, які додатково міститимуть словник "results" із наступними ключами:
"fields" - масив із ключами значень, які мають бути вирахувані та повернуті
"numbers" - запит потребує повернення проміжку значень для фільтрів типу "Числовий". Перелік ідентифікаторів фільтрів, для яких має бути вирахувано та повернуто проміжки значень передаватимуться в "filtersNumbers"
"facets" - запит потребує повернення фасетів для фільтрів типів "Чекбокси" та "Радіокнопки". Перелік ідентифікаторів фільтрів, для яких має бути вирахувано та повернуто фасети передаватимуться в "filtersFacets"
"objects" - запит потребує повернення результатів пошуку, враховуючи значення фільтрів передані через ключі: "valueSearch", "valueFilters", "valueSort", "valuePage", "valueLimit"
"count" - запит потребує повернення кількості результатів пошуку, враховуючи значення фільтрів передані через ключі: "valueSearch", "valueFilters", "valueSort", "valuePage", "valueLimit"
"filtersNumbers" - масив із ідентифікаторами фільтрів типу "Числовий" для яких потрібно буде повернути проміжки можливих значень
"filtersFacets" - масив із ідентифікаторами фільтрів типів "Чекбокси" та "Радіокнопки" для опцій яких потрібно буде повернути фасети
"valueSearch" - рядкове значення поля пошуку шаблону, може мати пусте значення
"valueFilters" - є словником кожен ключ якого є ідентифікатором фільтру зі значенням, притаманним відповідному типу фільтру. Приклад значень, які передаються для відповідних типів фільтрів, можна отримати за допомогою функцій: "filtersApplied" та "filtersCurrent" на фронтенді
"valueSort" - є рядковим значенням, яке являє собою ідентифікатор опції сортування. Дане значення передається виключно в тому випадку, якщо для шаблону було застосоване сортування
"valuePage" - є числовим значенням, яке являє собою сторінку, на якій перебуває користувач. Дане значення передається виключно в тому випадку, якщо для шаблону було застосоване лімітування кількості відображених результатів
"valueLimit" - є числовим значенням, яке являє собою ідентифікатор опції кількості відображених результатів. Дане значення передається виключно в тому випадку, якщо для шаблону було застосоване лімітування кількості відображених результатів
API відповідь
Коли на даний endpoint приходить запит, то шаблон очікує отримати у відповідь лише те, що передано в масив "results.fields". Якщо цей масив містить тільки "count", то має повернутися "{ count: ... }", якщо "objects" та "count" тоді: { objects: ... , count: ... } і так далі
Керування об'єктами
Наступні ендпоінти використовуються для додавання та видалення об'єктів через API. Зручно використовувати, коли сутність на сайті оновлюється або видаляється і потрібно одразу відіслати її на синхронізацію з Lurazon
Авторизація
Щоб успішно передавати дані до наступних API, треба побудувати правильний запит та авторизуватися через JWT закодований за алгоритмом "HS256"
Запит має обов'язково містити наступні дані:
"site" - ідентифікатор сайту
"token" - JWT авторизації
"list" - масив із необхідними для API даними, який обов'язково має бути не пустим і містити не більше 1000 елементів. Тіло всього запиту - не більше 16 МБ: більшу кількість об'єктів надсилайте кількома запитами
В JWT авторизації має бути закодовано словник, який містити ключі: "type" зі значенням "objects" та "site" зі значенням ідентифікатору сайту. Термін дії токену ("exp") обов'язковий і не може бути далі ніж за 3600 секунд, інакше токен відхиляється. Ми рекомендуємо зазначати орієнтовно на 15 секунд
API додавання/оновлення
Відправляйте POST запити на https://objects.lurazon.com/set
Для того, щоб створити або оновити об'єкти, необхідно в масив "list" додати їх перелік. Кожен об'єкт має бути словником, що містить в собі ключі:
"id" - обов'язкове рядкове значення, яке являє собою унікальний ідентифікатор сутності
"fields" - обов'язковий словник, кожен ключ якого є ідентифікатором поля, що зареєстроване в кабінеті сайту. Значення кожного ключа - це словник, що містить наступні ключі:
"value" - значення даного поля, що має бути передано в відповідному форматі:
Для "API-селектор" та "Мультиселектор" типів полів - масив із рядковими значеннями ідентифікаторів опцій. Для "Мультиселектор" мають бути передані лише ті, які збережені в кабінеті
Для "Одиночний селектор" типу полів - рядкове значення ідентифікатору опції, яке збережено в кабінеті в одному із опцій
Для "Рядок" та "Текстова область" типів полів - рядкове значення
Для "Число" типу полів - числове значення
Для "Дата" типу полів - рядкове значення, яке містить дату (найкраще у форматі ISO 8601, зміщення часового поясу в ньому враховується), або позначка часу в мілісекундах. Дата зберігається в часовому поясі UTC. Дата з часом, але без часового поясу, читається як UTC, тож для точних результатів передавайте пояс ("Z" або зміщення). Значення, яке не вдається прочитати як дату, не зберігається
Для "Зображення" типу полів - масив із рядкових значень, що є посиланнями на зображення
"translations" - словник з перекладами поля, значення яких застосовуються лише для тих полів, для яких увімкнено переклад в кабінеті. Кожен ключ - це ідентифікатор мови, який вказаний в кабінеті, що мусить мати значенням - в такому самому форматі, що і значення для "value", яке буде застосовано як переклад по замовчуванню
"unpublished" - не обов'язкове булеве значення, якщо воно дорівнює 'true', тоді об'єкт збережеться як неопублікований
Приклад запиту (ідентифікатори полів та опцій - ті самі, що в прикладах розділу "Налаштування API"):
Об'єкт з ідентифікатором, якого ще немає на сайті, створюється, з наявним - повністю перезаписується. Відповідь з кодом 200 - словник з ключами:
"required" - масив ідентифікаторів об'єктів, які не збережено: відсутнє або некоректне значення поля з параметром "Обов'язкове поле"
"failed" - масив ідентифікаторів об'єктів, які не збережено з будь-якої іншої причини (некоректне "fields", ліміт кількості об'єктів, помилка запису). Об'єкт без коректного ідентифікатора та повтор ідентифікатора є лише в "reasons"
"reasons" - словник із причинами, чому об'єкт не збережено або збережено із зауваженнями. Ключ - позиція об'єкта в масиві "list", починаючи з 0. Значення - масив записів у форматі "{ reason, field, language, value }", де "field", "language" та "value" вказуються лише тоді, коли стосуються причини. Об'єкти, збережені без зауважень, у словник не потрапляють. Можливі значення "reason":
"id" - об'єкт не збережено: ідентифікатор відсутній, не рядок, порожній, довший за 64 символи або містить пробіл
"duplicate" - об'єкт не збережено: його ідентифікатор уже був раніше в цьому "list" (обробляється попередній)
"fields" - об'єкт не збережено: "fields" не є словником
"required" - об'єкт не збережено: обов'язкове поле "field" відсутнє або має некоректне значення (перелічено кожне таке поле)
"limit" - об'єкт не збережено: ліміт кількості об'єктів пробного періоду
"write" - об'єкт не збережено: помилка запису
"skipped" - об'єкт збережено, частину відкинуто: значення поля "field" некоректне. З "language" - лише цей переклад (невідома мова, не рядок, задовгий). З "value" - лише цей елемент списку (не опція поля, некоректний ключ). Значення "null" залишає поле порожнім навмисно і не повідомляється
"translations" - об'єкт збережено без перекладів поля "field": "translations" не є словником або поле не перекладне
"unknown" - об'єкт збережено, поле "field" проігноровано: такого поля для запису немає (його немає в структурі, або це системне поле, яке API не задає)
"unpublished" - об'єкт збережено опублікованим: "unpublished" не є булевим значенням
Код 400 - некоректне тіло запиту (відсутній один з обов'язкових ключів, масив "list" порожній або довший за 1000 елементів). Код 413 - тіло запиту більше за 16 МБ. Код 403 - недійсний JWT або ідентифікатор сайту. Код 403 з тілом "blocked" - сайт заблоковано (неоплачений рахунок або видалення), об'єкти не приймаються
API видалення
Відправляйте POST запити на https://objects.lurazon.com/del
Для того, щоб видалити об'єкти, необхідно в масив "list" додати перелік їх ідентифікаторів - рядкових значень "id", переданих під час додавання:
Ідентифікатори, яких немає на сайті, ігноруються. Відповідь з кодом 200 - словник з ключем "failed" - масивом ідентифікаторів об'єктів, які не видалено через помилку запису. Коди 400, 413 та 403 - як в API додавання/оновлення