Звіти через API

Звіти через API повертають складські й продажні показники: залишки, резерви, очікувані товари, рейтинг продажів, журнал продажів, аналіз продажів і звіт за касирами.

Частина звітів повертає результат одразу. Великі продажні звіти запускаються як задача: API повертає task_id, після чого інтеграція перевіряє статус задачі й забирає результат, коли він готовий.

попередження

Не викликайте endpoint-и звітів частіше ніж 1 раз на годину. Це обмеження стосується всіх звітів у цьому розділі: залишків, резервів, очікувань і продажних звітів.

Звіти не призначені для постійного опитування на кшталт “перевірити залишок зараз” або “перерахувати прибуток кожні кілька хвилин”. Якщо інтеграція регулярно перевищує цей ліміт, доступ до API може бути заблокований. Зберігайте результат на своїй стороні й оновлюйте його не частіше дозволеного інтервалу.

Endpoint-и

Метод	Endpoint	Призначення
GET	/v1/reports/remains	залишки товарів
GET	/v1/reports/reserves	резерви товарів
GET	/v1/reports/waitings	очікувані товари
POST	/v1/reports/sales_rating	запустити рейтинг продажів
POST	/v1/reports/sales_registry	запустити журнал продажів
POST	/v1/reports/sales_analytic	запустити аналіз продажів
POST	/v1/reports/cashiers	запустити звіт за касирами
GET	/v1/report_tasks/:id/status	перевірити статус задачі звіту
POST	/v1/report_tasks/:id/cancel	скасувати задачу звіту

Залишки

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 документа очікування.

Асинхронні звіти

Продажні звіти можуть обробляти великий обсяг даних, тому вони запускаються як задача.

Типовий порядок:

1. Виконати POST /v1/reports/... з параметрами звіту.
2. Отримати task_id і status.
3. Періодично запитувати GET /v1/report_tasks/:id/status.
4. Коли задача завершиться, забрати result.
5. Якщо задача більше не потрібна, скасувати її через POST /v1/report_tasks/:id/cancel.

Відповідь запуску звіту:

Поле	Що означає
task_id	ID задачі звіту.
status	Поточний статус задачі.

попередження

Не запускайте важкі звіти занадто часто. Для інтеграцій краще зберігати результат на своїй стороні й повторювати запит тільки тоді, коли справді потрібне оновлення.

Рейтинг продажів

Endpoint:

POST /v1/reports/sales_rating

Параметри:

Параметр	Призначення
date_start	Початок періоду.
date_end	Кінець періоду.
stock_id	Склад або магазин.
group_id	Категорія товарів.
sale_channel_id	Канал продажів.
producer_id	Виробник.
sorting	Варіант сортування звіту.
kits_by_components	Розглядати комплекти за компонентами.

Доступні значення sorting:

Значення	Що означає
amount_sale	За сумою продажів.
quantity_sale	За кількістю.

Журнал продажів

Endpoint:

POST /v1/reports/sales_registry

Параметри:

Параметр	Призначення
date_start	Початок періоду.
date_end	Кінець періоду.
stock_id	Склад або магазин.
group_id	Категорія товарів.
producer_id	Виробник.
contragent_id	Контрагент.
sale_documents	Типи продажних документів для звіту.
cashier_id	Касир.
executor_id	Виконавець.
sale_channel_id	Канал продажів.
currency_id	Валюта звіту.

Доступні значення sale_documents:

Значення	Що означає
1	Продажі через основну програму.
2	Продажі через Skynum.Каса.

Аналіз продажів

Endpoint:

POST /v1/reports/sales_analytic

Параметри:

Параметр	Призначення
date_start	Початок періоду.
date_end	Кінець періоду.
group_by	Ознака групування звіту.
stock_id	Склад або магазин.
group_product_id	Категорія товарів.
sale_channel_id	Канал продажів.
producer_id	Виробник.
supplier_id	Постачальник.
client_id	Покупець.
group_client_id	Група покупців.
currency_id	Валюта звіту.
multicurrency_costing_method	Метод розрахунку собівартості для мультивалютного сценарію.

Доступні значення group_by:

Значення	Що означає
by_days	Групування за днями.
by_groups	Групування за категоріями товарів.
by_products	Групування за товарами.
by_stocks	Групування за складами.
by_clients	Групування за покупцями.
by_suppliers	Групування за постачальниками.

Доступні значення multicurrency_costing_method:

Значення	Що означає
document	За курсом на дату документа.
period_end	За курсом на кінець періоду.
present	За поточним курсом.
inside_document	За курсом з документа.

Звіт за касирами

Endpoint:

POST /v1/reports/cashiers

Параметри:

Параметр	Призначення
date_start	Початок періоду.
date_end	Кінець періоду.
computer_id	Робоче місце Skynum.Каса.
user_id	Користувач або касир.
by_bankbox	Деталізація за банківськими рахунками.
consolidated	Консолідований варіант звіту.

Статус задачі звіту

Endpoint:

GET /v1/report_tasks/:id/status

Поля відповіді:

Поле	Що означає
id	ID задачі звіту.
status	Статус задачі.
error	Текст помилки, якщо задача завершилася з помилкою.
result	Результат звіту, коли задача завершена й результат доступний.
created_at	Дата створення задачі.
updated_at	Дата оновлення задачі.

result повертається як масив рядків звіту. Набір полів залежить від конкретного звіту та його параметрів.

Скасування задачі звіту

Endpoint:

POST /v1/report_tasks/:id/cancel

Відповідь:

Поле	Що означає
id	ID задачі звіту.
status	Статус після скасування.

Перевірка доступу до ресурсів

Для звітів, де передаються ID філії, складу, робочого місця, каси або банківського рахунку, API перевіряє доступ користувача до цих ресурсів.

Поля, для яких перевіряється доступ:

Поле	Що означає
filial_id	Філія або юридична особа.
stock_id	Склад або магазин.
computer_id	Робоче місце Skynum.Каса.
cashbox_id	Каса.
bankbox_id	Банківський рахунок.

Якщо користувач інтеграції не має доступу до ресурсу, звіт не буде сформований для цього ресурсу.

Коли використовувати звіти, а не товари

Використовуйте /v1/reports/..., якщо потрібно отримати звітні дані, а не інкрементальну синхронізацію товарів:

• отримати залишки на конкретну дату;
• порахувати доступну кількість за фільтрами звіту;
• показати резерви за фільтрами звіту;
• показати очікувані поставки за фільтрами звіту;
• синхронізувати кількість по складах;
• отримати дані на конкретну дату;
• отримати агреговану аналітику продажів;
• отримати звіти, які залежать від активованих документів і фільтрів.

інформація

Якщо інтеграції потрібно регулярно забирати зміни товарів разом із залишками, резервами й очікуваннями, використовуйте Товари через API з фільтрами updated_from, updated_to і параметром extended=true.

Чеклист

Перед інтеграцією зі звітами перевірте:

• які склади мають потрапляти у зовнішню систему;
• чи потрібні резерви й очікування;
• чи треба деталізувати резерви або очікування за документами;
• які продажні звіти потрібні інтеграції;
• чи має API-користувач доступ до потрібних складів, філій, кас і рахунків;
• чи потрібно фільтрувати за категорією, товаром, каналом продажів або контрагентом;
• яку дату або період використовувати;
• як зовнішня система обробляє модифікації;
• як часто можна оновлювати дані без перевищення лімітів;
• як інтеграція працює з асинхронними задачами.

Повʼязані матеріали

• Залишки товарів;
• Резерви товарів;
• Очікувані товари;
• Аналіз продажів;
• Журнал продажів;
• Рейтинг продажів;
• Звіт за касирами;
• Склади через API;
• Товари через API.

Підсумок

Звіти API — джерело агрегованої аналітики, даних на конкретну дату й звітних вибірок для зовнішніх систем. Товари описують каталог і можуть повертати базові складські показники через extended=true, документи створюють облікові рухи, а звіти показують результат цих рухів у залишках, резервах, очікуваннях і продажах.