Завантаження / Вивантаження даних через API Elbuz

API надає доступ до інформації, що зберігається у базі даних програмного продукту Elbuz. Можливе отримання, додавання, оновлення та видалення елементів.

Формат обміну, автентифікація

• Для взаємодії використається формат JSON.
• Для запитів використовується метод HTTP POST.
• Для аутентифікації використовується логін та пароль для отримання токена.

Базова інформація

Обмеження доступу

• Доступ до API із зазначенням IP-адрес, з яких можливий доступ.
• Режим "лише читання" (блокує доступ на зміну даних).
• За кількістю запитів – не більше 30 з'єднань протягом 60 секунд.

Пагінація – посторінковий висновок

Виведення даних розбивається на сторінки. Максимальна кількість записів залежить від типу елемента, за промовчанням відображається 100 записів на одній сторінці. Щоб вказати номер сторінки, використовується параметр «page».

При відповіді формується "meta" інформація, приклад:

[meta] => Array
(
[item_scope] => category
[total_row] => 474
[page_total] => 5
[page_next] => 2
[page_current] => 1
[request_time] => 00:00:00
)

Опис meta інформації:

• item_scope – тип запитуваного елемента
• total_row – загальна кількість елементів
• page_total – загальна кількість сторінок
• page_next – номер наступної сторінки
• page_current – поточна сторінка
• request_time – час, витрачений для отримання інформації

Відбір елементів

Залежно від типу елемента доступні різні параметри, що обмежують вибірку даних, наприклад, можна отримати товари лише певної категорії, для цього необхідно передати параметр category_id у якому вказати ID категорії.

Обмеження полів, що виводяться

Система дозволяє збільшити швидкість роботи обмінюватись інформацією, отримуючи лише потрібні вам дані. Наприклад, картка товару може містити 150 полів, при цьому вам необхідно отримати тільки 10 з них, ви можете при запиті даних вказати потрібний вам набір полів, тим самим скоротити обсяг передаваних даних і збільшити швидкість як відповіді, так і час на подальшу обробку цієї інформації на вашому ресурсі. Для цієї мети використовується параметр limit_field в якому необхідно перерахувати потрібні поля через кому.

Опис роботи з API

Початкова адреса сервісу API: https://ваш_адреса_домена/admin/index.php?route=
Параметр route приймає шлях, на основі якого система розуміє, яку операцію необхідно виконати.
Доступні такі значення для параметра route:

• api/login - отримання токена для початку роботи
• api/scope/describe – опис полів елементів
• api/scope/get – отримання елементів
• api/scope/add – додавання елементів
• api/scope/update – оновлення елементів
• api/scope/delete – видалення елементів

Параметр route може бути доповнений типом елемента, з яким виконується операція.
Залежно від типу операції доступні такі значення:

• category – категорії товарів
• product – товари базового каталогу
• product_price – товари з прайс-листів
• attribute – атрибути товарів
• attribute_block – блоки атрибутів
• language – мови
• article – статті
• manufacturer – виробники
• stock_status – статус наявності товару
• warehouse – склади
• store – магазини
• company – компанії
• contractor – контрагенти
• contractor_group – групи контрагентів
• currency – валюти
• document – документи
• document_type – типи документів
• document_status – статуси документів
• document_payment_status – статуси оплат
• document_delivery_status – статуси доставки

Приклад посилання для отримання списку категорій товарів: https://ваш_адрес_домена/admin/index.php?route=api/scope/get/category
Також тип елемента може бути переданий у параметрі scope через POST запит, тоді не потрібно вказувати тип посилання.

Створення користувача API, отримання токена

Обмін даними через API проводиться з використанням логіну та паролю (токену). Для створення нового користувача API перейдіть до підсистеми "Налаштування"

Потім виберіть "Доступ до API Jumper"

Натисніть кнопку + для створення нового користувача

Для початку роботи з API необхідно отримати токен, для цього необхідно надіслати запит POST з логіном та паролем із зазначенням route=api/login.
Повна адреса:
https://ваш_адреса_домена/admin/index.php?route=api/login

Обов'язкові параметри POST:

• username – ваш логін
• key – пароль

У відповідь ви отримаєте токен, який буде вказано в полі api_token, цей токен необхідно використовувати для подальших запитів до API.
Приклад реалізації мовою PHP (функція send_data_to_jumper_api() це обгортка для CURL)

Отримання елементів

Для отримання списку елементів необхідно отруїти запит POST із зазначенням route=api/scope/get.
Повна адреса:
https://ваш_адреса_домена/admin/index.php?route=api/scope/get

Обов'язкові параметри POST:

• api_token - токен отриманий раніше
• scope – код елемента, якого потрібно отримати дані. Код елемента можна вказати на посилання, тоді цей параметр не обов'язковий.
  
  Список доступних кодів елементів:
  • category – категорії товарів
  • product – товари базового каталогу
  • product_price – товари з прайс-листів
  • attribute – атрибути товарів
  • attribute_block – блоки атрибутів
  • language – мови
  • article – статті
  • manufacturer – виробники
  • stock_status – статус наявності товару
  • warehouse – склади
  • store – магазини
  • company – компанії
  • contractor – контрагенти
  • contractor_group – групи контрагентів
  • currency – валюти
  • document – документи
  • document_type – типи документів
  • document_status – статуси документів
  • document_payment_status – статуси оплат
  • document_delivery_status – статуси доставки

Необов'язкові параметри:

• page - номер сторінки для отримання наступного списку записів
• limit_field – список полів для обмеження виводу
• extend - Отримання розширених даних. Наприклад, при отриманні картки товару можна розширити інформацію та отримати додатково такі дані як:
  • attribute – атрибути товару
  • image – фото товару
  • category – перелік категорій, де знаходиться товар
• extend_limit_field_attribute – список полів для обмеження виведення розширеної інформації щодо атрибутів
• extend_limit_field_image – список полів для обмеження виведення розширеної інформації про фото
• extend_limit_field_category – список полів для обмеження виведення розширеної інформації про категорії

Приклад реалізації мовою PHP

Додавання елементів

Для додавання нового елемента необхідно отруїти запит POST із зазначенням route=api/scope/add.
Повна адреса:
https://ваш_адреса_домена/admin/index.php?route=api/scope/add

Обов'язкові параметри POST:

• api_token - токен отриманий раніше
• scope – код елемента, який потрібно додати. Код елемента можна вказати на посилання, тоді цей параметр не обов'язковий.
  
  Список доступних кодів елементів:
  • category – категорії товарів
  • product – товари базового каталогу
  • product_price – товари з прайс-листів
  • attribute – атрибути товарів
  • attribute_block – блоки атрибутів
  • article – статті
  • manufacturer – виробники
  • document – документи
• name – назва елемента (залежно від типу елемента можуть бути різні поля)

Приклад реалізації мовою PHP

Оновлення елементів

Для оновлення елемента необхідно отруїти запит POST із зазначенням route=api/scope/update.
Повна адреса:
https://ваш_адреса_домена/admin/index.php?route=api/scope/update

Обов'язкові параметри POST:

• api_token - токен отриманий раніше
• scope – код елемента, який потрібно оновити. Код елемента можна вказати на посилання, тоді цей параметр не обов'язковий.
  
  Список доступних кодів елементів:
  • category – категорії товарів
  • product – товари базового каталогу
  • currency – кури валют
  • contractor – контрагенти
• name – назва елемента (залежно від типу елемента можуть бути різні поля)

Приклад реалізації мовою PHP

Видалення елементів

Для видалення елемента необхідно отруїти запит POST із зазначенням route=api/scope/delete.
Повна адреса:
https://ваш_адреса_домена/admin/index.php?route=api/scope/delete

Обов'язкові параметри POST:

• api_token - токен отриманий раніше
• scope – код елемента, який потрібно видалити. Код елемента можна вказати на посилання, тоді цей параметр не обов'язковий.
  
  Список доступних кодів елементів:
  • category – категорії товарів
  • product – товари базового каталогу
  • attribute – атрибути товарів
  • attribute_block – блоки атрибутів
  • contractor – контрагенти
  • article – статті
  • manufacturer – виробники
  • document – документи
• ID елемента (залежно від типу елемента використовується різне ім'я поля)

Приклад реалізації мовою PHP

Опис полів елементів

Для отримання опису полів елементів необхідно отруїти запит POST із зазначенням route=api/scope/describe.
Повна адреса:
https://ваш_адреса_домена/admin/index.php?route=api/scope/describe

Обов'язкові параметри POST:

• api_token - токен отриманий раніше
• scope – код елемента, яким необхідно отримати інформацію. Код елемента можна вказати на посилання, тоді цей параметр не обов'язковий.
  
  Список доступних кодів елементів:
  • product – товари базового каталогу
  • product_price – товари з прайс-листів
  • manufacturer – виробники
  • contractor – контрагенти
  • document – документи
  • user – користувачі (співробітники)
  • company – компанії

Приклад реалізації мовою PHP

Розширений приклад роботи з API, мова PHP

Розширені приклади роботи з API з використанням мови PHP доступні за цим посиланням .
Ви можете протестувати різні режими роботи, для цього необхідно активувати потрібну змінну для активації блоку коду, який відповідає за необхідну операцію та елемент.