Donatix API

Быстрый старт

1. Узнайте баланс:

curl -s https://donatix.duckdns.org/api/v1/balance -H "X-API-Key: $KEY"

{"ok": true, "balance": "100.0000", "currency": "USD"}

2. Найдите товар:

curl -s "https://donatix.duckdns.org/api/v1/products?kind=telegram_stars" -H "X-API-Key: $KEY"

{"ok": true, "items": [{
  "product_id": "tg-stars", "kind": "telegram_stars", "name": "Telegram Stars",
  "unit": "star", "price_usd": "0.016605", "min_quantity": 50, "max_quantity": 10000,
  "fields": [{"key": "telegram_username", "label": "Telegram @username", "type": "text"}]
}]}

3. Сделайте заказ. Всегда передавайте свой уникальный Idempotency-Key — тогда повтор запроса при обрыве связи не спишет деньги второй раз:

curl -s -X POST https://donatix.duckdns.org/api/v1/orders \
  -H "X-API-Key: $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "tg-stars", "quantity": 100, "fields": {"telegram_username": "@player"}}'

{"ok": true, "order": {
  "order_id": "dx-1042", "status": "processing", "kind": "telegram_stars",
  "product_name": "Telegram Stars 100", "quantity": 100,
  "total_usd": "1.6605", "delivery": null, "error": null, ...}}

4. Узнайте результат: GET /orders/dx-1042 (или дождитесь webhook). Статусы:

Методы

Полная схема: Swagger · OpenAPI JSON

Поля заказа

У каждого товара есть список fields — что нужно передать в заказе:

• Telegram Stars и Premium — telegram_username (например @player).
• Пополнения игр — обычно player_id, иногда ещё сервер или зона: смотрите fields товара.
• Подарочные карты — полей нет, укажите quantity.
• Steam-гифт (steam-gift) — app_id, sub_id и region из /steam-gifts/games/{appid}, плюс invite_url получателя (https://s.team/p/…).
• Пополнение Steam (steam-topup) — steam_login (логин, не никнейм), currency (USD, RUB, KZT, UAH) и amount в этой валюте. Курсы — в поле rates товара. Логин проверяется до списания.

Для Telegram Stars quantity — количество звёзд, цена указана за одну звезду.

Ошибки

{"ok": false, "error": "Недостаточно средств: нужно $1.6605, на балансе $0.5000.", "code": "insufficient_balance"}

Лимиты: 60 заказов в минуту, 120 запросов каталога и статусов в минуту на аккаунт.

Webhook

Укажите адрес в панели → API. Когда заказ выполнится или отменится, мы пришлём POST:

POST https://your-site.com/donatix-hook
X-Donatix-Timestamp: 1767225600
X-Donatix-Signature: 5d41402abc4b2a76b9719d911017c592...

{"event": "order.updated", "order": {"order_id": "dx-1042", "status": "completed", ...}}

Проверьте подпись: HMAC-SHA256 от строки timestamp + "." + тело вашим секретом из панели. Ответьте кодом 2xx — иначе повторим до 5 раз.

import hmac, hashlib

def valid(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256)
    return hmac.compare_digest(mac.hexdigest(), signature)

Пример: Python

import uuid, requests

API = "https://donatix.duckdns.org/api/v1"
H = {"X-API-Key": "dx_live_..."}

def buy_stars(username: str, amount: int) -> dict:
    r = requests.post(f"{API}/orders", headers={**H, "Idempotency-Key": str(uuid.uuid4())},
                      json={"product_id": "tg-stars", "quantity": amount,
                            "fields": {"telegram_username": username}}, timeout=30)
    data = r.json()
    if not data["ok"]:
        raise RuntimeError(data["error"])
    return data["order"]

Пример: Node.js

const res = await fetch("https://donatix.duckdns.org/api/v1/orders", {
  method: "POST",
  headers: { "X-API-Key": process.env.DONATIX_KEY, "Idempotency-Key": crypto.randomUUID(),
             "Content-Type": "application/json" },
  body: JSON.stringify({ product_id: "tg-stars", quantity: 100,
                         fields: { telegram_username: "@player" } }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.error);