API v1

Опис API

Цей опис для CRM або іншої системи, яка читає каталог. Ключ видає адміністратор магазину. Ціни передаються цілими копійками.

Той самий контракт для моделі: Markdown, OpenAPI, /api/llms.txt.

Авторизація

Ключ передається в кожному запиті.

Authorization: Bearer {key}
Accept: application/json

Базова адреса: https://ouroborosbooks.com.ua/api/v1/integrations

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

GET https://ouroborosbooks.com.ua/api/v1/integrations/products

Параметр	Значення
page	Номер сторінки, від 1.
limit	Розмір сторінки. Типово 15, максимум 50.
filter[name]	Частина назви товару.
filter[sku]	Точний артикул.
include=offers	Додати варіанти в offers.

curl -H "Authorization: Bearer {key}" \
  -H "Accept: application/json" \
  "https://ouroborosbooks.com.ua/api/v1/integrations/products?limit=15&filter[sku]=SKU-1&include=offers"

{
  "current_page": 1,
  "data": [
    {
      "id": 12,
      "name": "Product",
      "sku": "SKU-1",
      "quantity": 5,
      "currency_code": "UAH",
      "min_price": 49000,
      "max_price": 49000,
      "has_offers": false,
      "is_archived": false,
      "category_id": 3
    }
  ],
  "per_page": 15,
  "total": 1,
  "from": 1,
  "to": 1,
  "last_page": 1
}

Один товар

GET https://ouroborosbooks.com.ua/api/v1/integrations/products/{id}

Товар повертається в data. include=offers додає варіанти і тут. Невідомий id повертає 404.

Поля

Поле	Значення
id	Ідентифікатор товару в цьому магазині.
name, description, sku	Назва, текстовий опис і артикул першого варіанта.
quantity	Сума залишків варіантів.
currency_code	Валюта магазину.
min_price, max_price	Найменша і найбільша ціна варіанта, у копійках. 49000 означає 490.00.
weight, length, height, width	Габарити першого варіанта або null.
has_offers	Так, якщо у товару більше одного варіанта.
is_archived	Так, якщо товар не опублікований.
category_id	Ідентифікатор першої категорії або null.
offers	Лише з include=offers. У варіанта є id, sku, price, quantity, properties.

Права ключа

Ключ може оновлювати товари і при цьому не бачити замовлення. MCP отримає ті самі права.

catalog:read	GET /products
catalog:write	PUT/PATCH /catalog/products/{external_id}, PUT /catalog/categories/{external_id}, PUT /catalog/tags/{external_id}
orders:read	GET /orders?updated_since=&cursor=
orders:write-status	POST /orders/{reference}/status
content:read	GET /content/pages
content:write	PUT /content/pages/{external_id}, POST .../publish, POST .../unpublish

Кожен ключ має власні 60 запитів за хвилину. Відповідь 429 містить Retry-After. Помилка завжди має code, message і field. Запис товару приймає image_url. Список сторінок іде курсором cursor і limit.

Помилки

401 — ключа немає, він невідомий або відкликаний.
403 — у ключа немає права catalog:read.
404 — товару з таким id немає.