Интеграция, которую не нужно разгадывать

Самая короткая схема

Какие данные пользователя передавать

Чем точнее профиль, тем корректнее upstream-таргетинг сторонних сервисов.

Получить список спонсоров

DarkBoost собирает общий пул из всех включённых для бота источников, дедуплицирует его, фильтрует недоступные офферы и только потом ограничивает результат вашим max_sponsors. Максимум — 10.

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

import aiohttp

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

const data = await fetch('https://darkboosts.com/api/v1/sponsors', {
  method: 'POST',
  headers: {'Content-Type':'application/json', Auth: process.env.DARKBOOST_KEY},
  body: JSON.stringify({user_id:user.id, chat_id:user.id, max_sponsors:10})
}).then(r => r.json());

Нормальный ответ

{
  "ok": true,
  "status": "ok",
  "session_id": 1042,
  "sponsors": [
    {"id":"s1","title":"Спонсор #1","link":"https://t.me/DarkBoostsBot?startapp=offer_TOKEN&mode=compact"},
    {"id":"s2","title":"Спонсор #2","link":"https://t.me/DarkBoostsBot?startapp=offer_TOKEN2&mode=compact"}
  ],
  "count": 2
}

Проверить весь обязательный список

Передайте того же пользователя и session_id. Уже подтверждённые офферы фиксируются идемпотентно. В missing остаются только невыполненные.

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

Проверить конкретный оффер

Полезно, если у каждого спонсора отдельная кнопка «Проверить». Можно передать offer_id, offer_link, а также массивы offer_ids / offer_links.

{
  "user_id": 123456789,
  "session_id": 1042,
  "offer_ids": ["s1", "s2"]
}

Неизвестный оффер вернёт HTTP 404 до начислений. Повторная проверка уже завершённой сессии возвращает сохранённый результат с cached:true.

Получить одно текущее задание

Tasks mode всегда выдаёт ровно одно задание. Если текущее ещё активно, повторный запрос вернёт его же с тем же session_id.

curl -X POST https://darkboosts.com/api/v1/tasks/next \
  -H 'Auth: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"user_id":123456789,"chat_id":123456789,"username":"example"}'

{
  "ok": true,
  "status": "ok",
  "mode": "tasks",
  "session_id": 2088,
  "task": {"id":"s1","title":"Спонсор #1","link":"https://t.me/DarkBoostsBot?startapp=offer_TOKEN&mode=compact"},
  "count": 1,
  "no_timeout": true,
  "cooldown": false
}

Проверить или пропустить задание

{"user_id":123456789,"session_id":2088}

{"user_id":123456789,"session_id":2088}

После успешного check/skip можно сразу запросить /api/v1/tasks/next. DarkBoost не вводит cooldown между заданиями.

Первичный /start gate

Интеграции ничего менять не нужно. Если пользователь ещё не запускал @DarkBoostsBot, ссылка спонсора сначала откроет основной бот. После /start пользователь продолжит в тот же offer по тому же session/tracking token. Для уже активировавших DarkBoost ссылка сразу ведёт в Mini App.

Почему нельзя заменять link из ответа

Webhooks без сюрпризов

Включите webhook у подключённого бота и укажите HTTPS URL + secret. DarkBoost отправляет события subscription и unsubscription. Получатель должен вернуть любой HTTP 2xx.

Подпись

X-DarkBoost-Event: subscription
X-DarkBoost-Event-Id: 64-char-event-id
X-DarkBoost-Signature: sha256=HEX_HMAC

subscription payload

{
  "event": "subscription",
  "event_id": "…",
  "occurred_at": 1791121403,
  "occurred_at_iso": "2026-10-04T13:43:23Z",
  "bot_id": 87,
  "user_id": 5091745714,
  "session_id": 509680,
  "service": "flyer",
  "offer_id": "212b133c99",
  "offer_link": "https://t.me/+…",
  "reward_rub": 0.0,
  "reward_status": "pending",
  "provider_status": "waiting"
}

unsubscription payload

{
  "event": "unsubscription",
  "event_id": "…",
  "occurred_at_iso": "2026-10-08T09:10:00Z",
  "bot_id": 87,
  "user_id": 5091745714,
  "service": "darkboost",
  "offer_link": "https://t.me/example",
  "penalty_rub": 0.61,
  "reason": "retention_unsubscribe"
}

Готовый обработчик

import hashlib, hmac, json
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = "your-secret"

@app.post("/darkboost/webhook")
async def darkboost_webhook(request: Request):
    raw = await request.body()
    got = request.headers.get("X-DarkBoost-Signature", "")
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(), raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(got, expected):
        raise HTTPException(403, "bad signature")

    event = json.loads(raw)
    event_id = event["event_id"]
    # В БД сделайте UNIQUE(event_id), чтобы retry не обработался дважды.
    await process_once(event_id, event)
    return {"ok": True}

import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.use(express.raw({type:'application/json'}));

app.post('/darkboost/webhook', async (req, res) => {
  const got = req.get('X-DarkBoost-Signature') || '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.DARKBOOST_WEBHOOK_SECRET)
    .update(req.body).digest('hex');
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.sendStatus(403);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  await processOnce(event.event_id, event);
  res.json({ok:true});
});

Retry policy

Самопроверка webhook

Не нужно вручную собирать тестовый HMAC. Поставьте безопасное событие test в ту же production-очередь, а затем посмотрите результат доставки.

curl -X POST https://darkboosts.com/api/v1/webhook/test \
  -H 'Auth: YOUR_API_KEY'

{
  "ok": true,
  "status": "queued",
  "delivery_id": 1201,
  "event_id": "…"
}

curl https://darkboosts.com/api/v1/webhook/status/1201 \
  -H 'Auth: YOUR_API_KEY'

Test-event не означает подписку и не влияет на баланс. Если ваш обработчик принимает только два известных типа событий, добавьте ветку event === "test" и просто верните 200.

Sandbox — тестируйте интеграцию без денег и реальных подписок

Создайте sandbox key в Control Plane у нужного подключённого бота. Ключ начинается с dbx_test_, хранится на сервере только как SHA-256 и показывается один раз.

curl -X POST https://darkboosts.com/api/v1/sandbox/sponsors \
  -H 'Auth: dbx_test_...' -H 'Content-Type: application/json' \
  -d '{"user_id":123456789,"max_sponsors":3,"scenario":"pending_reward"}'

Для проверки HMAC-доставки вызовите POST /api/v1/sandbox/webhook с sandbox key. Событие проходит через тот же durable webhook pipeline, но имеет "sandbox": true.

Официальная Python-библиотека

pip install https://darkboosts.com/static/sdk/darkboost_sdk-1.0.0-py3-none-any.whl

from darkboost_sdk import AsyncDarkBoostClient

async with AsyncDarkBoostClient("YOUR_API_KEY") as db:
    session = await db.sponsors(user_id=123456789, max_sponsors=10)
    result = await db.check(
        user_id=123456789,
        session_id=session["session_id"],
    )

В SDK есть sync/async клиенты, mandatory/tasks/check-offer, webhook test/status, отдельные sandbox-клиенты и проверка HMAC по исходным байтам body.

from darkboost_sdk import verify_webhook
verify_webhook(WEBHOOK_SECRET, raw_body, request.headers["X-DarkBoost-Signature"])

Control Plane — почему именно эта интеграция не работает

Открыть Control Plane →

Для каждого подключённого бота доступны Provider Health, end-to-end funnel, webhook p50/p95, delivery history + Retry, sandbox key, anti-fraud summary и marketplace ROI-рекомендации.

HTTP код и status — это не одно и то же

Сначала проверяйте HTTP-код. Затем JSON-поле status. Например, HTTP 200 + status=not_ok — это нормальный бизнес-ответ, а не ошибка API.

Если что-то не работает

Checklist перед запуском

1. API key и webhook secret хранятся только на backend.
2. Пользователь получает только link из ответа DarkBoost.
3. session_id сохраняется до завершения проверки.
4. HTTP-код и JSON status обрабатываются отдельно.
5. busy повторяется по retry_after_ms, а не считается ошибкой.
6. Webhook HMAC проверяется до изменения баланса/состояния.
7. Webhook обработчик имеет UNIQUE по event_id.
8. Ваш endpoint быстро возвращает 2xx; тяжёлую работу делайте через собственную очередь.