BancaStore · Документация для партнёров

BancaStore Partner API

Базовый адрес: https://api.bancastore.xyz

Версия v1. API предназначено для партнёрских магазинов; все операции выполняются от имени аккаунта, привязанного к API-ключу.

Авторизация

В личном чате с ботом выполните /apikey. Ключ отображается только при выпуске. Повторный выпуск отключает старый ключ; /revokeapikey отзывает его.

Authorization: Bearer ps_live_…

Не отправляйте API-ключ из браузера или публичного кода. Считайте его паролем от привязанного аккаунта.

Все временные метки в ответах API возвращаются в часовом поясе Europe/Moscow с явным смещением +03:00.

В ответе товара поле price — цена одной единицы. Для товара с ценой по количеству каталог также возвращает is_variable_pricing=true, min_quantity и max_quantity. Перед покупкой запросите котировку: количество должно попадать в этот диапазон, а сумма рассчитывается сервером.

Методы

Идентификаторы каталога и аккаунта

Получите актуальные ID из API каталога: числовой ID обычно сохраняется, пока запись существует, но может измениться после удаления и повторного добавления. Не копируйте ID из чужого примера и не используйте название вроде K12 вместо числа.

1. GET /v1/categories — возьмите data[].id и нужное имя категории.
2. GET /v1/products?category_id=CATEGORY_ID — возьмите data[].id нужной позиции; запрос возвращает только активные товары.
3. GET /v1/products/PRODUCT_ID — перед покупкой перепроверьте название, цену и наличие.

Известные ID провайдеров: platega — СБП/карта; cryptopay — Crypto Pay; xrocket — xRocket; telegram — Telegram Payments. Доступны только способы, которые сейчас настроены: ориентируйтесь на актуальный ответ GET /v1/balance/payment-methods.

Обозначения в названии товара

Коды и слова в названии описывают позицию, но не заменяют числовой product_id. Категории вроде ChatGPT, Gemini, Claude, Grok, Perplexity и CapCut также нужно выбирать по текущему category_id.

Актуальный каталог

Каталог и остатки меняются. Получайте category_id и product_id через API, а не из примеров:

curl -H 'Authorization: Bearer YOUR_API_KEY'   'https://api.bancastore.xyz/v1/products?limit=20'

GET /v1/categories возвращает категории, GET /v1/products?category_id=ID — товары выбранной категории. Содержимое склада и доступы к аккаунтам в каталоге не возвращаются.

Как купить товар по ID

Выберите product_id из актуального каталога. Сначала получите котировку, затем передайте её total без изменений как expected_total. Покупка списывает реальные деньги с баланса привязанного аккаунта.

import uuid
import requests

BASE = "https://api.bancastore.xyz"
API_KEY = "YOUR_API_KEY"
product_id = int(input("product_id из актуального каталога: "))
headers = {"Authorization": f"Bearer {API_KEY}"}

quote_response = requests.post(
    f"{BASE}/v1/orders/quote",
    headers=headers,
    json={"product_id": product_id, "quantity": 1},
)
quote_response.raise_for_status()
quote = quote_response.json()["data"]

order_response = requests.post(
    f"{BASE}/v1/orders",
    headers={**headers, "Idempotency-Key": f"store-{uuid.uuid4()}"},
    json={
        "product_id": product_id,
        "quantity": 1,
        "expected_total": quote["total"],
    },
)
print(order_response.status_code, order_response.json())

Для других позиций подставьте их product_id из актуального API каталога. Уникальный Idempotency-Key создавайте на каждую новую покупку; при сетевом тайм-ауте повторяйте тот же запрос с тем же ключом.

Пример запроса

curl -H 'Authorization: Bearer YOUR_API_KEY' \
  https://api.bancastore.xyz/v1/me

Перед покупкой отправьте JSON в POST /v1/orders/quote, затем повторите product_id, quantity и полученный total как expected_total в POST /v1/orders. Скидка за объём применяется автоматически к количеству одного товара в одном заказе: от 5 шт. — 5%, от 10 шт. — 10%. Промокоды на покупку отключены; балансные промокоды доступны отдельно. Заголовок Idempotency-Key обязателен. Корзина оформляется аналогично через GET /v1/cart и POST /v1/cart/checkout.

Поле expected_total берётся из серверной котировки, передаётся десятичной строкой и защищает от незаметного изменения цены. При ошибке сети повторяйте тот же запрос с тем же ключом.

Пример пополнения

POST /v1/balance/top-ups
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: store-topup-00043
Content-Type: application/json

{"provider":"platega","amount":100}

Для ответа payment_creation_indeterminate не создавайте новый ключ и второе пополнение: сначала проверьте оригинальный платёж или обратитесь в поддержку.

Ответы не кэшируются. Ошибки имеют JSON-поле error.code; ключ идемпотентности можно повторять только с тем же методом, путем и телом. Состояние request_in_progress следует повторять с тем же ключом, не создавая новый.

Скидки и проверка цены

Котировка возвращает unit_price (цена до скидки), subtotal, discount_percent, discount_amount и total. От 5 единиц одного товара действует 5%, от 10 — 10%; скидки не складываются. Разные товары в корзине считаются отдельно. Итог округляется один раз до копеек.

При изменении цены покупка отклоняется с price_changed: получите новую котировку и подтвердите новую сумму. Проверка закупочной стоимости может заблокировать убыточный заказ; баланс не списывается.

Ошибки и лимиты

Все ошибки имеют вид {"error":{"code":"…","message":"…","request_id":"…"}}. Сохраните request_id для обращения в поддержку.

Ключ привязан к одному Telegram-аккаунту. Передача чужого Telegram ID не меняет пользователя. Отозвать ключ можно командой /revokeapikey. Браузерные запросы с ключом и публикация ключей в клиентском JavaScript не поддерживаются: используйте свой сервер.

API-заказы поставщиков

Покупка API-товара возвращает HTTP 202 и supplier_orders. Повторяйте запрос покупки только с прежним Idempotency-Key и телом. Проверяйте статус через GET /v1/supplier-orders/{order_id}; после delivered используйте purchase_ids для получения чеков. При refunded сумма возвращена на баланс; review требует проверки администратором. Ограничения min_quantity/max_quantity учитывают минимальный заказ поставщика и доступное количество.