21.08.2024 08:40

WidgetData

Модели, описывающие отображаемые данные виджетов

Примечание: У каждого типа виджета своя уникальная модель отображаемых данных.

Содержание


1. Личные задачи (Только текущие). Мои цели.

Название Тип данных Описание
id Int64 ID цели
name String Наименование цели
value Decimal Значение цели
progress Decimal Прогресс цели
percent Int64 Прогресс цели в процентах


2. Глобальные задачи (Только текущие). Глобальные цели.

Название Тип данных Описание
id Int64 ID цели
name String Наименование цели
value Decimal Значение цели
progress Decimal Прогресс цели
percent Int64 Прогресс цели в процентах


3. Состояние счетов, на дату формирования. Счета.

Название Тип данных Описание
name String Наименование счёта
currency_name String Наименование валюты счёта
value Decimal Баланс счёта


4. Заказы (Розн. заказы), на дату формирования. Розничные заказы.

Название Тип данных Описание
total Int64 Общее количество
new Int64 Количествоновых заказов (в статусе New)


5. Касса (массив касс, доступных пользователю). Кассы.

Название Тип данных Описание
id Int64 ID кассы
name String Наименование кассы


6. Статистика продаж, розница (за текущий день). Статистика продаж.

Название Тип данных Описание
total_amount Decimal Общая сумма
average_receipt_amount Decimal Средняя сумма чека
receipt_count Int64 Количество чеков
sales_amount Decimal Сумма продаж
sales_count Int64 Количство чеков продаж
sales_pos_count Int64 Количство позиций в чеках продаж
sales_unit_count Int64 Количство единиц продаж
refund_amount Decimal Сумма возвратов
refund_count Int64 Количство чеков возвратов
refund_pos_count Int64 Количство позиций в чеках возвратов
refund_unit_count Int64 Количство единиц возвратов
gross_profit Decimal Валовая прибыль (total_amount - last_purchase_cost_amount)
sales_amount_per_square_meter Decimal Сумма продаж на м2 (total_amount / SUM(area))
operating_cash_avg_down_time Decimal Среднее время работы кассы в секундах (SUM(sls_date - sls_start_date))
operating_cash_avg_work_time Decimal Среднее время работы кассы в секундах (SUM(sls_end_date - sls_start_date))
markup_avg_in_percent Decimal Средняя наценка в процентах (total_amount - last_purchase_cost_amount) / last_purchase_cost_amount * 100


7. Статистика продаж по типам оплат, розница (за текущий день).

Название Тип данных Описание
id Int64 ID типа оплаты
name String Тип оплаты
amount Decimal Сумма


8. Динамика продаж (оборот по сумме) за неделю, розница (за 7 дней, включая текущий). Продажи за неделю.

Название Тип данных Описание
date String Дата и время в формате: ГГГГ-ММ-ДДTЧЧ:ММ:СС
amount Decimal Сумма


9. Топ-10 продаваемые товары (по количеству), розница  (за 7 дней, включая текущий). Топ - 10, по количеству продаж.

Название Тип данных Описание
id Int64 ID номенклатуры
code Int64 Код номенклатуры
name String Наименование номенклатуры
quantity Decimal Количество


10. Топ-10 продаваемые товары (по сумме), розница (за 7 дней, включая текущий). Топ - 10, по сумме продаж.

Название Тип данных Описание
id Int64 ID номенклатуры
code Int64 Код номенклатуры
name String Наименование номенклатуры
amount Decimal Сумма


11. Розн. покупатели, предстоящиее дни рождения (за 5 дней заранее). Ближайшие дни рождения.

Название Тип данных Описание
id Int64 ID покупателя
name String Имя покупателя
phone String Контактный номер покупателя
date String День рождения покупателя в формате: ГГГГ-ММ-ДДTЧЧ:ММ:СС


12. Топ-10, Предпочитаемые покупки по картам покупателя (количество и сумма по настройкам системы).

Название Тип данных Описание
item_id Int64 ID номенклатуры
item_code Int64 Код номенклатуры
item_name String Наименование номенклатуры
value Decimal Значение
customer_id Int64 ID покупателя
customer_name String Имя покупателя
customer_phone String Телефон покупателя


13. Топ-10 Долги по котнрагентам (в базовой валюте) (Сортировка по сумме), на текущий день. Контрагенты, задолженности.

Название Тип данных Описание
id Int64 ID контрагента
name String Имя контрагента
debt_amount Decimal Сумма долга
last_payment String Дата последней оплаты в формате: ГГГГ-ММ-ДДTЧЧ:ММ:СС


14. График распределения возрастов покупателей (за 7 дней, включая текущий). Покупатели по возрастам.

Название Тип данных Описание
age String Возраст покупателя
count Int64 Количество чеков продаж


15. График распределения покупателей по полу (за 7 дней, включая текущий). Покупатели по полу.

Название Тип данных Описание
sex Enum Пол покупателя: <none | 1> (не указан), <male | 2> (мужской), <female | 3> (женский)
count Int64 Количество чеков продаж


16. Информация по тарифу

Название Тип данных Описание
tariff_id Int32 ID тарифа
name String Наименование тарифа
name_var String Ключ локализации наименования тарифа
paid_until String Оплачено до (в формате: "ДД.ММ.ГГГГ ЧЧ:ММ:СС")
data_display_period Int32 Период отображения данных, в месяцах
pay_period Int32 Периодичность оплаты (в месяцах)
pay_discount_percent Int32 Скидка на оплату в процентах
price Decimal Стоимость тарифа за один месяц без учёта скидки
services_price Decimal Стоимость всех тарифных услуг за один месяц без учёта скидки
service_data Array of Widget16Data Данные по услугам
Widget16Data

Модель, описывающая данные по услугам виджета "Информация по тарифам".

Название Тип данных Описание
name_var String Ключ локализации услуги
quantity Int32 Количество
in_use Int32 Используется


17. Топ-10 долгов розничных покупателей

Массив:

Название Тип данных Описание
id Int64 ID покупателя
name String Имя покупателя
debt_amount Decimal Сумма долга
last_payment String Дата последней оплаты в формате: ГГГГ-ММ-ДДTЧЧ:ММ:СС


18. Активность продаж

Представляет из себя *массив** с данными о количестве чеков, разделённых по часам и по дням недели. Количество дней в массиве: 168 (2 года).

Название Тип данных Описание
day Enum День недели: Monday - Понедельник, Tuesday - Вторник, Wednesday - Среда, Thursday - Четверг, Friday - Пятница, Saturday - Суббота, Sunday - Воскресенье
data Array of Data Массив с количеством чеков по часам
Data
Название Тип данных Описание
hour Int32 Час (0 - 23)
value Int32 Количество чеков


19. Виджет интеграции

Для виджета типа Integration (19) данные запрашиваются у подключённой интеграции через контрактный action DashboardWidgetDataGet. Интеграция должна быть активной и поддерживать обработчик Widget.

Если интеграция не ответила, вернула ошибку или ответ не прошёл проверку контракта, WidgetData/Get возвращает пустой объект {}. Такой пустой результат кешируется на 1 минуту.

Валидный ответ интеграции также кешируется на 1 минуту. Кеш зависит от ID виджета, подключённой интеграции, предприятия, склада и периода дашборда.

Запрос к интеграции

API вызывает интеграцию через gateway с envelope RegosIntegrationAdpatersRequest:

{
    "action": "DashboardWidgetDataGet",
    "event_id": "a5f22e72-7d0f-44f3-bf06-6da9f4db6d8d",
    "occurred_at": "2026-05-20T09:20:00Z",
    "connected_integration_id": "58b28744515e4e4c987078544d8eaacc",
    "data": {
        "widget_id": 123,
        "dashboard_id": 3,
        "firm_id": 0,
        "stock_id": 0,
        "start_date": "2026-04-21T00:00:00",
        "end_date": "2026-05-20T23:59:59",
        "language_code": "RUS"
    }
}
DashboardWidgetDataGetRequest
Название Тип данных Описание
widget_id Int64 ID виджета
dashboard_id Int64 ID дашборда
firm_id Int64 ID предприятия, 0 - предприятие не указано
stock_id Int64 ID склада, 0 - склад не указан
start_date DateTime Дата и время начала периода в формате YYYY-MM-DDTHH:mm:ss
end_date DateTime Дата и время окончания периода в формате YYYY-MM-DDTHH:mm:ss
language_code String Код языка пользователя

start_date и end_date рассчитываются API из периода дашборда. Для None используется период по умолчанию: последние 7 дней, включая текущий день. end_date передаётся как конец дня 23:59:59.

Ответ интеграции

Интеграция должна вернуть стандартный envelope ApiResult, где result содержит один из поддерживаемых типов графика:

{
    "ok": true,
    "result": {
        "chartType": "bar",
        "categories": ["Пн", "Вт", "Ср"],
        "series": [
            {
                "name": "Заявки",
                "data": [12, 18, 9]
            }
        ]
    }
}

Если интеграция возвращает ok: false, API считает это ошибкой интеграции и отдаёт в WidgetData/Get пустой объект {}.

Поддерживаемые chartType
chartType Обязательные поля Описание
pie slices Круговая диаграмма
radialBar bars Радиальные индикаторы
bar categories, series Столбчатая диаграмма
line series Линейный график
heatmap series Heatmap
Общие ограничения
Правило Описание
Number Числовые значения должны быть конечными: не NaN, не Infinity
id Необязательный String до 100 символов или Number
label String до 200 символов
color Необязательный String до 50 символов
name String до 200 символов
nameKey Необязательный String до 200 символов
meta Необязательный объект, максимум 50 ключей
meta key Ключ до 100 символов
meta value Только String, Number, Boolean или Null; строка до 500 символов
DashboardChartPoint
Название Тип данных Описание
id String | Number Необязательный ID точки
label String Подпись
value Number Значение
color String Необязательный цвет
meta Object Необязательные метаданные; значения только String, Number, Boolean или Null
DashboardRadialBarPoint

Расширяет DashboardChartPoint.

Название Тип данных Описание
percent Number Процент выполнения, обязательное значение от 0 до 100
progress Number Необязательное текущее значение
total Number Необязательное итоговое значение
DashboardAxisChartPoint
Название Тип данных Описание
x String | Number Значение по оси X
y Number Значение по оси Y
label String Необязательная подпись
meta Object Необязательные метаданные; значения только String, Number, Boolean или Null
DashboardChartSeries
Название Тип данных Описание
id String | Number Необязательный ID серии
name String Наименование серии
nameKey String Необязательный ключ локализации
data Array Данные серии
PieWidgetChartData
Название Тип данных Описание
chartType String Всегда pie
slices Array of DashboardChartPoint Сектора диаграммы, максимум 1000 элементов 
{
    "ok": true,
    "result": {
        "chartType": "pie",
        "slices": [
            {
                "id": "telegram",
                "label": "Telegram",
                "value": 120,
                "color": "#229ED9",
                "meta": {
                    "channel": "telegram"
                }
            },
            {
                "id": "web",
                "label": "Web",
                "value": 80,
                "color": "#34A853"
            }
        ]
    }
}
RadialBarWidgetChartData
Название Тип данных Описание
chartType String Всегда radialBar
bars Array of DashboardRadialBarPoint Индикаторы, максимум 1000 элементов 
{
    "ok": true,
    "result": {
        "chartType": "radialBar",
        "bars": [
            {
                "label": "План продаж",
                "value": 7500000,
                "percent": 75,
                "progress": 7500000,
                "total": 10000000
            }
        ]
    }
}
BarWidgetChartData
Название Тип данных Описание
chartType String Всегда bar
categories Array of String Категории, максимум 1000 элементов
series Array of DashboardChartSeries<Number> Серии, максимум 50 элементов. Количество значений в data каждой серии должно совпадать с количеством categories 
{
    "ok": true,
    "result": {
        "chartType": "bar",
        "categories": ["Пн", "Вт", "Ср"],
        "series": [
            {
                "id": "new",
                "name": "Новые заявки",
                "data": [12, 18, 9]
            },
            {
                "id": "closed",
                "name": "Закрытые заявки",
                "data": [4, 7, 5]
            }
        ]
    }
}
LineWidgetChartData
Название Тип данных Описание
chartType String Всегда line
series Array of DashboardChartSeries<DashboardAxisChartPoint> Серии, максимум 50 элементов. Общее количество точек во всех сериях - максимум 5000 
{
    "ok": true,
    "result": {
        "chartType": "line",
        "series": [
            {
                "name": "Продажи",
                "data": [
                    { "x": "2026-05-18", "y": 1200000 },
                    { "x": "2026-05-19", "y": 1450000 },
                    { "x": "2026-05-20", "y": 980000 }
                ]
            }
        ]
    }
}
HeatmapWidgetChartData
Название Тип данных Описание
chartType String Всегда heatmap
series Array of DashboardChartSeries<DashboardAxisChartPoint> Серии, максимум 50 элементов. Общее количество точек во всех сериях - максимум 5000

Для heatmap обычно series.name используется как строка/группа, x - колонка или период, y - интенсивность/значение.

{
    "ok": true,
    "result": {
        "chartType": "heatmap",
        "series": [
            {
                "name": "Понедельник",
                "data": [
                    { "x": "09:00", "y": 4 },
                    { "x": "10:00", "y": 9 }
                ]
            },
            {
                "name": "Вторник",
                "data": [
                    { "x": "09:00", "y": 3 },
                    { "x": "10:00", "y": 11 }
                ]
            }
        ]
    }
}