Інтеграція з «1С», «ERP», CRM-системами та CommerceAPI
Автоматичний експорт при замовленні / Відправка POST даних про замовлення у JSON форматі
Автоматичний експорт при замовленні ви можете включити в налаштуваннях сайту, у вкладці «Магазин», вказавши шлях для відправки даних.На вказану адресу буде відправлятися POST запит, з усіма даними про замовлення, в тому числі контактні дані замовника та перелік товарів. Контактні дані та інформація про замовлення буде передаватися у JSON форматі, POST запитом.
Наприклад, в 1С ви можете реалізувати прийом замовлень через «HTTP сервіс»->«SiteExchange» -> «POSTData»
Якщо після відправки запиту, ваш сервіс поверне JSON дані з вмістом «Number» або «crm_order_id», то до замовлення буде додано зовнішній номер замовлення.
Автоматичний експорт статистики продажів / Відправка POST даних про замовлення у JSON форматі
Автоматичний експорт статистики продажів ви можете включити в налаштуваннях сайту, у вкладці «Магазин», вказавши шлях для відправки даних.На вказану адресу буде відправлятися POST запит, з усіма даними про замовлення, які змінюються в Статистиці продажів. Інформація буде передаватися POST запитом у JSON форматі.
Наприклад, в 1С ви можете реалізувати прийом замовлень через «HTTP сервіс»->«SiteExchange» -> «POSTData»
Крім того ви можете включити зовнішній доступ до вашої статистики, вказавши «Ключ для доступу до статистики продажів».
Доступ до статистики продажів / JSON
Вкажіть ключ для доступу до статистики продажів в налаштуваннях, у вкладці «Магазин». Якщо вам необхідно отримати доступ до статистики продажів зовнішнім додатком, то ви можете виконати (POST/GET або AJAX) запит за адресою «
/ajax.php?statistic_sell» При цьому необхідно вказати ключ у запиті, з шифруванням MD5. Наприклад, якщо у вас вказано ключ «123», то в запиті це буде «
202cb962ac59075b964b07152d234b70».В такому випадку запит буде виглядати так: «
/ajax.php?statistic_sell&key=202cb962ac59075b964b07152d234b70»
В запиті можна вказати дані для сортування або пошуку (GET/POST параметри), які можна взяти на вашій сторінці статистики продажів в адмін-центрі (
/page.php?p=statistic_sell&mystat). Сортування та вибір параметрів здійснюється GET/POST запитом, наприклад, «&sort_dateperiod=1week» означає, що буде відображатися статистика продажів за тиждень. Дані відображаються у JSON форматі.
Зверніть увагу, що якщо ви використовуєте відкриті для відвідувачів запити на сторінці, то за допомогою вашого ключа вони зможуть отримати доступ до вашої статистики продажів.
Доступ до прайсу магазину / Повне вивантаження прайсу в CSV
Вкажіть ключ для доступу до прайсу магазину в налаштуваннях, у вкладці «Магазин». Повне вивантаження прайсу знаходиться за адресою «/csv_export_products.csv»
При цьому необхідно вказати ключ у запиті, з шифруванням MD5. Наприклад, якщо у вас вказано ключ «123», то в запиті це буде «
202cb962ac59075b964b07152d234b70».В такому випадку запит буде виглядати так: «
/csv_export_products.csv?key=202cb962ac59075b964b07152d234b70»
В запиті можна вказати дані для сортування та вибірки полів, які можна взяти на вашій сторінці експорту в адмін-центрі (/page.php?p=submit_catalog_page&subpage&export_from_shop). Сортування та вибір параметрів здійснюється GET/POST запитом, наприклад, «
&export_product_access=export_product_access» означає, що буде вивантажуватися поле з даними про доступ до товару. Дані відображаються у CSV форматі.
Файл вивантаження кешується для зменшення навантаження та оновлюється раз на добу. Видалити кеш можна за допомогою кнопки «Очистити кеш XML/CSV вивантажень».
Приклад: https://templatedemo437544.boostore.pro/csv_export_products.csv?key=202cb962ac59075b964b07152d234b70
Додатково реалізовано механізм обміну даними через API, схожий з WooCommerce API. API дозволяє отримувати та оновлювати інформацію про замовлення та товари, а також категорії. Інструкції та налаштування в розділі «Магазин» - «Обмін даними JSON Commerce API».
Commerce API (Products/Categories/Sales Statistics)
Commerce API — Короткий мануал за методами
Ключ доступу
Для роботи з API потрібен ключ доступу (Consumer Secret), який ви створюєте в розділі «Налаштування», «Магазин», «Доступ до статистики продажів». Ключ формується на основі Ключа для доступу до статистики продажів.
Методи API (HTTP)
Всі запити йдуть на базовий URL вашого сайту, наприклад: https://site.com/api/commerce/
1. Статистика продажів
| Метод | URL | Опис |
|---|---|---|
GET |
/orders |
Отримати статистику замовлень |
GET |
/orders/{id} |
Отримати статистику окремого замовлення за ID |
GET |
/crm_orders/{id} |
Отримати статистику окремого замовлення за зовнішнім CRM ID |
DELETE |
/orders/{id} |
Видалити замовлення за ID |
DELETE |
/crm_orders/{id} |
Видалити замовлення за зовнішнім CRM ID |
POST |
/orders |
Додати нове замовлення |
UPDATE |
/orders/{id} |
Оновити замовлення за ID (PATCH/PUT/UPDATE) |
UPDATE |
/crm_orders/{id} |
Оновити замовлення за зовнішнім CRM ID (PATCH/PUT/UPDATE) |
2. Товари
| Метод | URL | Опис |
|---|---|---|
POST |
/products |
Масове додавання та оновлення товарів |
GET |
/products |
Отримати список товарів |
GET |
/products/{id} |
Перегляд окремого товару за ID |
GET |
/products/sku/{sku} |
Перегляд окремого товару за SKU (кодом товару) |
UPDATE |
/products/{id} |
Оновити товар за ID (PATCH/PUT/UPDATE) |
UPDATE |
/products/sku/{sku} |
Оновити товар за SKU (кодом товару) (PATCH/PUT/UPDATE) |
UPDATE |
/products |
Масове оновлення кількох товарів (PATCH/PUT/UPDATE) |
DELETE |
/products/{id} |
Видалити товар за ID |
DELETE |
/products/sku/{sku} |
Видалити товар за SKU (кодом товару) |
3. Категорії магазину
| Метод | URL | Опис |
|---|---|---|
POST |
/products/categories |
Масове додавання та оновлення категорій |
GET |
/products/categories |
Отримати список категорій товарів |
GET |
/products/categories/{id} |
Отримати категорію за ID |
GET |
/products/categories/id/{id} |
Отримати категорію за ID (альтернативний варіант) |
GET |
/products/categories/name/{name} |
Отримати категорію за іменем |
UPDATE |
/products/categories |
Масове оновлення кількох категорій (PATCH/PUT/UPDATE) |
UPDATE |
/products/categories/{id} |
Оновити категорію за ID (PATCH/PUT/UPDATE) |
UPDATE |
/products/categories/id/{id} |
Оновити категорію за ID (альтернативний варіант) |
UPDATE |
/products/categories/name/{name} |
Оновити категорію за іменем |
Параметри батьківських категорій
| Параметр | Тип | Опис |
|---|---|---|
category_parent_id |
int | ID батьківської категорії. Використовується в першу чергу, якщо заданий. |
category_parent_name |
string | Латинське ім'я (alias / slug) батьківської категорії. Використовується, якщо category_parent_id не заданий. |
category_lang |
string | Мова категорії. Застосовується для вирішення колізій в іменах. |
Принцип роботи:
- Спочатку перевіряється
category_parent_id. - Якщо він не заданий – використовується
category_parent_name. - При збігу імен – додається перевірка за
category_lang.
Особливе правило:
Щоб додати категорію в кореневу (основну) категорію, необхідно вказати category_parent_name = "main" та обов'язково задати параметр category_lang.
Оновлення та видалення:
update_exists (bool) – якщо true, оновлює категорію при повторному додаванні.
delete (bool) – якщо true, категорія буде видалена.
4. Виробники
| Метод | URL | Опис |
|---|---|---|
POST |
/products/producers |
Масове додавання та оновлення виробників |
GET |
/products/producers |
Отримати список виробників |
GET |
/products/producers/{id} |
Отримати виробника за ID |
GET |
/products/producers/id/{id} |
Отримати виробника за ID (альтернативний варіант) |
GET |
/products/producers/name/{name} |
Отримати виробника за іменем |
UPDATE |
/products/producers |
Масове оновлення кількох виробників (PATCH/PUT/UPDATE) |
UPDATE |
/products/producers/{id} |
Оновити виробника за ID (PATCH/PUT/UPDATE) |
UPDATE |
/products/producers/id/{id} |
Оновити виробника за ID (альтернативний варіант) |
UPDATE |
/products/producers/name/{name} |
Оновити виробника за іменем |
Параметри прив'язки виробників
| Параметр | Тип | Опис |
|---|---|---|
producer_parent_id |
int | ID батьківського виробника (групи). Використовується в першу чергу. |
producer_parent_name |
string | Латинське ім'я (alias / slug) батьківського виробника. |
producer_lang |
string | Мова виробника для вирішення колізій імен. |
Принцип роботи:
- Спочатку перевіряється
producer_parent_id. - Якщо він не заданий – використовується
producer_parent_name. - При збігу імен – додається перевірка за
producer_lang.
Особливе правило:
Щоб додати виробника в кореневу (основну) групу виробників, необхідно вказати producer_parent_name = "main" та обов'язково задати параметр producer_lang.
Оновлення та видалення:
update_exists (bool) – якщо true, оновлює виробника при повторному додаванні (за замовчуванням false).
delete (bool) – якщо true, виробник буде видалений.
5. Колекції
| Метод | URL | Опис |
|---|---|---|
POST |
/products/collections |
Масове додавання та оновлення колекцій |
GET |
/products/collections |
Отримати список колекцій |
GET |
/products/collections/{id} |
Отримати колекцію за ID |
GET |
/products/collections/id/{id} |
Отримати колекцію за ID (альтернативний варіант) |
GET |
/products/collections/name/{name} |
Отримати колекцію за іменем |
UPDATE |
/products/collections |
Масове оновлення кількох колекцій (PATCH/PUT/UPDATE) |
UPDATE |
/products/collections/{id} |
Оновити колекцію за ID (PATCH/PUT/UPDATE) |
UPDATE |
/products/collections/id/{id} |
Оновити колекцію за ID (альтернативний варіант) |
UPDATE |
/products/collections/name/{name} |
Оновити колекцію за іменем |
Параметри прив'язки колекцій
| Параметр | Тип | Опис |
|---|---|---|
collection_parent_id |
int | ID батьківської колекції. Використовується в першу чергу. |
collection_parent_name |
string | Латинське ім'я (alias / slug) батьківської колекції. |
collection_lang |
string | Мова колекції для вирішення колізій імен. |
Принцип роботи:
- Спочатку перевіряється
collection_parent_id. - Якщо він не заданий – використовується
collection_parent_name. - При збігу імен – додається перевірка за
collection_lang.
Особливе правило:
Щоб додати колекцію в кореневу (основну) колекцію, необхідно вказати collection_parent_name = "main" та обов'язково задати параметр collection_lang – мова батьківської колекції.
Оновлення та видалення:
update_exists (bool) – якщо true, оновлює колекцію при повторному додаванні (за замовчуванням false).
delete (bool) – якщо true, колекція буде видалена.
6. Сортування та пагінація
Для методів /orders та /products доступні параметри для посторінкового виведення та сортування:
Параметри пагінації
| Параметр | Тип | Опис |
|---|---|---|
page |
int | Номер сторінки (за замовчуванням 1) |
per_page |
int | К-сть елементів на сторінку (за замовчуванням 90, максимум 2000) |
Параметри сортування
| Параметр | Тип | Допустимі значення | Опис |
|---|---|---|---|
orderby |
string | id, title, price, date, views |
Поле для сортування |
order |
string | asc, desc |
Напрямок сортування |
Параметри мови
| Параметр | Тип | Допустимі значення | Опис |
|---|---|---|---|
l |
string | ru, ua, en, de, fr, es, it, pl |
Мова відображення значень |
Додатково для замовлень
Можна фільтрувати замовлення за датою та статусом:
?after=YYYY-MM-DD— Початкова дата (у форматі ISO)?before=YYYY-MM-DD— Кінцева дата?status=pending|processing|on-hold|completed|cancelled|0|1|2|3|5|6|7|8— Статус замовлення0— Не опрацьовані (pending)1— Замовлення в обробці (processing)7— Замовлення в обробці, очікує поставки (on-hold)3— Опрацьовані (completed)8— Опрацьовані та завершені (completed)2— Скасовані (cancelled)5— Скасовані: немає в наявності (cancelled)6— Скасовані: відмова (cancelled)?show_deleted=1— Показати приховані замовлення
Приклади
GET /orders?page=2&per_page=100&after=2024-06-01&before=2024-06-30
GET /products?orderby=price&order=asc&per_page=50
Приклад авторизації в запиті
У запиті передаються ключі:
?consumer_secret=ВАШ_СЕКРЕТ (увага не публікуйте ключ у загальний доступ!)
Або через заголовок Authorization з OAuth 1.0a.
Додати нове замовлення (POST /orders)
Щоб створити нове замовлення через API, потрібно відправити POST-запит на /orders з JSON-тілом.
Обов'язково повинно бути вказано мінімум:
email— Email покупця (обов'язково!)line_items— Список додаваних товарів
Параметри замовлення
При створенні замовлення можна вказувати додаткові поля, наприклад:
{
"first_name": "Name",
"last_name": "Soname",
"email": "alex@example.com",
"phone": "+380671112233",
"address": "Full address of not used address eform",
"buyer_address_eform1": "State",
"buyer_address_eform2": "City",
"buyer_address_eform3": "Street",
"buyer_address_eform4": "house number",
"buyer_address_eform5": "flat",
"postcode": "01001",
"total": "999",
"status": "processing",
"status_for_customer": "processing",
"line_items": [ ... ]
}
Опис поля total:
-
total— фінальна сума замовлення (рядок або число). Якщо це поле вказано, воно буде використано як підсумкова ціна замовлення. - Якщо
totalне вказано, сума замовлення буде автоматично перерахована за сумою доданих товарів уline_items. - Поле
totalне є обов'язковим і може бути використано для замовлень без товарів.
Формат line_items
Параметр line_items — це масив товарів, кожен товар задається об'єктом з наступними полями:
"line_items": [
{
"product_id": 478734,
"quantity": 1,
"price": 100,
"currency": "USD"
},
{
"product_id": 478268,
"quantity": 10,
"variation": "51"
},
{
"product_id": 478266,
"quantity": 1,
"variation_id": 735302
}
]
- product_id — ID товару (обов'язково!).
- quantity — Кількість одиниць товару (обов'язково!).
- price — (необов'язково) Якщо вказана ціна — береться саме ця ціна і не обчислюється за даними сайту.
-
currency — (необов'язково) Валюта конкретного товару (наприклад,
USDабоUAH). Якщо вказана та відрізняється від загальної валюти замовлення (currency), система сконвертує ціну автоматично. - variation_id — ID різновиду (варіації товару) — спосіб вказати різновид, якщо він є.
-
variation — Назва або код різновиду — використовується якщо немає
variation_id. Якщо вказані обидва — пріоритет уvariation_id.
Важно: Якщо загальна валюта замовлення (currency) не вказана — буде використовуватися валюта за замовчуванням для сайту.
Якщо валюта товару відрізняється від загальної валюти — ціна конвертується автоматично.
Оновлення товарів
Оновлення товару здійснюється через HTTP-метод UPDATE (або PATCH/PUT) за URL із вказанням ID товару або його SKU (коду товару), або одразу кількох товарів одним запитом:
/products/{id}— оновлення товару за ID/products/sku/{sku}— оновлення товару за кодом (SKU)/products— масове оновлення кількох товарів (до 5000 за один запит)
При масовому оновленні шлях /products не містить ID або SKU. У цьому випадку необхідно передавати масив об'єктів товарів у параметрі products. Кожен елемент масиву повинен містити хоча б id або sku. Якщо вказаний id, він має пріоритет і може використовуватися для заміни коду товару (sku). Якщо id не вказаний, пошук здійснюється за sku — кодом товару.
При оновленні передається повний набір даних товару у форматі JSON. Всі передані дані замінюють існуючі значення, включаючи:
- Основні властивості товару (назва, опис, ціни, статус та ін.)
- Атрибути (характеристики)
- Варіації (різновиди товару)
- Зображення
- Категорії та теги
- Додаткові налаштування та мета-поля
Оновлення варіацій відбувається з використанням наступного алгоритму для кожної варіації з масиву variations:
- Якщо у варіації вказаний
id, оновлення проводиться за ним. - Якщо
idвідсутній, але вказанийsku(код варіації), пошук та оновлення відбувається за ним. - Якщо немає ні
id, ніsku, але єtitle(назва варіації), пошук та оновлення проводиться за назвою. - Якщо варіація не знайдена за вказаними критеріями, створюється нова варіація із заданими параметрами.
Оновлення за SKU зручне, коли ID варіації невідомий, але відомий унікальний код.
При оновленні всі поля, вказані в JSON, замінять поточні значення товару; щоб залишити якесь поле без змін, просто не включайте його в запит.
- Дублікати різновидів: якщо в масиві різновидів зустрічаються повторювані за кодом (SKU) та назвою (title), такі різновиди будуть пропущені — одна й та сама комплектація не додасться двічі.
- Головне зображення: у масиві
imagesголовним вважається те, що під індексом0. Якщоimages[0]відсутнє або не завантажено, головним стане перше успішно завантажене зображення. - Максимум зображень: для одного товару можна завантажити не більше 10 зображень. Якщо спробувати завантажити більше, зайві файли будуть проігноровані.
-
Робота із зображеннями:
- Видалення зображень: щоб видалити зображення за індексом, вкажіть для елемента масиву
imagesзначення"delete". Наприклад,images[2] = "delete"видалить файл з індексом 2. Можна видаляти та завантажувати одночасно, вказуючи кілька ключів:images[3] = "delete",images[1] = "https://...". - Пропуски індексів зображень: якщо вказати порожній рядок або
false, цей індекс буде пропущений без помилок. - Перезапис зображень: параметр
images_replace: якщоtrue, система перезапише існуючі файли зображень за переданими індексами (видалить старий файл та кеш). Якщоfalseабо не вказаний — перезапис заборонено. - Пропуск зайнятих індексів: параметр
images_skip_index: якщоtrue, то при зайнятому індексі та забороненому перезаписі система знайде наступний вільний індекс і збереже файл туди. Якщоfalseабо не вказаний — індекс береться строго як переданий. - Збереження під новим індексом при конфлікті: параметр
images_replace_new_index: якщоtrue, то при зайнятому індексі та відключених перезаписі та автоматичному пропуску файл буде збережений під новим вільним індексом. Якщо всі три параметриfalseабо не задані та індекс зайнятий — файл не буде завантажений.
- Видалення зображень: щоб видалити зображення за індексом, вкажіть для елемента масиву
Параметри товару
Доступні значення ви можете переглянути в коді прикладів нижче. Також наведена додаткова розшифровка деяких значень, яка може бути корисною.
-
Доступні значення
price_forДля кожного товару можна вказати параметр
price_for, який задає одиницю виміру ціни. Допустимо використовувати числовий код або текст (наприклад, «За 1 кг» або «Per 1 kg»). Ось повний список значень:Можна використовувати як числове значення, так і текст — система автоматично розпізнає і приведе до правильного коду.
-
Доступні значення
stock_statusДля кожного товару можна вказати параметр
stock_status, який визначає статус доступності товару та його поведінку на сайті. Можна використовувати числовий код або ключове слово — система розпізнає обидва варіанти.Можна використовувати як числове значення, так і текст — система автоматично розпізнає і приведе до правильного коду.
Якщо для товару вибраний варіант
3, він буде прихований зі списків товарів на сайті. Якщо вибраний варіант4, товар буде видимий, але його не можна буде додати в кошик. Варіант5показує покупцю, що наявність потрібно уточнити. -
Акція та Доступні значення
promotion_expires_jobДля кожного товару можна вказати параметр
promotion_expires_job, який керує тим, що робити з акцією після закінчення її терміну.
Можна використовувати числовий код або ключове слово — система розпізнає обидва варіанти.Можна вказувати як числове значення, так і текст — система автоматично розпізнає і приведе до потрібного коду.
Важно: Для активації таймера акції обов'язково вкажіть
promotionрівним1— це означає, що акція активна.Також необхідно вказати дату закінчення акції в параметрі
promotion_expires— вона може бути задана як UNIX-час (наприклад,time()), так і у форматіYYYY-MM-DDTHH:MM:SS+00:00(наприклад,2025-06-28T00:00:00+00:00).
Додавання товарів
Цей метод дозволяє додати один або кілька товарів одним запитом (до 3000 за один запит).
Формат запиту повністю збігається з методом оновлення: можна передавати масив products
або одиночний товар.
- Пошук за ID: при додаванні нового товару поле
idповинно бути порожнім або відсутнім. Якщоidвказаний і товар з таким ID вже існує, то система оновить цей товар замість створення нового. - Пошук за кодом (SKU): перед додаванням система перевіряє, чи є товар з таким SKU. Якщо такий товар знайдений, він буде оновлений, а не створений заново.
Ви можете додати нові товари та оновити існуючі одним запитом.
Це базовий опис основних методів для роботи з Commerce API / WooCommerce API v3 по замовленнях, товарах і категоріях.
Нижче розташовані скрипти з прикладами, які допоможуть правильно використовувати методи API на практиці.