Admin API: расходы

Через эти методы работает вкладка Настройки → Расходы и расширение для расходов. Ими же можно передавать в трекер расход рекламного аккаунта из своей интеграции. Авторизация описана на странице Admin API: обзор и авторизация, формат ответов и ошибок — на странице Формат запросов, ответов и ошибок.

Доступ и лицензия

Токен spend:write создаётся в панели: Настройки → Расходы, блок Подключить профиль, кнопка Создать ключ. Срок такого ключа — 90 дней. Токен full создаётся во вкладке API — см. Виды доступа.

Все четыре метода работают только на платной лицензии. На пробной они отвечают кодом 403:

{"code": "spend_paid_required", "message": "Расширение для расходов доступно после оплаты лицензии."}

При неактивной лицензии ответ — 402, см. Истёкшая лицензия.

Методы

Получить настройки и состояние дней

GET /api/v1/spend

Возвращает настройки расходов и состояние последних 60 дней, по которым приходили снимки.

Права токена: spend:write или full. Параметров и тела нет.

Ответ — код 200:

Те же данные показывает таблица на вкладке Расходы — см. Таблица дней.

Пример ответа:

{
  "settings": {"ad_key": "sub_id_4", "timezone": "Europe/Warsaw"},
  "jobs": [
    {
      "day": "2026-10-03",
      "pending": false,
      "error": "",
      "campaigns": 4,
      "unmatched_ads": 1,
      "unmatched_spend": 3.2,
      "updated_at": "2026-10-04T06:15:22.104512Z"
    }
  ]
}

Сохранить настройки расходов

PUT /api/v1/spend/settings

Задаёт поле клика с ID объявления и часовой пояс рекламного аккаунта. В панели это поля Поле с ID объявления и Timezone рекламного аккаунта.

Права токена: full.

Ответ — код 200 и сохранённые значения:

{"ad_key": "sub_id_4", "timezone": "Europe/Warsaw"}

Ошибки:

Передать дневной снимок расхода

POST /api/v1/spend/snapshots

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

Права токена: spend:write или full. Тело — один JSON-объект размером до 2 МиБ. Поля, которых нет в таблице, приводят к ошибке 422.

Как трекер обрабатывает снимок:

• Снимок заменяет прежние данные этого аккаунта за этот день, а не прибавляется к ним. Передавайте все объявления аккаунта, а не только изменившиеся.
• Из двух снимков одного аккаунта за один день остаётся тот, у которого fetched_at позже. Снимок с более ранним временем не применяется.
• Сумма переводится в USD по курсу на дату расхода. Курс закрепляется за аккаунтом и днём при первом снимке — см. Курс для расходов из расширения. Для USD курс не нужен.
• Расход объявления делится между кампаниями по кликам с его ID в поле settings.ad_key — см. Как расход попадает в отчёты.

Ответ — код 202: снимок принят, раскладка по кампаниям идёт в фоне. Результат смотрите в jobs метода GET /api/v1/spend.

Пример запроса:

curl -X POST https://panel.example.com/api/v1/spend/snapshots \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "1234567890123456",
    "day": "2026-10-03",
    "currency": "PLN",
    "timezone": "Europe/Warsaw",
    "fetched_at": "2026-10-04T06:15:00Z",
    "rows": [
      {"ad_id": "120210000000000001", "spend": 182.4},
      {"ad_id": "120210000000000002", "spend": 57.15}
    ]
  }'

Пример ответа:

{"accepted": true, "changed": true, "rows": 2}

Ошибки:

Повтор того же снимка с тем же fetched_at безопасен: трекер ответит 202 с "changed": false.

Скачать расширение

GET /api/v1/spend/extension

Отдаёт архив расширения расходов, собранный под домен панели, название и логотип этой установки. Это тот же файл, что скачивается кнопкой на вкладке Расходы — см. Расширение для расходов Facebook.

Права токена: full. Параметров и тела нет.

Ответ — код 200, тип application/zip, имя файла micator-spend.zip.

Пример запроса:

curl https://panel.example.com/api/v1/spend/extension \
  -H "Api-Key: <токен>" \
  -o micator-spend.zip

Ошибки:

Порядок загрузки из своей интеграции

1. Сохраните настройки методом PUT /api/v1/spend/settings или на вкладке Настройки → Расходы.
2. Отправляйте по одному запросу POST /api/v1/spend/snapshots на каждую пару «аккаунт — день».
3. Запросите GET /api/v1/spend и дождитесь у нужного дня "pending": false с пустым error.
4. Если unmatched_ads не ноль, проверьте, что ссылка в объявлении передаёт ID объявления в поле settings.ad_key — см. Токены источника и параметры ссылки.

Чтобы расход разложился по кликам, которые пришли после загрузки, отправьте снимок этого дня ещё раз с новым fetched_at.