Параметр period
Фільтр за датами в API реалізований через один рядковий query-параметр — period. Він доступний у методів, що повертають документи чи звіти, наприклад:
GET /documents/listGET /documents/groupedGET /documents/sales_with_productsGET /reports/reconciliationGET /reports/payment_reportGET /reports/brands_turnoverGET /reports/carrier_turnover
Дати в API — завжди у форматі ISO 8601 (YYYY-MM-DDTHH:mm:ssZ).
period приймає значення одним з двох способів: зарезервованим ключем (нижче) або довільним діапазоном дат (розділ Конкретні дати).
Зарезервовані швидкі фільтри
| Ключ | Період |
|---|---|
today | Сьогодні |
yesterday | Вчора |
last_7_days | Останні 7 днів |
last_30_days | Останні 30 днів |
week | Цей тиждень |
last_week | Минулий тиждень |
month | Цей місяць |
last_month | Минулий місяць |
quarter | Цей квартал |
year | Цей рік |
GET /documents/sales_with_products?period=year
Цей список не варто хардкодити на своїй стороні — точні ключі, назви та межі кожного пресета завжди можна отримати через /documents/filters/dates (нижче).
Конкретні дати
Замість ключа-пресета period приймає довільний діапазон — два значення дати/часу в фігурних дужках, через кому: {start,end}.
GET /documents/list?period={2018-02-23T00:00:01Z,2018-02-28T23:59:59Z}
Формат — той самий ISO 8601, що й скрізь в API (рік-місяць-деньTгодини:хвилини:секундиZ).
Час можна опустити — тоді в перше значення підставляється початок дня (00:00:00), а в друге — кінець дня (23:59:59):
GET /documents/list?period={2018-02-01,2018-01-31}
Одну чи обидві дати також можна опустити повністю — на місце порожнього значення підставляється початок або кінець поточного дня відповідно (а не дня з іншої половини діапазону):
GET /documents/list?period={2018-02-01,}
У цьому прикладі кінцем діапазону буде кінець сьогоднішнього дня, а не 2018-02-01.
Примітка: фігурні дужки
{}у значенні параметра — частина синтаксисуperiod, а не URL-екранування; при формуванні запиту не забудьте закодувати їх (%7B/%7D) разом з рештою спецсимволів рядка запиту.
Актуальний список пресетів
Набір ключів вище стабільний, але кожен з них резолвиться сервером у конкретні start/end дати — і ці межі відрізняються залежно від того, для якого функціоналу фільтрується період. Щоб дізнатись поточні межі (а не покладатись на дату, підраховану на своїй стороні), використовуйте:
GET /documents/filters/dates?dates_as=obj&target=documents
dates_as—obj(об’єкт з ключами періодів, за замовчуванням) абоarr(масив).target— для якого функціоналу рахувати межі:documents,reconciliation,payment_report,brands_turnover,carrier_turnover,returns_report,reclamations_reportабоsearch_stat. Необов’язковий параметр — без нього повертається той самий набір ключів із загальними межами.
Приклад відповіді (без target):
{
"dates": {
"today": {
"name": "Сьогодні",
"start": "2026-08-20T00:00:00Z",
"end": "2026-08-20T23:59:59Z",
"order": 0
},
"yesterday": {
"name": "Вчора",
"start": "2026-08-19T00:00:00Z",
"end": "2026-08-19T23:59:59Z",
"order": 1
},
"last_7_days": {
"name": "Останні 7 днів",
"start": "2026-08-14T00:00:00Z",
"end": "2026-08-20T23:59:59Z",
"order": 2
},
"last_30_days": {
"name": "Останні 30 днів",
"start": "2026-07-22T00:00:00Z",
"end": "2026-08-20T23:59:59Z",
"order": 3
},
"week": {
"name": "Цей тиждень",
"start": "2026-08-17T00:00:00Z",
"end": "2026-08-23T23:59:59Z",
"order": 4
},
"last_week": {
"name": "Минулий тиждень",
"start": "2026-08-10T00:00:00Z",
"end": "2026-08-16T23:59:59Z",
"order": 5
},
"month": {
"name": "Цей місяць",
"start": "2026-08-01T00:00:00Z",
"end": "2026-08-31T23:59:59Z",
"order": 6
},
"last_month": {
"name": "Минулий місяць",
"start": "2026-07-01T00:00:00Z",
"end": "2026-07-31T23:59:59Z",
"order": 7
},
"quarter": {
"name": "Цей квартал",
"start": "2026-07-01T00:00:00Z",
"end": "2026-09-30T23:59:59Z",
"order": 8
},
"year": {
"name": "Цей рік",
"start": "2026-01-01T00:00:00Z",
"end": "2026-12-31T23:59:59Z",
"order": 9
}
},
"min_available_date": null
}
order— порядок для відображення пресетів у власному UI (наприклад, у списку швидких фільтрів); на логіку фільтрації не впливає.min_available_date— найдавніша дата, доступна для обраногоtarget(якщо для нього діє обмеження глибини історії).
Помилки
Невідомий або невалідний period дає 422:
{
"message": "Не валідний datetime",
"documentation_url": "https://developer.bm.parts/api/v2/"
}
Якщо запитаний період виходить за межі, доступні для цього ендпоінту (дивись min_available_date вище):
{
"message": "Діапазон дат виходить за межі допустимого.",
"documentation_url": "https://developer.bm.parts/api/v2/"
}