Сигналы спроса

Возвращает сигналы спроса — плановые и фактические значения выручки и трафика по дням, с пагинацией и фильтрами по периоду и отделу.

Скоуп

Требуется скоуп 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 и почему он выключен по умолчанию.
Конвенции — общие правила фильтров и дат.

Была ли статья полезна?