English

Composite-запит та includes¶

Дві можливості дозволяють отримати рівно те, що потрібно, за мінімум запитів.

`?include=` — вбудовування пов'язаних об'єктів¶

Більшість ендпоінтів (списки та поодинокі) приймають ?include=a,b, щоб вбудувати пов'язані об'єкти, розв'язані одним батчем (без N+1). Наприклад, продаж із клієнтом:

curl "https://crm.h-profit.com/bapi-v2/sales?include=client&limit=10" \
  -H "Authorization: hp_live_ваш_ключ"

{
  "id": 4603, "amount": "…", "client_id": 105424,
  "client": { "id": 105424, "first_name": "Ярослав", "phone": "…" }
}

Невідома назва include повертає 422. Якщо зовнішній ключ null, вбудоване значення — null (для expenses — порожній масив).

Зв'язки¶

Ресурс	Значення `include`
`sales`	`client`
`orders`	`client`, `sale`
`shipments`	`supplier`, `expenses`
`expenses`	`warehouse`
`productions`	`category`
`products`	`images`

`POST /query` — кілька ресурсів одним викликом¶

Запитуйте кілька ресурсів (кожен зі своїм фільтром, пагінацією, проєкцією полів та includes) за один запит. Потрібен валідний ключ; кожен під-запит перевіряється на власний scope resource:read.

Запит:

{
  "queries": {
    "recent_sales": {
      "resource": "sales",
      "filter": { "warehouse_id": 8562 },
      "limit": 20,
      "include": ["client"],
      "fields": ["id", "amount", "sold_at", "client"]
    },
    "catalog": {
      "resource": "products",
      "filter": { "category_id": 18726 },
      "limit": 100
    }
  }
}

Відповідь — за вашими аліасами:

{
  "success": true,
  "data": {
    "recent_sales": { "data": [ /* … */ ], "meta": { "limit": 20, "offset": 0 } },
    "catalog":      { "data": [ /* … */ ], "meta": { "limit": 100, "offset": 0 } }
  },
  "meta": { "count": 2 }
}

queries також може бути масивом, де кожен елемент опційно має as (за замовчуванням — назва ресурсу):

{ "queries": [ { "resource": "warehouses", "as": "wh" },
               { "resource": "clients", "filter": { "with_debt": 1 }, "limit": 50 } ] }

Поля під-запиту¶

Поле	Значення
`resource`	обов'язкове — один із ресурсів
`filter`	об'єкт тих самих фільтрів, що приймає `GET` ресурсу
`limit` / `offset`	пагінація (limit не більше 500)
`include`	масив назв зв'язків (зв'язки)
`fields`	білий список верхньорівневих ключів (`id` зберігається завжди)

Ізоляція помилок¶

Один поганий під-запит не ламає весь батч — його слот містить error замість data:

{
  "success": true,
  "data": {
    "ok_one":  { "data": [ /* … */ ], "meta": { "limit": 100, "offset": 0 } },
    "bad_one": { "error": { "code": "forbidden", "message": "insufficient scope",
                            "details": { "required": ["expenses:read"] } } }
  }
}

Ліміти¶

Не більше 10 під-запитів на запит.
limit кожного під-запиту обмежений 500.

Ресурси для запиту: sales, orders, shipments, expenses, clients, categories, products, warehouses, suppliers, product_sync, productions.