Инструкция и документация Seller API
Русский · English · OpenAPI JSON
Seller API предназначен только для серверного плагина или backend. Не помещайте API secret в FunPay-лот, браузер, клиентский мод или публичный репозиторий. Создайте ключ в «Мой API», сохраните API key и API secret: они показываются один раз. При замене старый ключ перестаёт работать только после подтверждения; новый ключ остаётся владельцем того же Telegram-аккаунта, поэтому видит его баланс и прежние API-заказы.
Базовый URL: https://grinberg.cc/api/v1. Все суммы в JSON передавайте и читайте строками: "3.09", никогда не float. Рублёвую сумму рассчитывает магазин по своему курсу.
Подпись каждого закрытого запроса
Передавайте X-Api-Key, X-Timestamp (Unix seconds), X-Nonce (уникальные 16–128 A-Za-z0-9_-), X-Signature. Подпись — lowercase hex HMAC-SHA256(secret, timestamp + "." + nonce + "." + METHOD + "." + path_with_query + "." + raw_body). У часов допускается 5 минут; nonce нельзя повторить 10 минут. Для GET тело — пустые байты. Используйте новый nonce для каждой попытки, включая повтор с тем же Idempotency-Key.
Обычный путь покупки
1. GET /products?currency=USDT — выберите id. Товар с available: false недоступен для покупки.
2. GET /quote?product_id=123&quantity=3¤cy=USDT. Ответ не списывает средства: unit_price, total, available, max_quantity, quote_token; stock передаётся, когда количество известно.
3. Если available true, немедленно создайте заказ с возвращённым quote_token, новым external_order_id и новым Idempotency-Key.
4. Опросите GET /orders/{id} либо GET /orders/by-external?external_order_id=... до финального статуса. Не запускайте новую покупку после сетевого тайм-аута: сначала найдите этот заказ по external_order_id, затем повторите тот же POST тем же телом и Idempotency-Key только если это действительно нужно.
Рост цены между quote и POST даёт 409 price_changed: заказ не создан и баланс не списан. Снижение цены разрешено — списывается новая меньшая стоимость. Наличие и баланс резервируются атомарно: два параллельных запроса не продадут одну единицу дважды.
POST /orders
Заголовок Idempotency-Key обязателен (16–128 символов). Тело:{"external_order_id":"funpay-10069","product_id":123,"quantity":3,"currency":"USDT","quote_token":"..."}.
external_order_id уникален в пределах аккаунта. Повтор с тем же idempotency key и полностью тем же телом возвращает тот же заказ без второго списания. Тот же ключ с другим телом — 409 idempotency_conflict; повтор другого external_order_id — 409 external_order_conflict.
Статусы
PROCESSING — ожидайте и не создавайте повторный заказ. DELIVERED — поле delivery_text содержит данные купленного товара и доступно при последующих запросах. REFUNDED — средства возвращены на баланс. SUPPORT_REQUIRED — обратитесь в поддержку, указав номер заказа. Получайте статус и данные заказа через API.
Пример подписи и получения каталога на Python
Подставьте свои данные только на сервере. Порядок и кодирование параметров пути должны совпадать в подписи и запросе. Для заказа используйте тот же способ подписи, передав точные байты JSON и заголовок Idempotency-Key.
import hashlib, hmac, json, secrets, time
from urllib.request import Request, urlopen
api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"
path = "/api/v1/products?currency=USDT"
body = b""
timestamp = str(int(time.time()))
nonce = secrets.token_urlsafe(24)
signed = b".".join([timestamp.encode(), nonce.encode(), b"GET", path.encode(), body])
signature = hmac.new(api_secret.encode(), signed, hashlib.sha256).hexdigest()
request = Request("https://grinberg.cc" + path, headers={
"X-Api-Key": api_key, "X-Timestamp": timestamp,
"X-Nonce": nonce, "X-Signature": signature,
})
with urlopen(request, timeout=15) as response:
products = json.load(response)["products"]
Для интеграции с Codex / Claude / другим ИИ передайте эту инструкцию без реальных ключей. Реальные тестовые покупки выполняйте только с вашего разрешения.
GET /health публичен: {"ok":true,"service":"seller_api"}. Все остальные методы требуют подпись из инструкции.
GET /products?currency=USDT|RUB возвращает products[], rub_per_usdt. Рублёвые значения и курс рассчитывает магазин; не используйте в интеграции фиксированный внешний курс. Поля товара: id, title, product_name, variant_name, brand, product_type, denomination, description, category, region, delivery_type, price:{amount,currency}, prices:{USDT,RUB}, available, max_quantity. Поле stock присутствует, когда количество известно; stock: 0 означает нулевой остаток. Если available: false, товар недоступен для покупки.
GET /balances возвращает {"balances":{"USDT":"12.50","RUB":"0.00"}} для владельца ключа.
GET /quote?product_id=123&quantity=2¤cy=USDT возвращает quote. Пример: {"ok":true,"quote":{"product_id":123,"quantity":2,"currency":"USDT","unit_price":"3.09","total":"6.18","available":true,"max_quantity":5,"stock":7,"quote_token":"..."}}. При недоступности цена, total и token равны null; это не ошибка и не разрешение на POST.
POST /orders требует Idempotency-Key. Пример тела: {"external_order_id":"funpay-10069","product_id":123,"quantity":2,"currency":"USDT","quote_token":"..."}. Успех 201: {"ok":true,"idempotent_replay":false,"order":{...}}; повтор — 200 и idempotent_replay:true.
GET /orders/{order_id} и GET /orders/by-external?external_order_id=funpay-10069 возвращают только заказы владельца ключа (после замены ключа — того же аккаунта). Поля: id, external_order_id, status, amount (строка), currency, product:{title,quantity}, created_at, delivered_at; delivery_text только при DELIVERED. Возможные статусы: PROCESSING, DELIVERED, REFUNDED, SUPPORT_REQUIRED.
Когда данные единиц доступны отдельно, они разделяются пустой строкой; одна единица при этом может содержать несколько строк. Если выдача представлена одним текстом, её формат сохраняется, поэтому автоматическое разделение по пустым строкам не гарантируется.
Пример ответа на запрос заказа (данные условные):
{
"ok": true,
"order": {
"id": 10069,
"external_order_id": "funpay-10069",
"status": "DELIVERED",
"amount": "6.18",
"currency": "USDT",
"product": {"title": "Example — Standard", "quantity": 2},
"created_at": "2026-01-01T12:00:00+00:00",
"delivered_at": "2026-01-01T12:01:00+00:00",
"delivery_text": "Example delivery data"
}
}
Ошибки всегда: {"ok":false,"error":{"code":"...","message":"..."}}. Основные: 400 invalid_request, invalid_json, invalid_quote, invalid_currency, idempotency_required; 401 auth_headers_missing, timestamp_invalid, timestamp_expired, auth_failed, bad_signature, unauthorized; 404 product_not_found, order_not_found; 409 price_changed, order_rejected, idempotency_conflict, external_order_conflict, nonce_reused, order_processing; 413 payload_too_large; 429 rate_limited; 500 internal_error. Сообщения об ошибках нейтральны и не раскрывают внутреннюю обработку. На 500/тайм-аут не создавайте новую закупку: восстановите её GET по external ID.