English

Домовленості¶

Однакові правила діють на кожному ендпоінті — вивчіть їх один раз.

Конверт відповіді¶

Успіх:

{
  "success": true,
  "data": { /* об'єкт */ } ,
  "meta": { /* опційно: пагінація, баланси, чеки */ }
}

data — це або один об'єкт, або масив, залежно від ендпоінта. meta присутній на списках (пагінація) та на записах, що дають додаткові дані (новий баланс рахунку, фіскальний чек, …).

Помилка:

{
  "success": false,
  "error": { "code": "validation_error", "message": "name is required",
             "details": { "field": "name" } }
}

code — стабільний рядок (див. Помилки); message — читабельний текст; details — опційний структурований контекст. HTTP-статус відповідає помилці (4xx/5xx).

Типи даних¶

Тип	Правило	Приклад
Гроші	точний рядок-decimal, ніколи не float	`"1234.50"`
Час	ISO-8601, UTC	`"2026-07-20T08:28:59"`
Кількість	число (ціле, якщо без дробу)	`3`, `1.5`
Булеве	справжнє `true`/`false` (не `0`/`1`)	`true`
Відсутнє значення	`null` (внутрішні `0`/`""` нормалізуються)	`null`
Ключі	`snake_case`	`warehouse_id`

Гроші — це рядок, щоб ви не втрачали точність на float. Розбирайте його decimal-типом.

Пагінація¶

Списки приймають ?limit= та ?offset=:

curl "https://crm.h-profit.com/bapi-v2/products?limit=50&offset=100" \
  -H "Authorization: hp_live_ваш_ключ"

limit обмежується максимумом ресурсу (дефолти різні; напр. products 100, sales до 5000).
Блок meta віддзеркалює пагінацію:

{ "meta": { "limit": 50, "offset": 100 } }

Гортайте, збільшуючи offset, доки не отримаєте менше ніж limit рядків.

Отримати весь список одним запитом¶

Довідникові ресурси — suppliers, categories, product_sync — теж пагіновані за замовчуванням, але весь список можна витягнути одним запитом через ?all=1:

curl "https://crm.h-profit.com/bapi-v2/categories?all=1" \
  -H "Authorization: hp_live_ваш_ключ"

meta.limit повертається як null — ознака, що обмеження не застосовувалось:

{ "meta": { "limit": null, "offset": 0, "total": 820 } }

Використовуйте ?all=1, коли потрібен повний набір локально (дерево категорій, мапа товар→remote-прив'язка); для великих таблиць віддавайте перевагу звичайній пагінації. (categories?tree=1 теж повертає весь набір, уже вкладеним.)

HTTP-методи¶

Метод	Значення
`GET`	читання (список або один)
`POST`	створення (або масова дія)
`PUT`	оновлення
`DELETE`	видалення

Тіла запитів — JSON (Content-Type: application/json). Фільтри для GET — у query-рядку; тіла для POST/PUT/DELETE — у JSON.

Ліміт запитів¶

Кожен API-ключ може робити 120 запитів на хвилину. Хвилина починається з першого запиту ключа, і рахуються всі запити, зокрема ті, що завершилися помилкою. Складений /query рахується як один запит. Кожна відповідь показує поточний стан:

Заголовок	Значення
`X-RateLimit-Limit`	скільки запитів дозволено на хвилину
`X-RateLimit-Remaining`	скільки запитів лишилося в поточній хвилині
`X-RateLimit-Reset`	за скільки секунд лічильник обнулиться

Понад ліміт API відповідає 429 з code: rate_limited і заголовком Retry-After (скільки секунд почекати). Якщо інтеграції потрібен більший ліміт — зверніться до підтримки.

CORS¶

Усі відповіді надсилають дозвільні CORS-заголовки (Access-Control-Allow-Origin: *) і відповідають на OPTIONS preflight кодом 204, тож API можна викликати з браузера.

Локалізація¶

Деякі значення (назви категорій, одиниці) локалізуються під мову акаунта власника ключа, а не запиту. Перемикача мови на рівні запиту немає.