API — Snow Funpay

Как начать

Откройте бота Snow Funpay и пополните баланс — покупки через API списываются с вашего баланса в боте.
Отправьте боту команду /apikey и нажмите «Создать ключ». Ключ выглядит так: sk_AbCdEf1234…
Передавайте ключ в заголовке каждого запроса:

X-API-Key: sk_ваш_ключ

Перевыпуск ключа в /apikey мгновенно отключает старый — так же делайте, если ключ утёк.

Базовый адрес

https://api.snowstore.xyz/api/v1

Эндпоинты

`GET /api/v1/ping`

Проверка, что сервер жив. Ключ не нужен.

curl https://api.snowstore.xyz/api/v1/ping

{"ok": true, "service": "snowshop-api", "version": 1, "api_enabled": true}

`GET /api/v1/me`

Ваш профиль и баланс.

curl https://api.snowstore.xyz/api/v1/me -H "X-API-Key: sk_ваш_ключ"

{"telegram_id": 123456789, "username": "seller1", "full_name": "Иван", "balance": 1500.0, "total_spent": 320.0}

`GET /api/v1/catalog`

Категории и товары с ценами и остатками. ?in_stock=1 — только то, что есть в наличии.

curl "https://api.snowstore.xyz/api/v1/catalog?in_stock=1" -H "X-API-Key: sk_ваш_ключ"

{
  "categories": [{"id": 1, "name": "Подписки", "parent_id": null}],
  "products": [
    {"id": 42, "category_id": 1, "name": "ChatGPT Plus 1 месяц", "price": 450.0,
     "is_digital": true, "stock": 7, "in_stock": true}
  ]
}

`GET /api/v1/products/{id}`

Один товар — тот же формат, что в каталоге.

curl https://api.snowstore.xyz/api/v1/products/42 -H "X-API-Key: sk_ваш_ключ"

`POST /api/v1/orders`

Купить товар. Деньги списываются с баланса, товар сразу приходит в ответе.

curl -X POST https://api.snowstore.xyz/api/v1/orders \
  -H "X-API-Key: sk_ваш_ключ" -H "Content-Type: application/json" \
  -d '{"product_id": 42, "quantity": 1}'

Ответ 201 Created:

{
  "order_id": 1234, "product_id": 42, "product_name": "ChatGPT Plus 1 месяц",
  "quantity": 1, "total_price": 450.0, "status": "completed", "is_digital": true,
  "delivered_items": ["login:pass"], "balance_after": 1050.0
}

delivered_items — по одной строке на каждую купленную единицу.

`GET /api/v1/orders/{id}`

Статус и выдача своего заказа (чужие — 404).

curl https://api.snowstore.xyz/api/v1/orders/1234 -H "X-API-Key: sk_ваш_ключ"

`GET /api/v1/orders`

Последние заказы. ?limit=20 — от 1 до 100.

curl "https://api.snowstore.xyz/api/v1/orders?limit=10" -H "X-API-Key: sk_ваш_ключ"

Пример на Python

import requests

BASE = "https://api.snowstore.xyz/api/v1"
KEY = "sk_ваш_ключ"
H = {"X-API-Key": KEY}

print(requests.get(f"{BASE}/me", headers=H, timeout=30).json())

r = requests.post(f"{BASE}/orders", headers=H, json={"product_id": 42, "quantity": 1}, timeout=60)
data = r.json()
if r.status_code == 201:
    for item in data["delivered_items"]:
        print("Выдано:", item)
else:
    print("Ошибка:", data["error"], data["message"])

Коды ошибок

Все ошибки — JSON: {"error": "код", "message": "описание"}

HTTP	`error`	Когда
400	`bad_request`	Неверное тело запроса или параметры
401	`missing_api_key`	Нет заголовка `X-API-Key`
401	`invalid_api_key`	Ключ неверный или перевыпущен
402	`insufficient_balance`	Не хватает денег на балансе — пополните в боте
403	`account_banned`	Аккаунт заблокирован
404	`not_found`	Товар или заказ не найден
409	`out_of_stock`	Товар закончился (деньги, если списались, уже вернулись на баланс)
422	`not_purchasable_via_api`	Товар выдаётся вручную — купите его в боте
503	`supplier_unavailable`	Поставщик временно недоступен, деньги вернулись — повторите позже
503	`api_disabled`	API временно выключен магазином
500	`internal_error`	Внутренняя ошибка — повторите позже

Вопросы

Деньги могут списаться дважды при повторе запроса? Каждый POST /orders — новая покупка. Если ответ не пришёл (обрыв связи), сначала проверьте GET /orders — заказ мог уже создаться.

Что если на балансе не хватает? Ответ 402, заказ не создаётся, деньги не списываются.

Что если товар закончился во время покупки? Ответ 409, списанные деньги автоматически возвращаются на баланс.

Начисляется ли реферальный бонус? Да, как при обычной покупке в боте.