Загрузка / Выгрузка данных через 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 доступны по этой ссылке.
Вы можете протестировать различные режимы работы, для этого необходимо активировать нужную переменную для активации блока кода отвечающего за необходимую операцию и элемент.