Donatix API

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

1Баланс

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

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

2Товар

curl -s "https://donatix.tj/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.tj/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.

Методы

kind: telegram_stars telegram_premium steam_topup steam_gift topup gift_card game_key

ID товаров

Каждый товар и каждый пакет имеет свой product_id — его вы передаёте в POST /orders. По виду ID сразу понятно, что это за товар:

Примеры topup-… выше — условные. У каждой игры и каждого пакета (100 алмазов, 310 алмазов, недельный ваучер…) свой ID; настоящие берите из GET /products. ID не меняется, пока пакет есть в продаже, — его можно сохранить у себя и не запрашивать каталог перед каждым заказом.

1Найти игру

curl -s "https://donatix.tj/api/v1/categories" -H "X-API-Key: $KEY"

В ответе у каждой игры есть category_id — по нему удобно брать только её пакеты.

2Получить пакеты и их ID

curl -s "https://donatix.tj/api/v1/products?kind=topup&q=ff" -H "X-API-Key: $KEY"

Картинки: у каждого товара и каждой игры есть поле image_url — полная ссылка на картинку на donatix.tj. Если картинки ещё нет, поле равно null.

За один запрос отдаётся не больше limit товаров: по умолчанию 100, максимум 500. Если пакетов больше, листайте через offset: ?limit=500&offset=0, потом offset=500 и так, пока items не станет пустым. Так вы получите все товары, а не только первую сотню.

for off in 0 500 1000 1500 2000; do
  curl -s "https://donatix.tj/api/v1/products?kind=topup&limit=500&offset=$off" -H "X-API-Key: $KEY"
done

{"ok": true, "items": [{
  "product_id": "topup-3f9a1c2b7d",
  "kind": "topup", "category_id": "free_fire", "category_name": "FF",
  "region": "CIS", "region_title": "СНГ",
  "name": "100 Diamonds", "title": "100 алмазов", "emoji": "💎",
  "price_usd": "0.9900",
  "fields": [{"key": "player_id", "label": "ID игрока", "type": "text"}]
}]}

Смотрите на region: у одной игры бывают пакеты для разных регионов (например, FF СНГ и Индонезия) — у них разные ID, и пакет другого региона на аккаунт не зачислится.

3Заказать пакет по его ID

curl -s -X POST https://donatix.tj/api/v1/orders \
  -H "X-API-Key: $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "topup-3f9a1c2b7d", "fields": {"player_id": "1234567890"}}'

Поля заказа

Что передать в fields, указано в самом товаре.

Проверка аккаунта

Для многих игр можно проверить ID до заказа и показать покупателю ник. Заказ на несуществующий аккаунт не создаётся, деньги не списываются.

curl -s -X POST https://donatix.tj/api/v1/accounts/check \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"product_id": "topup-a1b2c3d4e5", "fields": {"player_id": "5123456789"}}'

{"ok": true, "supported": true, "valid": true, "player_name": "Player_6789", "region": "GLOBAL"}

Пополнение баланса

Деньги за заказы списываются с вашего баланса в Donatix. Пополнить его можно в кабинете или через API:

1Заявка

curl -X POST https://donatix.tj/api/v1/payments -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"method": "dc", "amount_tjs": "200"}'

В ответе — реквизиты (номер карты/телефона) и точная сумма к переводу.

2Перевод и чек

Переведите ровно эту сумму на указанные реквизиты и пришлите чек: POST /payments/{id}/receipt (multipart, поле file). Статус — GET /payments/{id}.

«Душанбе Сити»: приложение → «Переводы» → «По номеру карты» → вставьте номер карты из ответа.

Боты для гильдии (Glory клана FF)

Группа ботов заходит в игру за клан и набирает очки славы (glory). На один клан — одна работающая группа. Не запустилось — деньги возвращаются сами. После запуска деньги не возвращаются, можно только остановить.

curl https://donatix.tj/api/v1/glory/regions -H "X-API-Key: $KEY"

{"ok": true, "items": [{"id": "bd", "name": "Bangladesh", "code": "BD", "premium": false, "price_usd": "1.8349", "price_tjs": "20.00"}]}

curl -X POST https://donatix.tj/api/v1/glory/orders -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"region": "bd", "clan_id": "3012345678"}'

{"ok": true, "order": {"id": "gl-15", "clan_id": "3012345678", "status": "running", "glory": 48210, "farmed": 1350,
  "clan": {"name": "TJ KINGS", "level": 6, "members": 47, "capacity": 55}, "uptime": "1h12m", "bots": 4, "price_usd": "1.8349"}}

status: running работает · stopped закончила · failed не запустилась (деньги вернулись). Ошибки: invalid_clan_id invalid_region clan_busy (для клана уже работает группа) insufficient_balance launch_failed. Те же адреса есть в /api/v2/glory/….

Виртуальные номера (коды из SMS)

Номер на один СМС-код: вы покупаете номер для сервиса, получаете код и отдаёте его клиенту. Цены как на сайте. Деньги списываются с баланса аккаунта ключа. Если номер не получился или код не пришёл за отведённое время, деньги возвращаются на баланс сами.

curl -s "https://donatix.tj/api/v1/numbers/services" -H "X-API-Key: $KEY"

{"ok": true, "items": [{"service": "telegram", "title": "Telegram"}, {"service": "whatsapp", "title": "WhatsApp"}]}

curl -s "https://donatix.tj/api/v1/numbers/countries?service=telegram" -H "X-API-Key: $KEY"

{"ok": true, "items": [{"country": "indonesia", "title": "Индонезия", "flag": "🇮🇩", "price_usd": "0.3100", "available": 120}]}

curl -s -X POST "https://donatix.tj/api/v1/numbers/orders" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": "indonesia"}'

{"ok": true, "order": {"id": 555, "service": "telegram", "country": "indonesia", "status": "PENDING", "phone": "+6281234567", "code": null, "sms": null, "price_usd": "0.3100", "expires": "2030-01-01T00:15:00Z", "refunded": false}}

curl -s "https://donatix.tj/api/v1/numbers/orders/555" -H "X-API-Key: $KEY"

Когда в code появится код, номер готов. Статусы: PENDING — ждём код, RECEIVED — код пришёл, FINISHED — завершён, CANCELED — отменён, TIMEOUT — код не пришёл, деньги вернулись, BANNED — номер отклонён сервисом, деньги вернулись.

curl -s -X POST "https://donatix.tj/api/v1/numbers/orders/555/cancel" -H "X-API-Key: $KEY"

Список своих заказов: GET /api/v1/numbers/orders?limit=20. Ошибки: insufficient_balance (402) — пополните баланс; order_failed (400) — номер не купился, деньги не списаны; service_unavailable (503) — сервис временно выключен.

Подарки Telegram

Подарок за Telegram Stars, который уходит на аккаунт получателя. Цена как на сайте, списание с баланса. Если знаете @username получателя и он уже нажимал Start в нашем боте, подарок уходит сразу. Если нет, создаётся ссылка: отправьте её получателю, он нажмёт Start и получит подарок.

curl -s "https://donatix.tj/api/v1/gifts" -H "X-API-Key: $KEY"

{"ok": true, "items": [{"gift_id": "g15", "stars": 15, "emoji": "🧸", "image": null, "price_usd": "0.2400", "left": null, "total": null}]}

curl -s -X POST "https://donatix.tj/api/v1/gifts/orders" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"gift_id": "g15", "recipient": "@username", "text": "С днём рождения!"}'

{"ok": true, "order": {"id": 91, "ref": "GF-91", "gift_id": "g15", "stars": 15, "price_usd": "0.2400", "status": "paid", "recipient": "@username", "link": null, "error": null}}

curl -s "https://donatix.tj/api/v1/gifts/orders/91" -H "X-API-Key: $KEY"

Если получатель ещё не нажимал Start, в ответе будет "status": "awaiting_recipient" и поле link: отправьте её получателю. Статусы: paid — в очереди, sent — отправлен, awaiting_recipient — ждём получателя, failed и refunded — деньги вернулись. Поле text — до 128 символов, подпись к подарку.

Ошибки

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

Лимиты на ключ: 60 заказов, 120 запросов каталога, 120 проверок статуса, 60 запросов аккаунта в минуту. Каталог кешируйте у себя на 5–15 минут, а не запрашивайте перед каждым заказом.

Правила и ответственность

API v2 — совместимый формат

Если ваш бот уже работает с API в формате v2, поменяйте в нём только адрес и ключ — всё остальное работает как есть:

Номера заказов у нас вида dx-123. Ответы и ошибки — в том же формате {"ok": false, "error": "…", "code": "…"}.

Webhook

Адрес указывается в панели → API. При смене статуса заказа придёт:

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)

Примеры

import uuid, requests

API = "https://donatix.tj/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"]

const res = await fetch("https://donatix.tj/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);