# Отчёты через Management API и BI

Отчёты программы — те же, что на страницах отчётов кабинета мерчанта (ADR-0026), — Management API отдаёт в JSON. Так их
забирает BI-система (Power BI, Excel, Yandex DataLens, Looker Studio, свой скрипт) или бэк-офис мерчанта. Людям удобнее
файлы: на каждой странице отчётов в кабинете есть «Выгрузить» — Excel со всеми таблицами отчёта или CSV одной таблицы.

## Ключ

Для отчётов хватает одного скоупа `reports`: в отчётах нет персональных данных, и ключ с ним ничего не меняет.

- **Мерчант** выпускает ключ в кабинете: «Ключи мерчанта» → «Выпустить ключ», отмечает только «Отчёты». Ключ вида
  `lm_<префикс>.<секрет>` показывается один раз. Заголовок `Loyal-Merchant` ключу мерчанта не нужен.
- **Партнёр** выдаёт скоуп `reports` клиенту OAuth (его может выдать и разработчик партнёра) и в каждом запросе называет
  мерчанта заголовком `Loyal-Merchant`.

Ключ передаётся в заголовке `Authorization: Bearer <ключ>`. Держите его в хранилище секретов BI-системы, а не в тексте
отчёта или запроса, который видят другие. Выпускайте каждой BI-системе и каждому файлу отчёта свой ключ: так его можно
отозвать, не трогая остальные.

## Что можно получить

| Запрос | Что в ответе |
|---|---|
| `GET /api/management/v1/reports/programs` | Программы мерчанта, работающие и в архиве: `id`, название, часовой пояс |
| `GET /api/management/v1/programs/{program}/reports/overview` | «Сводка»: участники, чеки и выручка, покупатели, баллы по источникам, по дням |
| `GET /api/management/v1/programs/{program}/reports/liabilities` | «Обязательства»: остатки баллов на начало и конец, движение по месяцам, график сгорания, когорты, юрлица и расчёты между ними |
| `GET /api/management/v1/programs/{program}/reports/locations` | «Точки и кассы»: чеки, выручка и баллы по точкам и кассам, с названиями |
| `GET /api/management/v1/programs/{program}/reports/campaigns` | «Результаты акций»: чеки, участники, выручка, скидка и баллы каждой акции, с названием и состоянием |

Поля ответов описаны в спецификации `docs/api/management-v1.yaml` (раздел «Отчёты»).

- **Период.** Отчёты по дням принимают `from` и `to` (`Y-m-d`, оба включительно, до 92 дней), «Обязательства» — месяцы
  (`Y-m`, до 12). Без них — последние 30 дней или 12 месяцев до сегодня. Дни и месяцы — по часовому поясу программы
  (`timezone` в ответе).
- **Единицы.** Деньги — в копейках, целыми числами. Баллы — в минимальных единицах типа баллов: `point_type.precision`
  знаков после запятой, номинал балла — `value_minor` копеек.
- **Свежесть.** Собранный отчёт хранится 5 минут, `read_at` — когда его собрали. Возврат или чек, который касса прислала
  позже, меняют прошлые дни: перечитывайте последние дни периода при каждой загрузке.
- **Лимит.** Отчётов мерчанта собирается не больше 30 в минуту — для кабинета и API вместе («Обязательства» за давние
  месяцы считаются за несколько). Дальше ответ `429` с кодом `reports_throttled` и заголовком `Retry-After`: повторите
  после паузы. Отчёт, который уже собран, отдаётся сразу и в лимит не считается.
- **Чего нет.** Кассиров через API нет: касса может назвать кассира именем человека. Юрлица — только по
  идентификаторам: название и ИНН индивидуального предпринимателя — его персональные данные; их видно в кабинете и в
  выгрузке оттуда.

## Пример: curl

```bash
curl -s -H "Authorization: Bearer $LOYAL_REPORTS_KEY" \
  "https://<хост>/api/management/v1/programs/<program>/reports/overview?from=2026-10-01&to=2026-10-31"
```

## Пример: Excel и Power BI (Power Query)

Таблица по дням «Сводки» за прошлый месяц. Ключ — в параметре `ReportsKey` (Power BI: «Управление параметрами»), а не в
тексте запроса. Но и параметр Excel и Power BI хранят в самом файле открытым текстом: кто получил файл (`.xlsx`, `.pbix`),
получил и ключ. Перед тем как отправить такой файл, уберите из него ключ; если файл уже ушёл — отзовите ключ в «Ключах
мерчанта» и выпустите новый.

```
let
    LastMonth = Date.AddMonths(Date.StartOfMonth(DateTime.Date(DateTime.LocalNow())), -1),
    Report = Json.Document(Web.Contents(
        "https://<хост>/api/management/v1/programs/<program>/reports/overview",
        [
            Headers = [Authorization = "Bearer " & ReportsKey],
            Query = [
                from = Date.ToText(LastMonth, "yyyy-MM-dd"),
                to = Date.ToText(Date.EndOfMonth(LastMonth), "yyyy-MM-dd")
            ]
        ]
    )),
    Days = Table.FromRecords(Report[days]),
    Typed = Table.TransformColumnTypes(Days, {{"day", type date}, {"receipts", Int64.Type}, {"revenue", Int64.Type}}),
    Roubles = Table.AddColumn(Typed, "revenue_rub", each [revenue] / 100, type number)
in
    Roubles
```
