Перейти к основному содержимому

Отчеты

Базовое описание продукта​

Smart Placement Reports API позволяет партнерам и порталам регулярно выгружать статистику Smart Placement в собственные BI-системы, аналитические инструменты или data warehouse.

Через API можно получать данные о рекламной активности, эффективности размещений, атрибутированных продажах и трафике плейсментов. Данные доступны в едином JSON-формате с дневной гранулярностью.

API предназначен для серверной интеграции. Партнер настраивает регулярную выгрузку со своей стороны, например ежедневный pull-сценарий по расписанию, и загружает данные в собственное хранилище без ручных экспортов и дополнительных запросов к Retail Rocket Group.

Для авторизации используется Personal Access Token. Токен должен храниться на стороне сервера партнера и не должен передаваться в клиентский браузер. Интеграция выполняется по схеме server-to-server; CORS и клиентский трекинг в этом сценарии не используются.

Кейсы использования​

  1. Сводная аналитика по рекламной активности Партнер регулярно выгружает Adverts Daily Report в собственное хранилище данных, чтобы строить дашборды по эффективности реклам, рекламодателей и плейсментов.
  2. Финансовая отчетность и attribution-анализ Партнер выгружает Attributed Orders Daily Report, чтобы связывать атрибутированные заказы с конкретными рекламами и плейсментами. Эти данные могут использоваться для финансовой отчетности, сверок и построения attribution-моделей.
  3. Анализ инвентаря и заполняемости плейсментов Партнер выгружает Placements Daily Report, чтобы анализировать спрос и матч рекламы по каждому плейсменту и группе плейсментов. Метрики requests и adRequests помогают оценивать доступный инвентарь, заполняемость и потенциальные точки оптимизации.
  4. Интеграция с собственными аналитическими процессами Партнер настраивает регулярную выгрузку отчетов в BI-систему, data warehouse или внутренние аналитические пайплайны. Это позволяет использовать данные Smart Placement вместе с другими источниками данных партнера.

Использование со сторонним SSO​

Если портал или паблишер использует сторонний SSO-провайдер, правила аутентификации определяются настройками этого провайдера. При этом контракт ответа для отчетов остается одинаковым и не зависит от способа аутентификации пользователя в портале.

Технические ограничения​

  • Date range. Дата запроса должна находиться в пределах последних 60 дней. Если дата выходит за это окно, API возвращает 400 INVALID_DATE_RANGE. Ограничение позволяет делать backfill без нагрузки на холодные данные.
  • Rate limit. Для запросов действует 10-секундное окно rate limit. При превышении API возвращает 429 RATE_LIMIT_EXCEEDED и retryAfter в секундах. Клиент должен реализовать backoff и повторять запрос после указанной паузы.
  • Granularity. Adverts Daily Report возвращает одну строку на сочетание рекламы, плейсмента, рекламодателя и даты. Attributed Orders Daily Report возвращает одну строку на товарную позицию в заказе. Placements Daily Report возвращает одну строку на сочетание плейсмента, часа и deviceType; за полный день может быть до 24 строк на плейсмент.
  • Формат ответа. Adverts Daily Report и Attributed Orders Daily Report возвращают application/json с оберткой { "value": [...] }. Placements Daily Report возвращает application/json-seq: поток JSON-объектов по строкам без обертки value. Такой ответ нужно парсить построчно.
  • Timezone. Query-параметр tz в формате IANA обязателен. От него зависит граница дня для группировки данных. Рекомендуется явно передавать часовой пояс партнера, например Europe/Moscow.
  • Денежные значения. Поля spent, purchase, postViewRevenue и postClickRevenue передаются как десятичные значения с двумя знаками после точки. Валюта соответствует валюте кабинета партнера.