API

Покупка звёзд Telegram, Premium, Steam и игровых пакетов из вашего кода — сайта, бота или приложения.

Как начать

1. Напишите владельцу боту /api и создайте ключ.
2. Скопируйте ключ — он показывается один раз.
3. Пополните баланс — с него списываются покупки.
4. Передавайте ключ в каждом запросе: Authorization: Bearer ВАШ_КЛЮЧ

Точки

Создать заказ

curl -X POST https://vipstars.duckdns.org/api/v1/order/create \\
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \\
  -H "Content-Type: application/json" \\
  -H "Idempotency-Key: my-order-1001" \\
  -d '{"product_id":"stars","quantity":100,"customer":"@durov"}'

<?php
$ch = curl_init('https://vipstars.duckdns.org/api/v1/order/create');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('SHOP_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: my-order-1001',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'product_id' => 'stars',
        'quantity'   => 100,
        'customer'   => '@durov',
    ]),
]);
$answer = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($answer['success'])) {
    throw new RuntimeException($answer['error']['message'] ?? 'unknown');
}
echo $answer['order_id'];   // ORD-000123

import os, requests

answer = requests.post(
    "https://vipstars.duckdns.org/api/v1/order/create",
    headers={
        "Authorization": f"Bearer {os.environ['SHOP_API_KEY']}",
        "Idempotency-Key": "my-order-1001",
    },
    json={"product_id": "stars", "quantity": 100, "customer": "@durov"},
    timeout=30,
).json()

if not answer["success"]:
    raise RuntimeError(answer["error"]["message"])
print(answer["order_id"])   # ORD-000123

const answer = await fetch("https://vipstars.duckdns.org/api/v1/order/create", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SHOP_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "my-order-1001",
  },
  body: JSON.stringify({
    product_id: "stars",
    quantity: 100,
    customer: "@durov",
  }),
}).then((r) => r.json());

if (!answer.success) throw new Error(answer.error.message);
console.log(answer.order_id);   // ORD-000123

Ответ

{
  "success": true,
  "order_id": "ORD-000123",
  "status": "processing",
  "product_id": "stars",
  "quantity": 100,
  "amount": 1931,
  "amount_text": "19.31",
  "currency": "TJS",
  "customer": "@durov",
  "transaction_id": "TX-9F2A71B4C8D0",
  "created_at": "2026-09-15T10:04:11+00:00"
}

Повторный запрос

Передайте Idempotency-Key (заголовком или полем idempotency_key). Если тот же запрос уйдёт дважды — из-за обрыва связи или повтора очереди, — второй раз деньги не спишутся: вернётся тот же заказ.

Статус заказа

curl "https://vipstars.duckdns.org/api/v1/order/status?order_id=ORD-000123" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"

{
  "success": true,
  "order_id": "ORD-000123",
  "status": "completed",
  "result": "@durov",
  "amount": 1931,
  "amount_text": "19.31",
  "currency": "TJS"
}

Вебхук

Укажите свой адрес в боте (/api → Вебхук) — и мы сами сообщим, когда статус заказа изменится. Опрашивать /order/status в цикле тогда не нужно.

POST ваш-адрес
X-Signature: 3b099d0edd…
X-Signature-Algorithm: hmac-sha256

{
  "event": "order.completed",
  "order_id": "ORD-000123",
  "status": "completed",
  "product_id": "stars",
  "quantity": 100,
  "amount": 1931,
  "customer": "@durov",
  "result": "@durov"
}

Проверьте подпись

Подпись — HMAC-SHA256 от сырого тела запроса на вашем секрете whsec_…. Без проверки любой, кто узнает ваш адрес, сможет прислать «заказ выполнен».

# Python — проверка подписи вебхука
import hmac, hashlib

def genuine(body: bytes, header: str, secret: str) -> bool:
    mine = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mine, header)   # сравнение постоянное по времени

Ошибки

{
  "success": false,
  "error": {
    "code": "insufficient_funds",
    "message": "Недостаточно средств.",
    "required": 1931,
    "balance": 400,
    "currency": "TJS"
  }
}

Лимиты

• 60 запросов в минуту на ключ. Сверх — 429 и заголовок Retry-After.
• Короткий всплеск проходит целиком: лимит считается «дырявым ведром», а не жёстко по минутам.
• Десять неверных ключей подряд с одного адреса закрывают его на 5 минут.
• В каждом ответе есть X-Request-Id. Если что-то не работает — пришлите этот номер владельцу, по нему запрос найдётся в журнале.