Типовые сценарии

Ежедневная выгрузка выручки в BI#

Классика: ночью забрать вчерашний день по всем точкам всех доступных центров.

1. POST /auth/token                       → токен на час
2. GET  /shopping_centers                 → sc_id, кэшировать на сутки
3. GET  /sc/{sc_id}/shops?per_page=500    → shop_id, кэшировать на сутки
4. GET  /sc/{sc_id}/reports/shops/{shop_id}/by_days
        ?start_date=вчера&end_date=вчера  → строка на точку

Что учесть:

«Вчера» считается в таймзоне ТЦ, она приходит в time_zone каждого центра. Для дальневосточного центра московская полночь наступает, когда там уже день.
На Basic вчерашний день и есть самая свежая доступная дата, то есть ровно этот случай.
Справочники в шагах 2–3 меняются редко: их стоит кэшировать, иначе большая часть лимита уйдёт на них.

Если точек много, стоит забирать период, а не день: один запрос с 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 отдаёт состояние, а не оценку.

Посещаемость и конверсия#

Конверсия = чеки ÷ посетители. Данные лежат в разных методах.

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 нельзя.