Public Beta · v0.1

API партнёрам

HTTP API для реселлеров: автоматизируйте создание заказов, отслеживайте баланс и статусы. Base URL: https://fathersmm.ru/api/v1

Quickstart

Три шага, чтобы создать первый заказ через API:

Получи API-ключ в ЛК → Партнёр API. Для тестов используй sandbox-ключ pk_test_sandbox_* — у него безлимитный баланс.
Отправь POST-запрос на /orders с Bearer-токеном:
В ответе получишь orderId — по нему дальше отслеживай статус.

cURL

curl -X POST https://fathersmm.ru/api/v1/orders \
  -H "Authorization: Bearer pk_test_sandbox_eE9rTy5UvB6xCs1" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "telegram",
    "service": "tg-subs-standard",
    "quantity": 500,
    "url": "https://t.me/your_channel"
  }'

Authentication

Все запросы требуют заголовок Authorization: Bearer <api_key>. Без заголовка → 401 Unauthorized. Невалидный ключ → 401.

Ключи начинаются с префикса pk_demo_ (production-демо) или pk_test_ (sandbox с безлимитным балансом). Никогда не коммитьте ключи в git и не публикуйте в клиентском коде.

POST /api/v1/orders

Создать заказ. Списывает сумму с баланса партнёра.

Body (JSON):

platform — string. Одна из платформ из /services.
service — string. ID услуги (например tg-subs-standard).
quantity — integer > 0.
url — string. Ссылка на профиль/пост.
options — object (опционально). Платформо-специфичные параметры.

Ответ (201 Created):

JSON

{
  "orderId": "ord_1714834200000_a1b2c3d4",
  "status": "pending",
  "amount": 25.0,
  "createdAt": "2026-05-07T10:30:00.000Z"
}

Beta: цена считается по упрощённой формуле quantity × 0.05 ₽/ед. Sprint 25 свяжет с реальным каталогом.

cURL

curl -X POST https://fathersmm.ru/api/v1/orders \
  -H "Authorization: Bearer pk_test_sandbox_eE9rTy5UvB6xCs1" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "telegram",
    "service": "tg-subs-standard",
    "quantity": 500,
    "url": "https://t.me/your_channel"
  }'

GET /api/v1/orders/:id

Получить статус и прогресс заказа. Партнёр видит только свои заказы — на чужой orderId ответ 404.

Ответ (200 OK):

JSON

{
  "orderId": "ord_1714834200000_a1b2c3d4",
  "status": "in_progress",
  "progress": 42,
  "amount": 25.0,
  "platform": "telegram",
  "service": "tg-subs-standard",
  "quantity": 500,
  "url": "https://t.me/your_channel",
  "createdAt": "2026-05-07T10:30:00.000Z",
  "updatedAt": "2026-05-07T10:35:12.000Z"
}

Возможные значения status: pending, in_progress, completed, cancelled.

cURL

curl https://fathersmm.ru/api/v1/orders/ord_1234567890_abc \
  -H "Authorization: Bearer pk_test_sandbox_eE9rTy5UvB6xCs1"

GET /api/v1/balance

Получить текущий баланс партнёра, общую сумму расходов и количество заказов.

Ответ (200 OK):

JSON

{
  "balance": 4975.0,
  "currency": "RUB",
  "totalSpent": 25.0,
  "ordersCount": 1,
  "unlimited": false,
  "partnerName": "Alpha Reseller"
}

cURL

curl https://fathersmm.ru/api/v1/balance \
  -H "Authorization: Bearer pk_test_sandbox_eE9rTy5UvB6xCs1"

GET /api/v1/services

Каталог доступных услуг. Используй поле service при создании заказа.

Ответ (200 OK):

JSON

{
  "services": [
    {
      "platform": "telegram",
      "category": "subscribers",
      "service": "tg-subs-standard",
      "title": "Telegram — подписчики (Стандарт)",
      "tiers": [
        { "tier": "standard", "pricePerUnit": 0.9, "minQty": 100, "maxQty": 100000 },
        { "tier": "fast", "pricePerUnit": 1.1, "minQty": 100, "maxQty": 100000 }
      ]
    }
  ],
  "total": 12,
  "pricingNote": "Beta: фактическая стоимость = quantity * 0.05 RUB."
}

cURL

curl https://fathersmm.ru/api/v1/services \
  -H "Authorization: Bearer pk_test_sandbox_eE9rTy5UvB6xCs1"

Errors

Ошибки возвращаются как JSON { "error": "...", "details"?: ... } с соответствующим HTTP-статусом.

Code	Name	Description
401	Unauthorized	Отсутствует или невалидный API-ключ.
402	Payment Required	Недостаточно средств на балансе партнёра.
403	Forbidden	Ключ заблокирован или нет прав на операцию.
404	Not Found	Ресурс не найден или принадлежит другому партнёру.
422	Validation Error	Ошибка валидации тела запроса (см. поле details).
429	Rate Limit	60 запросов в минуту на ключ исчерпаны. Жди Retry-After секунд.
500	Server Error	Внутренняя ошибка. Повтори через минуту, если повторится — пиши в support.

Rate limits

Лимит — 60 запросов в минуту на ключ. Окно — sliding window 60 секунд.

Каждый ответ содержит заголовки:

X-RateLimit-Limit — общий лимит (60).
X-RateLimit-Remaining — сколько запросов осталось.
X-RateLimit-Reset — ISO-таймстамп когда счётчик обнулится.
Retry-After — секунды до следующей попытки (только при 429).

Для нагрузочного тестирования используйте sandbox-ключ — у него тот же rate-limit, но безлимитный баланс.

Changelog

v0.1 (2026-05-07) — public beta. POST /orders, GET /orders/:id, GET /balance, GET /services. Лимит 60 req/min. In-memory state — данные сбрасываются при перезапуске сервера. Production-стор появится в Sprint 25.

Status

Real-time uptime и инциденты — stats.uptimerobot.com

TODO (backlog): подключить собственную status-page с историей инцидентов и метриками p50/p95 латентности на endpoint.

Готов начать?

Получить API-ключ