Birgen Store / Seller API v2

Seller API: инструкция и методы

Birgen Seller API позволяет вашему серверу получить товары, рассчитать покупку, создать заказ и забрать выдачу.

Как проходит покупка

Birgen Seller API позволяет вашему серверу получить товары, рассчитать покупку, создать заказ и забрать выдачу.

01 / 05

Получите доступ

Создайте ключ в боте Birgen Store: Профиль → Мой API. Сохраните ключ и секрет в конфигурации своего сервера.

02 / 05

Получите каталог

Вызовите GET /products?currency=USDT. Выберите id товара, проверьте available, цену и остаток.

03 / 05

Рассчитайте покупку

Вызовите GET /quote?product_id=123&quantity=2&currency=USDT. Списания ещё нет. Полученный quote_token используйте, пока расчёт актуален.

04 / 05

Создайте один заказ

Отправьте POST /orders с external_order_id, ID товара, количеством, валютой, quote token и заголовком Idempotency-Key. Успешный POST создаёт реальную покупку.

05 / 05

Получите результат

Опрашивайте 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
HMAC-SHA256(secret, timestamp + "." + nonce + "." + METHOD + "." + path_with_query + "." + raw_body)
Для каждой попытки создавайте новый nonce. При идемпотентном повторе заказа сохраняйте исходное тело и Idempotency-Key.

Python: запрос каталога с подписью

Пример берёт данные доступа из переменных окружения и не создаёт покупку.

Python 3
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

GET

/api/v1/health

Публичная проверка {"ok":true,"service":"seller_api"}.

GET

/api/v1/products?currency=USDT

Массив товаров и rub_per_usdt. У товара есть ID, название, цена, доступность и лимит; stock появляется, когда остаток известен.

GET

/api/v1/balances

Баланс владельца ключа, например {"balances":{"USDT":"12.50"}}.

GET

/api/v1/quote?product_id=123&quantity=2&currency=USDT

Расчёт: цена, итог, доступность, лимит, возможный остаток и quote_token. Средства не списывает.

POST

/api/v1/orders

Создаёт покупку. Нужны Idempotency-Key и поля JSON: external_order_id, product_id, quantity, currency, quote_token.

GET

/api/v1/orders/{order_id}

Заказ владельца ключа: статус, сумма, товар, время и текст выдачи после доставки.

GET

/api/v1/orders/by-external?external_order_id=…

Поиск своего заказа после сетевого тайм-аута или замены ключа.

Заказы и выдача

Используйте уникальный external_order_id для каждой покупки и Idempotency-Key длиной 16–128 символов. Повтор с тем же ключом и полностью тем же телом вернёт тот же заказ без второго списания. Изменение тела при том же ключе или присвоение занятого внешнего ID другой покупке вызовет конфликт.

POST /api/v1/orders · JSON
{
  "external_order_id": "my-order-10069",
  "product_id": 123,
  "quantity": 2,
  "currency": "USDT",
  "quote_token": "<token from GET /quote>"
}
PROCESSINGОжидайте и опрашивайте заказ; новый не создавайте.
DELIVEREDПолучите delivery_text; поле доступно и при следующих запросах.
REFUNDEDДеньги за закупку вернулись на баланс магазина.
SUPPORT_REQUIREDОбратитесь в поддержку с номером заказа.
Формат выдачи зависит от товара. Нельзя всегда считать пустую строку разделителем единиц.

Ошибки и безопасные повторы

  • 400 — некорректный запрос, JSON, расчёт, валюта или отсутствующий idempotency key.
  • 401 — нет обязательных заголовков, истёк timestamp или неверна подпись.
  • 404 — товар или заказ не найден.
  • 409 — изменилась цена, заказ отклонён, повторён nonce либо конфликтует ключ или внешний ID.
  • 413 — слишком большое тело. 429 — ограничение частоты.
  • 500 или тайм-аут — восстановите состояние по external order ID до повтора POST.

Точную актуальную схему и описание полей можно открыть в живой спецификации OpenAPI.