Ежедневная выгрузка выручки в BI#
Классика: ночью забрать вчерашний день по всем точкам всех доступных центров.
1. POST /auth/token → токен на час
2. GET /shopping_centers → sc_id, кэшировать на сутки
3. GET /sc/{sc_id}/reports/shops/by_period
?start_date=вчера&end_date=вчера
&per_page=500 → строка на точкуПродажи по всем точкам отдают весь центр одним обходом: в каждой строке уже есть точка и арендатор, отдельный запрос справочника точек не нужен.
Что учесть:
- «Вчера» считается в таймзоне ТЦ, она приходит в
time_zoneкаждого центра. Для дальневосточного центра московская полночь наступает, когда там уже день. - На Basic вчерашний день и есть самая свежая доступная дата, то есть ровно этот случай.
- Список центров в шаге 2 меняется редко: его стоит кэшировать.
- Точки без данных за день в ответ не попадают. Если витрине нужна строка на каждую точку, полный список берётся из справочника точек.
Если нужны строки по каждому дню за длинный период, подходят продажи по дням отдельной точки: один запрос с start_date за неделю назад вернёт семь строк вместо семи запросов. Данные за прошедшие дни не меняются, но пересчёт товарооборота задним числом возможен — раз в неделю имеет смысл перезабрать закрытый период.
Сверка товарооборота для расчёта аренды#
Аренда часто считается как процент от товарооборота, а товарооборот это не выручка: из него по правилам центра могут вычитаться возвраты, НДС, авансы.
1. GET /sc/{sc_id}/shops/{shop_id}/turnover_config → правила расчёта
2. GET /sc/{sc_id}/reports/shops/{shop_id}/by_months
?start_date=2026-01-01&end_date=2026-06-30 → turnover по месяцамПоле turnover уже посчитано по этим правилам, пересчитывать самостоятельно из
income_sum не нужно. turnover_config полезен, чтобы объяснить
арендатору, почему цифра отличается от его кассовой.
Поле source в настройках показывает, откуда взялись правила: своя настройка точки
(shop), общая настройка центра (shopping_center) или значения по умолчанию (default).
Мониторинг касс#
Задача в том, чтобы заметить остановку кассы раньше арендатора.
1. GET /sc/{sc_id}/shops?per_page=500 → точки
2. GET /sc/{sc_id}/shops/{shop_id}/kkts → состояние касс точкиНа что смотреть в ответе:
| Поле | Сигнал |
|---|---|
connection_status | active — данные идут; in_progress — подключение не завершено |
last_document_datetime | Давно не было чеков при работающем магазине |
last_open_shift_datetime | Смена открыта, а чеков нет |
fn_expiration_datetime | Скоро кончится фискальный накопитель |
Пороги «сколько молчания считать проблемой» интеграция задаёт сама: у островка в будний день и у якорного арендатора в воскресенье они разные. API отдаёт состояние, а не оценку.
На PRO у каждой кассы есть дневные суммы: продажи кассы по дням. По ним видно, какая из касс точки перестала пробивать чеки, когда в итогах точки это ещё незаметно.
Посещаемость и конверсия#
Конверсия = чеки ÷ посетители. Данные лежат в разных методах.
1. GET /sc/{sc_id}/traffic_areas → зоны, id числом
2. GET /sc/{sc_id}/attendance
?start_date=…&end_date=…&granularity=day → посетители ТЦ
3. GET /sc/{sc_id}/reports/shops/{shop_id}/by_days → чеки точкиЧто учесть:
idзоны приходит целым числом, в отличие от остальных идентификаторов API.- Пустой
dataпри200это законный ответ: центр или точка не покрыты зоной подсчёта. Не ошибка, и отtraffic_unavailableотличается намеренно. - Посещаемость по зоне или отдельной точке доступна только на PRO. На Basic остаётся посещаемость центра целиком.
visitors_outможет быть нулём, если данные вводятся вручную.
Публикация акций в календарь ТЦ#
Рассказать центру о своей акции.
POST /sc/{sc_id}/events
{ "name": "Чёрная пятница", "description": "Скидки", "event_type": "marketing",
"start_date": "2026-11-27", "end_date": "2026-11-30",
"color": "#FF8800", "shop_ids": ["..."] }Повторная отправка того же события (совпали название, тип и обе даты) вернёт 409
already_exists_in_sc и не изменит существующее. Если календарь синхронизируется
целиком, 409 стоит трактовать как «уже создано» и идти дальше; менять существующее
событие через API нельзя.
Выгрузка заявок и пропусков#
Данные портала арендаторов: заявки и пропуска. Оба метода доступны на любом тарифе, тарифное окно периода к ним не применяется. Жёсткого лимита длины периода нет — для стабильного ответа лучше брать не больше трёх месяцев.
Заявки, действующие в день или период#
Получить все заявки, действующие в указанный день/период. Удобно использовать для формирования реестров для охраны и эксплуатации.
GET /sc/{sc_id}/portal/tickets
?start_active_date=2026-08-28
&end_active_date=2026-08-28
&per_page=100Active-период выбирает заявки, чей интервал действия пересекается с окном. Для «кто сегодня в объекте» это правильнее, чем фильтр по дате создания: заявку могли оформить заранее.
Для каких работ оформили пропуск#
Если нужно понять, для проведения каких работ был оформлен пропуск. Стыковка —
по ticket_uid.
1. GET /sc/{sc_id}/portal/passes
?start_active_date=…&end_active_date=… → пропуска с ticket_uid
2. GET /sc/{sc_id}/portal/tickets
?ticket_uids[]=Z-MRM-12345&ticket_uids[]=… → заявки по этим номерамСвязка ответов:
passes = list(api.portal_passes(sc_id, start_active=day, end_active=day))
uids = [p["ticket_uid"] for p in passes if p.get("ticket_uid")]
tickets = {t["ticket_uid"]: t for t in api.portal_tickets(sc_id, ticket_uids=uids)}
for pass_row in passes:
ticket = tickets.get(pass_row.get("ticket_uid"))
work = ticket["title"] if ticket else None
# pass_row["id"] → work / ticket["ticket_type"] / ticket["text"]В ticket будут title, ticket_type, text и остальные поля заявки — отдельного
запроса за деталями нет.
Пропуска по конкретным заявкам#
Если нужно посмотреть список пропусков, привязанных к конкретным заявкам.
GET /sc/{sc_id}/portal/passes
?ticket_uids[]=Z-MRM-12345
&ticket_uids[]=Z-MRM-12346До 500 номеров за запрос. UID не из текущего ТЦ игнорируются: в ответ попадают только найденные. Подробности методов — Заявки портала и Пропуска портала.