Libermall Merchant API

Ваш каталог на Libermall — по API

Товары, заказы, выдача в момент продажи, баланс и выплаты. Один ключ, понятные скоупы, идемпотентность на каждой записи. Ниже — путь от пустого магазина до опубликованного товара за пять минут.

За пять минут Полный справочник SDK для Node.js

Первый товар за пять минут

Всё, что ниже — обычный HTTPS. Базовый адрес — https://api.libermall.com.

  1. Выпустите ключ

    Кабинет продавца → API-ключи. Скоупы выдаются по одному: для каталога хватит products:read и products:write. Секрет показывается ровно один раз.

  2. Проверьте, в какой магазин пишет ключ

    Магазин определяется ключом — в запросах его нет. Если магазинов несколько, это единственный способ убедиться, что каталог поедет туда, куда вы думаете. 

    # кто я
curl https://api.libermall.com/admin/seller-api/me \
  -H "x-seller-api-key: $LIBERMALL_API_KEY"

    В ответе есть payout_verified. Если он false — витрина не покажет товары этого магазина, как бы они ни были опубликованы. Это самый частый ответ на «залил каталог, а на сайте пусто».

  3. Возьмите категорию

    Плоский список, у каждой строки есть parent_id — дерево собирается за один запрос.

    curl https://api.libermall.com/admin/seller-api/categories \
  -H "x-seller-api-key: $LIBERMALL_API_KEY"

  4. Создайте товар — сразу с обложкой

    Ссылку на картинку можно давать свою: Libermall скачает её и положит к себе, поэтому обложка не отвалится, если ваш адрес переедет. Отдельный запрос на загрузку нужен, только если картинки нигде не опубликованы. 

    curl -X POST https://api.libermall.com/admin/seller-api/products \
  -H "x-seller-api-key: $LIBERMALL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Ключ активации",
    "delivery_type": "digital_instant",
    "category_id": "pcat_…",
    "thumbnail": "https://ваш-сайт/cover.png",
    "status": "published",
    "variants": [{ "title": "Стандарт",
      "prices": [{ "amount": 9.99, "currency_code": "usd" }] }]
  }'

  5. Повторяйте безопасно

    Idempotency-Key обязателен на каждой записи. Повтор с тем же ключом вернёт тот же товар, а не второй такой же — сеть может оборваться в любой момент, и это нормально.

Рецепты под задачу

Четыре способа продавать. Отличаются они одним полем — delivery_type.

digital_instant

Готовые ключи из пула

Вы заранее загружаете коды, площадка выдаёт их сама в момент оплаты. Ничего писать не нужно.

 external_api

Выдача на лету

Товар выпускается вашим сервером в момент продажи — карты, аккаунты, коды. Libermall присылает подписанное событие, вы отвечаете товаром.

 smm_panel

Услуги через панель

Заказ уходит вашему поставщику по стандарту JAP. Подключение заводится один раз в кабинете (там боевые креды), дальше id берётся из /suppliers и каталог живёт по API.

 ручная выдача

Отдать заказ руками

Когда выдача не автоматизируется: вы закрываете строку заказа сами, идемпотентно.

Ответы, которые экономят день

Товары загрузились, а на витрине пусто.
Скорее всего магазин ещё не прошёл верификацию выплат. Проверьте payout_verified в /me: товары непроверенного магазина витрина не показывает.
Что именно вернуть из своего эндпоинта выдачи?
Годятся обе формы — статусом HTTP (409, 422) или 200 с полем status. Важнее другое: в любом «выдано» обязателен items, а всё нечитаемое, включая голый 200 {}, считается провалом и ведёт к возврату денег покупателю. Подробно — в разделе Selling on the fly.
Ключ вернул 403.
Скоупы работают fail-closed: чего нет в ключе, того нет вовсе. В теле ответа написано, какого именно скоупа не хватает.
Какие картинки принимаются?
PNG, JPEG, WebP, GIF. До 5 МБ, до 10 на товар. Тип определяется по содержимому файла, а не по расширению. SVG не принимается.
Цена в ответе — это что?
Десятичная строка в валюте отображения, например "12.50". Внутри деньги считаются в минорных единицах.
В кабинете ключ, которого я не создавал.
Значит его выпустила поддержка Libermall по обращению — такие ключи помечены. Если обращения не было, отзовите ключ и напишите нам.