API для владельцев ботов

Обновлено 20.10.2026

Свой бот можно монетизировать через Pulsar двумя форматами: ОП при /start и задания. Pulsar подбирает спонсоров, проверяет подписки и платит за подписчиков, а твой бот показывает каналы и отправляет один-два запроса. Код программист пишет один раз.

Два формата

Подключение

1. В боте @PulsarAdsBot открой «Продать» и подключи своего бота токеном от @BotFather.
2. Выбери формат «ОП при /start» или «Задания», задай число спонсоров (кнопка «Спонсоров», от 1 до 6), цену и ГЕО, включи продажу.
3. В кабинете формата нажми «Как подключить API» (у заданий «Инструкция») и открой раздел «Для программиста». На странице «Ключи (передай программисту)» лежат platform_id, api_key и базовый адрес.

Ключ и авторизация

• platform_id — публичный ID площадки вида plt_…, подходит и числовой id.
• В GET-запросах ключ передаётся заголовком X-Api-Key.
• В POST-запросах ключ передаётся полем api_key в JSON-теле.
• В адрес запроса ключ не клади: строка ?api_key= оседает в логах прокси и в истории браузера. Сервер пока принимает её ради старых интеграций, но этот способ устарел.
• Mini App Pulsar работает без ключа, по подписи Telegram в init_data.
• Если ключ утёк, нажми «Перевыпустить ключ» в разделе «Для программиста». Старый ключ сразу перестанет работать.

Эндпоинты

Пути /op/tasks/verify-webapp и /op/tasks/complete устарели: это старые имена check-webapp и tasks/check.

ОП при /start

1. Покажи спонсоров на /start

Как только человек нажал /start, запроси спонсоров для него. В ответе только каналы, на которые он ещё не подписан, со ссылками трекинга Pulsar, клики по ним видны в кабинете.

curl "https://pulsarx.sale/api/v1/op/sponsors?platform_id=plt_...&telegram_user_id=123456789&language_code=ru" \
      -H "X-Api-Key: $PULSAR_API_KEY"

language_code бери из from_user.language_code. По нему подбираются спонсоры с ГЕО: без него часть спонсоров не покажется, и подписка на них не оплатится. Показывай спонсоров сразу: Pulsar платит за подписку, сделанную в течение 2 часов после первого ответа «не подписан».

Тот же запрос без telegram_user_id вернёт каталог всей сетки (mode: catalog), он нужен только для обзора. Человеку показывай режим op: у каждого свой набор спонсоров.

2. Проверь подписки по кнопке

Человек подписался и нажал «Проверить подписки» в твоём боте. Отправь запрос с его Telegram ID:

curl -X POST "https://pulsarx.sale/api/v1/op/check-subscriptions" \
      -H "Content-Type: application/json" \
      -d '{
        "platform_id": "plt_...",
        "api_key": "КЛЮЧ_ИЗ_БОТА",
        "telegram_user_id": 123456789,
        "language_code": "ru"
      }'

Ответ, сокращённо:

{
      "ok": true,
      "platform_id": "plt_...",
      "telegram_user_id": 123456789,
      "all_subscribed": false,
      "no_sponsors": false,
      "subscribed_count": 1,
      "pending_count": 1,
      "total": 2,
      "sponsors": [
        {
          "id": 512,
          "title": "Канал спонсора",
          "username": "sponsor_channel",
          "type": "channel",
          "url": "https://...",
          "subscribed": false
        }
      ],
      "subscribed_sponsors": [
        {"id": 377, "title": "Другой спонсор", "username": "other_sponsor", "type": "channel"}
      ]
    }

• all_subscribed: true: пускай человека в бота.
• all_subscribed: false: покажи каналы из sponsors, там только оставшиеся.
• no_sponsors: true приходит вместе с all_subscribed: true: подписываться не на что, пускай человека.
• attributed показывает, сколько подписок взято на оплату. Поле появляется при all_subscribed: true.

id спонсора бывает числом или строкой. Кроме полей выше, в ответе есть служебные: platform_numeric_id, bot_username, limit, у спонсора target_url и track_token.

3. /start без токена

Если Pulsar не может проверить /start по токену твоего бота, зафиксируй его сам запросом POST /op/start с тем же телом, что у check-subscriptions. GET /op/check с platform_id и telegram_user_id отвечает, запускал ли человек бота: поле started, способ проверки в поле method.

Задания

1. Возьми постоянную ссылку Mini App. Она есть в боте, в разделе «Твоя ссылка», и в ответе GET /op/tasks/link (поля open_link и mini_app_url). Ссылка одна на весь бот, одинаковая для всех пользователей и не меняется.
2. Поставь её на кнопку в боте, например «Задания» или «Получить бонус». Mini App показывает человеку только каналы, на которые он не подписан, и по кнопке «Проверить» сохраняет результат.
3. Твой бот читает сохранённый результат и выдаёт свой бонус. Логику решаешь ты: например, 1 канал = 10 монет, 2 канала = 25.

curl "https://pulsarx.sale/api/v1/op/tasks/status?platform_id=plt_...&telegram_user_id=123456789" \
      -H "X-Api-Key: $PULSAR_API_KEY"

В ответе has_progress, subscribed_count, subscribed_sponsors и saved_at. Если человек отписался, после следующей проверки subscribed_count уменьшится.

Проверить задания со своего сервера, без Mini App, можно запросом POST /op/tasks/check: тело как у check-subscriptions плюс поле task_id (по умолчанию subscribe). Запросы /op/tasks/context и /op/tasks/check-webapp делает сам Mini App Pulsar, передавая init_data из Telegram.WebApp.initData. Повторять их в боте не нужно.

Когда платят

• При успешной проверке Pulsar фиксирует подписку. Следующие 12 часов человек должен оставаться подписанным.
• Остался: продавцу оплата, у покупателя списание. Отписался раньше: оплата отменяется.
• ОП оплачивается только при all_subscribed: true. Задания оплачиваются при subscribed_count от 1, каждый канал отдельно.
• Платят только за людей, которые запускали твоего бота: Pulsar сверяет это по токену, который ты дал при подключении. Для человека, которого твой бот не знает, API вернёт пустую сетку.
• Подписка, которая была до первой проверки, не оплачивается.
• Если ты перевыпустил токен бота, пришли новый в «Мои площадки», иначе Pulsar нечем проверять подписки и спонсоров не будет.

В кабинете у каждой подписки видно состояние: 12 ч на проверке, подтверждено, заработано. Счётчики интеграции отдаёт GET /op/stats: op_starts (зафиксированные /start), task_users (люди с заданиями) и tasks_completed (проверки заданий).

Ответы и ошибки

Перед запуском проверь

• Лот в продаже. На паузе API отвечает no_sponsors: true.
• При no_sponsors, ошибке или таймауте API бот пускает человека и не держит его у входа.
• Бот передаёт language_code, иначе спонсоры с ГЕО не покажутся.
• Спонсоры показываются сразу на /start.

Пустой список спонсоров значит, что в сети сейчас нет подходящих закупок. Подожди или измени цену и ГЕО в кабинете.