← Назад
referenceПочатківець⏱️ 3 хв читання

Фільтрація за періодом (датами)

Як фільтрувати документи та звіти за періодом через параметр period — готові пресети, довільний діапазон дат, як дізнатись поточний список ключів і типові помилки.

#period#filters#reference#documents

Параметр period

Фільтр за датами в API реалізований через один рядковий query-параметр — period. Він доступний у методів, що повертають документи чи звіти, наприклад:

Дати в 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/"
}

Пошук

Пошук ендпоінтів, гайдів, туторіалів, реліз-ноутів по всьому порталу