Сигнали попиту

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

Скоуп

Потрібен скоуп demand.read — єдиний «грошовий» скоуп v1: ресурс включає дані про виручку. Тому в інтерфейсі створення ключа його чекбокс за замовчуванням вимкнений і позначений «включає дані про виручку» — видавайте його свідомо. Без скоупа ключ отримає 403 missing_scope. Яке право потрібне творцеві ключа, щоб видати цей скоуп, — у Скоупах і правах → Таблиця скоупів.

Query-параметри

Параметр	Обов'язковий	Опис
`limit`	ні	Ціле `1..200`, за замовчуванням `100`.
`cursor`	ні	Курсор `meta.next_cursor` попередньої відповіді — для наступної сторінки.
`from`, `to`	ні	Дати `YYYY-MM-DD` у таймзоні організації, межі включно — фільтр за `date`. Передаються лише парою; максимальний діапазон — 366 днів. Без них — поточний календарний місяць.
`department_id`	ні	UUID відділу — суворе рівняння за власною колонкою сигналу. Невідомий або чужий `department_id` — не помилка, просто порожній список.

Рядки з department_id = null — сигнал по всій точці цілком — повертаються лише коли фільтр department_id не передано. Запит із будь-яким department_id віддає строго рядки цього відділу: загальноточкові сигнали в нього не потрапляють. Щоб отримати і загальні, і повідділові рядки, запитуйте без фільтра й розділяйте їх за department_id на своєму боці.

employee_id на цьому ресурсі не підтримано: сигнали попиту не прив'язані до співробітників, передача → 400 validation_error (параметр відхиляється явно, а не ігнорується мовчки — див. Конвенції → Фільтри). Передати лише from без to (або навпаки) теж не можна — 400 з підказкою pass both from and to, or neither.

Запит

Без параметрів — сигнали поточного місяця в таймзоні організації:

curl -s https://smengo.com/api/v1/demand-signals \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

За конкретний період:

curl -s "https://smengo.com/api/v1/demand-signals?from=2026-07-01&to=2026-07-31" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Відповідь

{
  "data": [
    {
      "id": "a1c3e5b7-9d2f-4a6c-8e0b-3f5d7a9c1e24",
      "department_id": null,
      "date": "2026-07-14",
      "metric": "revenue",
      "kind": "fact",
      "value": 48250.75,
      "source": "poster",
      "updated_at": "2026-07-15T02:10:05.000Z"
    },
    {
      "id": "8e0c2a4f-6b1d-4e9a-b3c5-7d9f1b3e5a70",
      "department_id": "9c1a2e34-5678-4abc-9def-0123456789ab",
      "date": "2026-07-14",
      "metric": "traffic",
      "kind": "plan",
      "value": 320,
      "source": "manual",
      "updated_at": "2026-07-10T09:41:18.000Z"
    }
  ],
  "meta": { "next_cursor": null }
}

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

Поле	Тип	Опис
`id`	`string` (uuid)	Унікальний ідентифікатор сигналу.
`department_id`	`string` (uuid) \| `null`	Відділ сигналу (див. Відділи); `null` — сигнал по всій точці цілком (див. правило фільтрації вище).
`date`	`string` (`YYYY-MM-DD`)	День сигналу, в таймзоні організації; список відсортований за цим полем (плюс `id` як тай-брейкер).
`metric`	`"revenue"` \| `"traffic"`	Метрика: виручка або трафік (кількість гостей/чеків).
`kind`	`"plan"` \| `"fact"`	План це чи факт.
`value`	`number`	Значення метрики — JSON-число, не рядок: невід'ємне, не більше 10¹². Для `revenue` може бути дробовим (`48250.75`), для `traffic` зазвичай ціле.
`source`	`"manual"` \| `"csv"` \| `"poster"`	Звідки сигнал: ручне введення, CSV-імпорт або інтеграція Poster POS.
`updated_at`	`string` (ISO 8601 UTC)	Час останньої зміни сигналу.

Сигнали не прив'язані до співробітників — у відповіді немає ні employee_id, ні вкладених даних співробітників.

Пагінація

Список відсортований за date, id. Якщо сигналів більше, ніж limit, meta.next_cursor містить курсор для наступної сторінки; передайте його в cursor наступного запиту як є:

curl -s "https://smengo.com/api/v1/demand-signals?limit=1&cursor=eyJrIjoiMjAyNi0wNy0xNCIsImlkIjoiYTFjM2U1YjctOWQyZi00YTZjLThlMGItM2Y1ZDdhOWMxZTI0In0" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

meta.next_cursor дорівнює null, коли сигналів більше немає. Загальні правила пагінації — у Конвенціях → Пагінація.

Що далі

Відділи — розшифрування department_id.
Скоупи та права — хто може видати ключу demand.read і чому він вимкнений за замовчуванням.
Конвенції — загальні правила фільтрів і дат.

Чи була стаття корисною?