Товари та замовлення

Відкритий API

/erp/api/v1/

Товари, категорії та замовлення — читання й завантаження. Саме через цей API працює плагін синхронізації з WooCommerce.

Доступ

Токен у заголовку. Отримати або перевипустити — у налаштуваннях модуля «Товари та замовлення». Токен доступний на платному тарифі: без нього запит повернеться з 403.

Authorization: Bearer <token>
X-API-Key: <token>

Обидва заголовки рівнозначні — достатньо одного.

Ліміти й режими

Ліміт запитів: Немає. Основний споживач цього API — плагін WooCommerce, який надсилає дані при кожній зміні товару чи замовлення; різати його квотою немає за що.
Ідемпотентність: Ingest-ендпоінти впізнають обʼєкт за парою external_id + source, тож той самий товар можна надсилати скільки завгодно разів — дубліката не буде.
Формат: Спільний для всіх модулів ClearMoney: англомовні поля й повідомлення, помилка як обʼєкт із code. До вересня 2026 цей модуль віддавав українські рядки без кодів — тепер він такий самий, як «Послуги».

Ендпоінти

GET /erp/api/v1/products/

Список товарів

Усі товари акаунта разом із залишками, цінами й атрибутами.

Параметри й приклади

Параметри запиту

Параметр	Обовʼязковий	Опис
`q`	ні	Пошук за назвою або SKU (частковий збіг).

Відповідь 200

{
  "count": 2,
  "results": [
    {
      "id": 41,
      "name": "Гель-лак рожевий",
      "sku": "GL-001",
      "category": "Матеріали",
      "category_id": 7,
      "price": "320.00",
      "sale_price": null,
      "display_price": "320.00",
      "status": "publish",
      "in_stock": true,
      "manage_stock": true,
      "stock_qty": "12.000",
      "unit": "pcs",
      "pack_size": "1.000",
      "image_url": "https://clearmoney.com.ua/media/products/gel.jpg",
      "short_description": "",
      "attributes": [
        {"name": "Колір", "values": ["Рожевий"]}
      ]
    }
  ]
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}

GET /erp/api/v1/products/<id>/
Один товар

Той самий обʼєкт, що й у списку, за внутрішнім ID.
Параметри й приклади

Помилки й тіла відповідей
- 401 missing_token
  {"error": {"code": "missing_token", "message": "Authorization header is missing."}}
- 401 invalid_token
  {"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
- 403 plan_required
  {"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
- 405 method_not_allowed
  {"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
- 404 not_found
  {"error": {"code": "not_found", "message": "Object does not exist."}}
GET /erp/api/v1/categories/
Категорії

Дерево категорій із кількістю товарів у кожній.
Параметри й приклади

Відповідь 200
```
{
  "count": 1,
  "results": [
    {"id": 7, "name": "Матеріали", "slug": "materialy",
     "parent_id": null, "product_count": 12}
  ]
}
```
Помилки й тіла відповідей
- 401 missing_token
  {"error": {"code": "missing_token", "message": "Authorization header is missing."}}
- 401 invalid_token
  {"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
- 403 plan_required
  {"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
- 405 method_not_allowed
  {"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}

GET /erp/api/v1/orders/

Список замовлень

Замовлення без позицій — короткий вигляд для списків.

Параметри й приклади

Параметри запиту

Параметр	Обовʼязковий	Опис
`status`	ні	pending · processing · on-hold · completed · cancelled · refunded · failed

Відповідь 200

{
  "count": 1,
  "results": [
    {
      "id": 305,
      "customer": "Олена Коваль",
      "first_name": "Олена",
      "last_name": "Коваль",
      "status": "processing",
      "payment_method": "card",
      "shipping_method": "nova",
      "total": "640.00",
      "created_at": "2026-09-04T11:20:00+03:00"
    }
  ]
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}

GET /erp/api/v1/orders/<id>/
Одне замовлення

Повний обʼєкт: контакти, адреса, примітка і позиції.
Параметри й приклади

Відповідь 200
```
{
  "id": 305,
  "customer": "Олена Коваль",
  "status": "processing",
  "total": "640.00",
  "created_at": "2026-09-04T11:20:00+03:00",
  "email": "[email protected]",
  "phone": "+380671112233",
  "shipping_address": "Київ, Нова пошта №12",
  "note": "",
  "items": [
    {
      "product_id": 41,
      "variation_id": null,
      "name": "Гель-лак рожевий",
      "sku": "GL-001",
      "attributes": "Колір: Рожевий",
      "image_url": "",
      "price": "320.00",
      "quantity": 2,
      "subtotal": "640.00"
    }
  ]
}
```
Помилки й тіла відповідей
- 401 missing_token
  {"error": {"code": "missing_token", "message": "Authorization header is missing."}}
- 401 invalid_token
  {"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
- 403 plan_required
  {"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
- 405 method_not_allowed
  {"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
- 404 not_found
  {"error": {"code": "not_found", "message": "Object does not exist."}}

POST /erp/api/v1/ingest/products/

Завантажити товари

Upsert за парою (external_id, source). Той самий товар можна надсилати повторно при кожній зміні — дубліката не буде. Приймає одиночний обʼєкт, {"products": [...]} або сирий список.

Параметри й приклади

Поля тіла запиту

Поле	Обовʼязкове	Опис
`external_id`	так	ID товару у вашій системі.
`source`	ні	Джерело; за замовчуванням woocommerce.
`name`	ні	Назва. Якщо не передати — лишається наявна.
`sku`	ні	Артикул.
`price`	ні	Ціна, десятковий рядок або число.
`sale_price`	ні	Акційна ціна; null — прибрати.
`categories`	ні	Список назв категорій; створюються за потреби.
`stock_managed`	ні	Чи вести облік залишків.
`stock_qty`	ні	Залишок.
`in_stock`	ні	Наявність; за замовчуванням true.
`status`	ні	Статус публікації.
`image_url`	ні	Посилання на зображення.
`short_description`	ні	Короткий опис.
`description`	ні	Повний опис.

Зірочка означає «одне з двох» — достатньо будь-якого.

Запит

{
  "products": [
    {
      "external_id": "8842",
      "source": "woocommerce",
      "name": "Гель-лак рожевий",
      "sku": "GL-001",
      "price": "320.00",
      "categories": ["Матеріали"],
      "stock_managed": true,
      "stock_qty": 12,
      "in_stock": true
    }
  ]
}

Відповідь 200

{"synced": 1, "ids": [41]}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
400 invalid_json
{"error": {"code": "invalid_json", "message": "Request body is not a valid JSON object."}}

POST /erp/api/v1/ingest/products/delete/

Видалити товари

Видалення за external_id вашої системи.

Параметри й приклади

Поля тіла запиту

Поле	Обовʼязкове	Опис
`external_ids`	так*	Список ID у вашій системі.
`external_id`	так*	Один ID — альтернатива списку.

Зірочка означає «одне з двох» — достатньо будь-якого.

Запит

{"external_ids": ["8842", "8843"]}

Відповідь 200

{"deleted": 2}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
400 invalid_json
{"error": {"code": "invalid_json", "message": "Request body is not a valid JSON object."}}

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Some fields failed validation.",
    "details": {
      "external_ids": "This field must be an array of ids."
    }
  }
}

POST /erp/api/v1/ingest/orders/

Завантажити замовлення

Upsert за (external_id, source). Якщо передати items, позиції перестворюються, а склад перераховується: попереднє списання повертається, нове застосовується за статусом замовлення.

Параметри й приклади

Поля тіла запиту

Поле	Обовʼязкове	Опис
`external_id`	так	ID замовлення у вашій системі.
`source`	ні	Джерело; за замовчуванням woocommerce.
`first_name / last_name`	ні	Імʼя та прізвище покупця.
`email / phone`	ні	Контакти.
`status`	ні	Статус; мапиться на внутрішні значення.
`payment_method`	ні	Спосіб оплати.
`shipping_method`	ні	Спосіб доставки.
`shipping_address`	ні	Адреса доставки.
`total`	ні	Сума замовлення.
`note`	ні	Примітка.
`date_created`	ні	Дата створення, ISO 8601.
`items[]`	ні	product_external_id, name, sku, attributes, image_url, price, quantity.

Зірочка означає «одне з двох» — достатньо будь-якого.

Запит

{
  "orders": [
    {
      "external_id": "10231",
      "status": "processing",
      "first_name": "Олена",
      "last_name": "Коваль",
      "phone": "+380671112233",
      "total": "640.00",
      "date_created": "2026-09-04T11:20:00+03:00",
      "items": [
        {
          "product_external_id": "8842",
          "name": "Гель-лак рожевий",
          "sku": "GL-001",
          "price": "320.00",
          "quantity": 2
        }
      ]
    }
  ]
}

Відповідь 200

{"synced": 1, "ids": [305]}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
400 invalid_json
{"error": {"code": "invalid_json", "message": "Request body is not a valid JSON object."}}

Усі помилки

Формат один на всі модулі. code стабільний — на нього і варто перевіряти; message англійською й може бути уточнений. У details — конкретні поля, якщо помилка про них. Тіло кожної помилки показане в самому ендпоінті, ось загальний вигляд:

{
  "error": {
    "code": "validation_error",
    "message": "Some fields failed validation.",
    "details": {
      "field_name": "What exactly is wrong with this field."
    }
  }
}

code	HTTP	message	Коли
`missing_token`	401	Authorization header is missing.	Немає ні Authorization: Bearer, ні X-API-Key.
`invalid_token`	401	Token is invalid or revoked.	Токена не існує або його відкликали в налаштуваннях модуля.
`plan_required`	403	Paid plan required for this token.	Токен працює лише на платному тарифі модуля «Товари та замовлення». Дані нікуди не зникають, але синхронізація зупиняється, поки підписку не поновлено.
`method_not_allowed`	405	HTTP method is not allowed for this endpoint.	Не той HTTP-метод. Дозволені перелічені в заголовку Allow.
`invalid_json`	400	Request body is not a valid JSON object.	Тіло запиту не розібралось як JSON.
`validation_error`	400	Some fields failed validation.	Поля не пройшли перевірку. Які саме й що з ними — у details.
`not_found`	404	Object does not exist.	Обʼєкта немає або він належить іншому акаунту — назовні це одне й те саме, щоб чужі id не можна було перебрати.

Спільні правила

Гроші рядками, дати ISO 8601, ізоляція даних за токеном, ідемпотентність ingest — однакові для всіх модулів і описані на головній документації.

Інші модулі

Облік доходів У планах
Послуги Відкритий API

Питання по інтеграції — у Telegram або на сторінці підтримки.

Товари та замовлення

Доступ

Ліміти й режими

Ендпоінти

Список товарів

Параметри запиту

Відповідь 200

Помилки й тіла відповідей

Один товар

Помилки й тіла відповідей

Категорії

Відповідь 200

Помилки й тіла відповідей

Список замовлень

Параметри запиту

Відповідь 200

Помилки й тіла відповідей

Одне замовлення

Відповідь 200

Помилки й тіла відповідей

Завантажити товари

Поля тіла запиту

Запит

Відповідь 200

Помилки й тіла відповідей

Видалити товари

Поля тіла запиту

Запит

Відповідь 200

Помилки й тіла відповідей

Завантажити замовлення

Поля тіла запиту

Запит

Відповідь 200

Помилки й тіла відповідей

Усі помилки

Спільні правила

Інші модулі