Документация для интеграции

Авторизация

Передавайте API-ключ подключенного бота в заголовке Auth. Ключ находится в Telegram: Продать трафик → В ботах → Интеграция(API).

Auth: db_xxxxxxxxxxxxxxxxx

POST /api/v1/sponsors

Создаёт сессию и возвращает массив кнопок. API никогда не возвращает больше спонсоров, чем запрошено в max_sponsors. В ответе всегда есть session_id, даже если офферов временно нет.

curl -X POST https://darkboosts.com/api/v1/sponsors \
  -H "Content-Type: application/json" \
  -H "Auth: YOUR_API_KEY" \
  -d '{
    "user_id": 123456789,
    "chat_id": 123456789,
    "username": "username",
    "first_name": "Name",
    "language_code": "ru",
    "is_premium": false,
    "max_sponsors": 10
  }'

{
  "ok": true,
  "status": "ok",
  "session_id": 1042,
  "sponsors": [
    {"id":"s1", "title":"Спонсор #1", "link":"https://t.me/example"}
  ],
  "count": 1
}

POST /api/v1/check

Проверяет сессию. Если выполнена только часть списка, выполненные пункты засчитываются один раз, а в missing возвращаются только оставшиеся.

curl -X POST https://darkboosts.com/api/v1/check \
  -H "Content-Type: application/json" \
  -H "Auth: YOUR_API_KEY" \
  -d '{"user_id":123456789,"session_id":1042}'

{
  "ok": true,
  "status": "not_ok",
  "completed": 1,
  "rewarded": 1,
  "missing": [
    {"id":"s2", "title":"Спонсор #2", "link":"https://t.me/example2"}
  ],
  "blocked_offers": []
}

Железное правило: если оффер не подтверждён как выполненный, он остаётся невыполненным и не оплачивается владельцу площадки.

Проверка одного оффера

Чтобы проверить только один выданный оффер, передайте его id в поле offer_id. Остальные офферы сохранятся в активной сессии и смогут быть проверены позже.

{"user_id":123456789,"session_id":1042,"offer_id":"s2"}

15 неудачных проверок одного оффера

Если один и тот же пользователь 15 раз не подтвердил подписку на конкретный оффер, DarkBoost блокирует этот оффер только для этого пользователя. Оффер больше не будет выдаваться ему в новых и активных сессиях, но награда владельцу за него не начисляется.

{
  "ok": true,
  "status": "not_ok",
  "completed": 0,
  "rewarded": 0,
  "blocked": 1,
  "missing": [],
  "blocked_offers": [
    {"id":"s1", "title":"Спонсор #1", "link":"https://t.me/example", "blocked":true, "attempts":15}
  ]
}

В админ-панели сайта появилась вкладка Блокировки, где можно посмотреть такие офферы и вручную снять блокировку.

Опциональный пропуск офферов

Если конкретный оффер недоступен или внешний сервис временно не может его проверить, интеграция может пропустить один или несколько офферов при проверке. Пропущенный оффер удаляется из текущей сессии, не попадает в missing и не оплачивается.

curl -X POST https://darkboosts.com/api/v1/check \
  -H "Content-Type: application/json" \
  -H "Auth: YOUR_API_KEY" \
  -d '{
    "user_id": 123456789,
    "session_id": 1042,
    "skip_ids": ["s2", "https://t.me/broken_offer"]
  }'

Можно передавать skip, skip_ids, skip_offer_ids, skipped или skipped_ids. Значениями могут быть id из ответа API (s1, s2), ссылка, внешний id оффера или массив объектов с полями id/link.

Правильный flow

1. Вызовите /api/v1/sponsors и сохраните session_id.
2. Покажите кнопки из массива sponsors.
3. После нажатия «Я подписался» вызовите /api/v1/check.
4. При not_ok замените список кнопок на missing. Если missing пустой, но есть blocked_offers, не пропускайте пользователя как успешно выполнившего задание: этот оффер скрыт после 15 неудач и не оплачивается.
5. При ok пропускайте пользователя дальше.
6. Если нужно, передайте skip_ids в /api/v1/check; за пропущенные офферы награда не начисляется.
7. Не создавайте новую сессию, пока старая не проверена. После успешной проверки уважайте cooldown/reset_seconds.

Минимальный пример aiogram

async def get_sponsors(user):
    payload = {
        "user_id": user.id,
        "chat_id": user.id,
        "username": user.username,
        "first_name": user.first_name,
        "language_code": user.language_code or "ru",
        "is_premium": bool(user.is_premium),
        "max_sponsors": 10,
    }
    async with aiohttp.ClientSession() as s:
        async with s.post("https://darkboosts.com/api/v1/sponsors", json=payload, headers={"Auth": API_KEY}) as r:
            return await r.json()

async def check_sponsors(user_id, session_id, skip_ids=None):
    payload = {"user_id": user_id, "session_id": session_id}
    if skip_ids:
        payload["skip_ids"] = skip_ids
    async with aiohttp.ClientSession() as s:
        async with s.post("https://darkboosts.com/api/v1/check", json=payload, headers={"Auth": API_KEY}) as r:
            return await r.json()