Способы выдачи
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 читает их одинаково:
| Итог | Статусом HTTP | 200 и поле status |
|---|---|---|
| Выдано | 200 {status:"fulfilled", items:[…]} | то же |
| Уже выдано раньше | 409 {items:[…]} | 200 {status:"already_fulfilled", items:[…]} |
| Нет в наличии | 422 | 200 {status:"out_of_stock"} |
Два правила решают, получит покупатель товар или деньги назад.
В любом ответе «выдано» обязателен непустой items — без него строка считается не выданной.
Всё, что мы не можем прочитать, — провал: голый 200 {}, неизвестный status, другие 4xx и 5xx, таймаут. Такая строка уходит на проверку, покупателю возвращаются деньги. Простое «OK» — не выдача.
При «нет в наличии» Libermall сам возвращает покупателю деньги. Схема события — в справочнике.