API рекламы и примеры
Раздел относится к новой реализации в dev. Полные схемы и требования авторизации описаны в HTTP API и публикуемой OpenAPI-спецификации.
Публичный POST /api/advertising/capture принимает code, пять разрешённых UTM-полей
в объекте utm и необязательный event_id. Идентификатор пользователя определяется
подтверждённой сессией. Нельзя передать его в теле. Ответ содержит только доступный
публичный контекст ссылки и предложения. Cookie визита живёт 30 дней.
Административные операции находятся в /api/admin/ads: список с page, page_size,
search, source, status; карточка /{id}/detail; ссылки, версии предложений,
расходы, архив и импорт. Период задаётся start включительно, end исключительно,
с обязательным часовым поясом. period_mode=events выбирает события, cohort —
привлечение. /{id}/export?kind=contacts|purchases|report|matches выгружает CSV.
Денежные minor units передаются строками, например "123456789" для 0.123456789 TON.
Для импорта есть отдельные preview, confirm, revert и candidates. Preview принимает
JSON с csv, mapping, account, timezone, granularity, currency, delimiter,
либо тело text/csv с остальными параметрами в query. Доступ требует роли администратора.
Лимиты: 1 MiB, 5000 строк. На предпросмотре показаны первые 20 нормализованных строк;
подтверждение применяет весь проверенный batch. Повторное подтверждение идемпотентно.
Ниже синтетический пример, а не объявленный формат экспорта Telegram Ads:
Сопоставьте start→start, end→end, advertisement→ad, impressions→views,
clicks→clicks, starts→starts, cost→cost, currency→currency. Для интервала
и накопительного итога окончание обязательно. Накопительный итог представляет один
полный интервал; пересекающиеся итоги не складываются. Исправление ровно того же
интервала требует явного разрешения замены. Дневной и минутный экспорт одного периода
нельзя одновременно включить в сумму. Переходы летнего времени проверяются явно.
В событийном режиме строка представляет один запуск, а не счётчик запусков. Кандидаты по времени требуют выбранного бота и окна; даже единственное совпадение не подтверждает личность и не выдаёт права. При наличии нескольких внешних или локальных событий показываются конкурирующие кандидаты. Детали доступны в описании импорта.