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

Ежедневная выгрузка выручки в 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 нельзя.

Выгрузка заявок и пропусков#

Данные портала арендаторов: заявки и пропуска. Оба метода доступны на любом тарифе, тарифное окно периода к ним не применяется. Жёсткого лимита длины периода нет — для стабильного ответа лучше брать не больше трёх месяцев.

Заявки, действующие в день или период#

Получить все заявки, действующие в указанный день/период. Удобно использовать для формирования реестров для охраны и эксплуатации.

GET /sc/{sc_id}/portal/tickets
    ?start_active_date=2026-08-28
    &end_active_date=2026-08-28
    &per_page=100

Active-период выбирает заявки, чей интервал действия пересекается с окном. Для «кто сегодня в объекте» это правильнее, чем фильтр по дате создания: заявку могли оформить заранее.

Для каких работ оформили пропуск#

Если нужно понять, для проведения каких работ был оформлен пропуск. Стыковка — по 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[]=… → заявки по этим номерам

Связка ответов:

python

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 не из текущего ТЦ игнорируются: в ответ попадают только найденные. Подробности методов — Заявки портала и Пропуска портала.