К содержанию
Libermall для разработчиков
Buyer API › Первые шаги

Buyer API

Для партнёров, которые перепродают товары Libermall в своём приложении, боте или магазине: те же товары, цены и защита покупателя, что на сайте. Покупка оплачивается с вашего кошелька Libermall. Базовый адрес — https://api.libermall.com/buyer-api, заголовок — x-buyer-api-key.

1. Пополните кошелёк и выпустите ключ

libermall.com → Кабинет → Кошелёк, затем Кабинет → API. Выпустить ключ может только защищённый аккаунт: подтверждена почта, привязан Telegram, включена двухфакторная защита. При создании ключа спросим код 2FA и пришлём на почту ссылку: ключ заработает только после подтверждения (ссылка действует 30 минут). Ключ показывается один раз — храните его только на сервере. Права — ключи и права.

curl https://api.libermall.com/buyer-api/balance \
  -H "x-buyer-api-key: $LIBERMALL_BUYER_KEY"

2. Найдите товар

curl "https://api.libermall.com/buyer-api/products?q=playstation" \
  -H "x-buyer-api-key: $LIBERMALL_BUYER_KEY"

GET /buyer-api/products/{id} отдаёт номиналы, описание и инструкцию активации. Каждый номинал — отдельный variant_id, у него есть цена и признак in_stock.

Импорт каталога с разделами

Переносите каталог в свой магазин? Сначала заберите дерево разделов, затем товары постранично — у каждого товара есть categories и primary_category_id, раздел, в который его положить.

# 1. Разделы: корни и непустые подразделы, со счётчиком товаров
curl "https://api.libermall.com/buyer-api/categories" \
  -H "x-buyer-api-key: $LIBERMALL_BUYER_KEY"

# 2. Товары по 100, пока next_offset не станет null
curl "https://api.libermall.com/buyer-api/products?limit=100&offset=0" \
  -H "x-buyer-api-key: $LIBERMALL_BUYER_KEY"

Нужен один раздел — передайте category_id в GET /buyer-api/products: в выдачу попадут и его подразделы. Раздел, скрытый для вашего аккаунта (по стране или входу), не появится ни в дереве, ни у товаров.

Деньги

Все суммы — целые числа в минимальных единицах валюты кошелька (копейках для рублей). Какая это валюта, написано в поле currency каждого ответа. price_usd_minor у номинала — только для справки: списание всегда в валюте кошелька. Цены те же, что на витрине.

3. Купите

curl -X POST https://api.libermall.com/buyer-api/orders \
  -H "x-buyer-api-key: $LIBERMALL_BUYER_KEY" \
  -H "Idempotency-Key: my-order-1042" \
  -H "Content-Type: application/json" \
  -d '{"variant_id":"variant_…","quantity":1,"max_price_minor":120000,"external_ref":"1042"}'

Повтор с тем же ключом — тот же заказ, второго списания не будет. Цена выросла выше max_price_minor — 409 price_changed, ничего не списано. Не хватает денег — 402 insufficient_balance. Все ответы — покупка с кошелька.

4. Заберите код

Дождитесь вебхука order.fulfilled (адрес задаётся через PUT /buyer-api/webhook) или опрашивайте GET /buyer-api/orders/{id}. Когда status = fulfilled, коды и инструкция — в items[].codes и items[].instructions.

Нет товара у продавца — деньги вернутся на кошелёк сами, status станет refunded, причина — в reason.

Справочник Buyer API OpenAPI 3.1