English

Автентифікація¶

Кожен запит (окрім GET /health) повинен містити API-ключ.

Ключ¶

Ключ v2 має вигляд:

hp_live_Jcv2S9xM3kQ8...    (hp_<env>_<random>)

Ви створюєте його в інтерфейсі (Налаштування інтеграції). Повний ключ показується один раз — під час створення — збережіть його надійно. Всередині ми зберігаємо лише префікс для пошуку та SHA-256 хеш, тож секрет неможливо відновити з нашої бази.

Передача ключа¶

Передавайте його в заголовку Authorization, з префіксом Bearer або без нього:

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

# те саме
curl https://crm.h-profit.com/bapi-v2/me \
  -H "Authorization: Bearer hp_live_ваш_ключ"

Відсутній або невірний ключ повертає 401:

{ "success": false, "error": { "code": "unauthorized", "message": "invalid or missing API key" } }

Scopes (дозволи)¶

Кожному ключу надається набір scopes у форматі resource:action, де action — це read або write. Приклади: sales:read, products:write, webhooks:write.

* або full надає все.
sales:* надає і sales:read, і sales:write.

Якщо ключу бракує потрібного scope, виклик повертає 403:

{ "success": false, "error": { "code": "forbidden", "message": "insufficient scope",
  "details": { "required": ["sales:write"] } } }

Префікс scope	Охоплює
`reference`	довідкові дані (`/reference`)
`warehouses` / `suppliers`	склади, постачальники
`products`	товари, залишки, зв'язки товар↔маркетплейс
`product_sync`	зв'язки `/product_sync`
`categories`	категорії товарів
`clients`	клієнти + теги
`sales`	продажі (таблиця `orders`)
`orders`	замовлення з маркетплейсів (`remote_orders`)
`shipments`	поставки / приймання
`expenses`	витрати
`productions`	рецепти та запуски виробництва
`delivery`	пошук міст і відділень (`read`), ТТН Нової Пошти (`write`, оплачується у вашому акаунті перевізника)
`webhooks`	підписки на вебхуки та доставки

Перевірка ключа: `GET /me`¶

Повертає контекст ключа — ніколи не секрет. Зручно для першої перевірки.

{
  "success": true,
  "data": {
    "user_id": 11,
    "integration_id": 4821,
    "label": "Моя інтеграція",
    "scopes": ["*"]
  }
}

Перевірка стану: `GET /health`¶

Єдиний ендпоінт без автентифікації — перевірка живучості для моніторингу.

{ "success": true, "data": { "service": "apiv2", "status": "ok", "ts": 1784551104 } }