Звіти через API
Звіти API повертають складські показники: залишки, резерви та очікувані товари. Це правильний ресурс для синхронізації кількості із сайтами, CRM, маркетплейсами та внутрішніми системами.
Повʼязані інструкції:
Endpoint-и
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/reports/remains | залишки товарів |
| GET | /v1/reports/reserves | резерви товарів |
| GET | /v1/reports/waitings | очікувані товари |
Залишки
Endpoint:
GET /v1/reports/remains
Параметри:
| Параметр | Призначення |
|---|---|
date | Дата, на яку потрібно отримати залишки. |
stock_id | Склад або магазин. |
category_id | Категорія товарів. |
contragent_id | Контрагент. |
typeprice | Тип ціни для розрахунку цінового поля звіту. |
Поля відповіді:
| Поле | Що означає |
|---|---|
stock_id | ID складу. |
stock_title | Назва складу. |
product_id | ID товару. |
product_title | Назва товару. |
product_code | Код товару. |
modification_code | Код модифікації. |
modification_id | ID модифікації. |
modification_title | Назва модифікації. |
product_sku | Артикул товару. |
price_retail | Роздрібна ціна. |
price_wholesale | Гуртова ціна. |
datevalid | Термін придатності, якщо товар ведеться за термінами. |
measure_title | Технічне поле одиниці виміру у відповіді залишків. |
price | Ціна, розрахована за параметром typeprice або обліковою ціною за замовчуванням. |
quantity | Кількість залишку. |
amount | Сума залишку. |
date важлива для складського обліку: залишок рахується за датами документів, а не тільки за поточним моментом.
Резерви
Endpoint:
GET /v1/reports/reserves
Параметри:
| Параметр | Призначення |
|---|---|
date | Дата, на яку потрібно отримати резерви. |
stock_id | Склад. |
category_id | Категорія товарів. |
product_id | Конкретний товар. |
filial_id | Філія або юридична особа. |
by_documents | Деталізація за документами. Працює, коли передано product_id. |
Поля звичайної відповіді:
| Поле | Що означає |
|---|---|
stock_id | ID складу. |
stock_title | Назва складу. |
product_id | ID товару. |
product_title | Назва товару. |
product_code | Код товару. |
modification_id | ID модифікації. |
modification_title | Назва модифікації. |
product_sku | Артикул товару. |
measure_title | Одиниця виміру. |
quantity | Кількість у резерві. |
Якщо by_documents=true і передано product_id, відповідь додатково містить:
| Поле | Що означає |
|---|---|
typedoc | Тип документа, який сформував резерв. |
document_id | ID документа резерву. |
docnum | Номер документа. |
docdate | Дата документа. |
contragent_title | Назва контрагента. |
Очікування
Endpoint:
GET /v1/reports/waitings
Параметри:
| Параметр | Призначення |
|---|---|
date | Дата, на яку потрібно отримати очікування. |
stock_id | Склад. |
category_id | Категорія товарів. |
product_id | Конкретний товар. |
filial_id | Філія або юридична особа. |
by_documents | Деталізація за документами. |
Поля відповіді:
| Поле | Що означає |
|---|---|
stock_id | ID складу, на який очікується товар. |
stock_title | Назва складу. |
product_id | ID товару. |
product_title | Назва товару. |
product_code | Код товару. |
product_sku | Артикул товару. |
measure_title | Одиниця виміру. |
modification_title | Назва модифікації. |
modification_id | ID модифікації. |
quantity | Очікувана кількість. |
price | Прихідна ціна очікуваного товару. |
amount | Сума очікування. |
currency_title | Валюта. |
Якщо by_documents=true, відповідь додатково містить:
| Поле | Що означає |
|---|---|
due_date | Термін виконання або очікувана дата. |
docnum | Номер документа. |
docdate | Дата документа. |
document_id | ID документа очікування. |
Коли використовувати звіти, а не товари
Використовуйте /v1/reports/..., якщо потрібно:
- передати залишок на сайт;
- порахувати доступну кількість;
- показати резерви;
- показати очікувані поставки;
- синхронізувати кількість по складах;
- отримати дані на конкретну дату.
Не покладайтеся на updated_from товарів для синхронізації залишків. Залишки, резерви й очікування змінюються документами, а не оновленням картки товару.
Чеклист
Перед інтеграцією зі звітами перевірте:
- які склади мають потрапляти у зовнішню систему;
- чи потрібні резерви й очікування;
- чи треба деталізувати резерви або очікування за документами;
- чи потрібно фільтрувати за категорією або товаром;
- яку дату використовувати;
- як зовнішня система обробляє модифікації;
- як часто можна оновлювати дані без перевищення лімітів.
Підсумок
Звіти API - основне джерело кількості товарів для зовнішніх систем. Товари описують каталог, а звіти показують складські показники.