Seller API: инструкция и методы
Birgen Seller API позволяет вашему серверу получить товары, рассчитать покупку, создать заказ и забрать выдачу.
Быстрый старт / API
Как проходит покупка
Birgen Seller API позволяет вашему серверу получить товары, рассчитать покупку, создать заказ и забрать выдачу.
Получите доступ
Создайте ключ в боте Birgen Store: Профиль → Мой API. Сохраните ключ и секрет в конфигурации своего сервера.
Получите каталог
Вызовите GET /products?currency=USDT. Выберите id товара, проверьте available, цену и остаток.
Рассчитайте покупку
Вызовите GET /quote?product_id=123&quantity=2¤cy=USDT. Списания ещё нет. Полученный quote_token используйте, пока расчёт актуален.
Создайте один заказ
Отправьте POST /orders с external_order_id, ID товара, количеством, валютой, quote token и заголовком Idempotency-Key. Успешный POST создаёт реальную покупку.
Получите результат
Опрашивайте GET /orders/{id}. После тайм-аута сначала найдите существующий заказ по external_order_id, затем решайте, нужен ли повтор того же POST.
Подписывайте каждый закрытый запрос
Для всех методов, кроме GET /health, нужны эти заголовки. Подписывайте точный HTTP-метод, путь вместе с query string и исходные байты тела. Денежные значения в JSON передавайте строками.
X-Api-Key— ключ аккаунта Birgen Store.X-Timestamp— Unix-время в секундах; допустимое расхождение часов — пять минут.X-Nonce— новое значение длиной 16–128 символов изA–Z a–z 0–9 _ -; не повторять десять минут.X-Signature— HMAC-SHA256 в нижнем регистре hex.
HMAC-SHA256(secret, timestamp + "." + nonce + "." + METHOD + "." + path_with_query + "." + raw_body)Python: запрос каталога с подписью
Пример берёт данные доступа из переменных окружения и не создаёт покупку.
import hashlib, hmac, json, os, secrets, time
from urllib.request import Request, urlopen
path = "/api/v1/products?currency=USDT"
timestamp = str(int(time.time()))
nonce = secrets.token_urlsafe(24)
body = b""
payload = b".".join((timestamp.encode(), nonce.encode(), b"GET", path.encode(), body))
signature = hmac.new(os.environ["BIRGEN_API_SECRET"].encode(), payload, hashlib.sha256).hexdigest()
request = Request("https://grinberg.cc" + path, headers={
"X-Api-Key": os.environ["BIRGEN_API_KEY"],
"X-Timestamp": timestamp, "X-Nonce": nonce, "X-Signature": signature,
})
with urlopen(request, timeout=15) as response:
products = json.load(response)["products"]Методы
Базовый адрес: https://grinberg.cc/api/v1
/api/v1/health
Публичная проверка {"ok":true,"service":"seller_api"}.
/api/v1/products?currency=USDT
Массив товаров и rub_per_usdt. У товара есть ID, название, цена, доступность и лимит; stock появляется, когда остаток известен.
/api/v1/balances
Баланс владельца ключа, например {"balances":{"USDT":"12.50"}}.
/api/v1/quote?product_id=123&quantity=2¤cy=USDT
Расчёт: цена, итог, доступность, лимит, возможный остаток и quote_token. Средства не списывает.
/api/v1/orders
Создаёт покупку. Нужны Idempotency-Key и поля JSON: external_order_id, product_id, quantity, currency, quote_token.
/api/v1/orders/{order_id}
Заказ владельца ключа: статус, сумма, товар, время и текст выдачи после доставки.
/api/v1/orders/by-external?external_order_id=…
Поиск своего заказа после сетевого тайм-аута или замены ключа.
Заказы и выдача
Используйте уникальный external_order_id для каждой покупки и Idempotency-Key длиной 16–128 символов. Повтор с тем же ключом и полностью тем же телом вернёт тот же заказ без второго списания. Изменение тела при том же ключе или присвоение занятого внешнего ID другой покупке вызовет конфликт.
{
"external_order_id": "my-order-10069",
"product_id": 123,
"quantity": 2,
"currency": "USDT",
"quote_token": "<token from GET /quote>"
}delivery_text; поле доступно и при следующих запросах.Ошибки и безопасные повторы
400— некорректный запрос, JSON, расчёт, валюта или отсутствующий idempotency key.401— нет обязательных заголовков, истёк timestamp или неверна подпись.404— товар или заказ не найден.409— изменилась цена, заказ отклонён, повторён nonce либо конфликтует ключ или внешний ID.413— слишком большое тело.429— ограничение частоты.500или тайм-аут — восстановите состояние по external order ID до повтора POST.
Точную актуальную схему и описание полей можно открыть в живой спецификации OpenAPI.