К содержанию
Libermall для разработчиков
Seller API › Способы выдачи

Способы выдачи

Четыре способа продавать. Отличаются они одним полем товара — delivery_type.
delivery_typeКогда подходит
digital_instantУ вас есть готовые коды: загружаете их заранее, площадка выдаёт сама в момент оплаты. Писать ничего не нужно.
external_apiТовар выпускает ваш сервер в момент продажи — карты, аккаунты, коды. Libermall присылает подписанное событие, вы отвечаете товаром.
smm_panelУслуги: заказ уходит вашему поставщику по стандарту JAP. Подключение заводится один раз в кабинете, дальше его id берётся из /suppliers.
ручная выдачаКогда выдача не автоматизируется: вы закрываете строку заказа сами через POST /orders/{id}/fulfill, идемпотентно.

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

Для товаров с delivery_type=external_api укажите в кабинете адрес выдачи. Когда заказ оплачен, Libermall отправляет на него событие fulfillment.requested. Ваша задача — четыре шага.

1. Проверьте подпись

Заголовок X-Libermall-Signature: t=<unix>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{сырое тело}"). Считайте подпись по сырому телу запроса и отклоняйте метку времени старше 5 минут.

import { verifyWebhookSignature } from "@libermall/shop-sdk"

let event
try {
  // бросает ошибку, если подпись не сходится или метка старше 5 минут
  event = verifyWebhookSignature(rawBody, req.headers["x-libermall-signature"], secret)
} catch {
  return res.status(401).end()
}

2. Проверьте оплату у нас

Вызовите verify_url из события (это ваш GET /orders/{id}) и убедитесь, что заказ оплачен. Никогда не доверяйте одному телу события.

3. Выдайте товар один раз

Одна строка заказа — один товар, навсегда. idempotency_key в событии равен id строки: повтор должен вернуть тот же товар.

4. Ответьте

Подходят оба стиля — Libermall читает их одинаково:

ИтогСтатусом HTTP200 и поле status
Выдано200 {status:"fulfilled", items:[…]}то же
Уже выдано раньше409 {items:[…]}200 {status:"already_fulfilled", items:[…]}
Нет в наличии422200 {status:"out_of_stock"}

Два правила решают, получит покупатель товар или деньги назад.

В любом ответе «выдано» обязателен непустой items — без него строка считается не выданной.

Всё, что мы не можем прочитать, — провал: голый 200 {}, неизвестный status, другие 4xx и 5xx, таймаут. Такая строка уходит на проверку, покупателю возвращаются деньги. Простое «OK» — не выдача.

При «нет в наличии» Libermall сам возвращает покупателю деньги. Схема события — в справочнике.