Списание товара
Задача: списать товар со склада магазина — брак, потеря, недостача — и увидеть уменьшение остатка.
Списание в BILLZ двухшаговое: сначала собирается документ, потом он проводится. Остаток двигает только проведение.
GET /v2/write-off-reason причина списания (справочник)POST /v2/write-off ──> ID документа (черновик)POST /v2/write-off/:id/add каждая позиция отдельным запросомPUT /v2/write-off/finish/:id провести ──> остаток уменьшаетсяВсе методы изменения — асинхронные. Требуется заголовок Billz-Response-Channel: HTTP,
иначе вместо результата приходит только идентификатор события.
1. Причина списания
Заголовок раздела «1. Причина списания»curl -X GET 'https://api-admin.billz.ai/v2/write-off-reason' \ -H 'Authorization: Bearer ТОКЕН'{ "count": 5, "write_off_reasons": [ { "id": "d6ccea76-...", "name": "Дефект" } ] }Причины заводятся только в интерфейсе BILLZ.
2. Создать документ
Заголовок раздела «2. Создать документ»curl -X POST 'https://api-admin.billz.ai/v2/write-off' \ -H 'Authorization: Bearer ТОКЕН' \ -H 'Content-Type: application/json' \ -H 'Billz-Response-Channel: HTTP' \ -d '{ "name": "Списание 2026-08-22", "reason_id": "d6ccea76-7412-48b0-bad3-e0bc0f41673f", "shop_id": "70919136-9481-4c7e-8581-685d750d67a9", "comment": "" }'Магазин списания задаётся полем shop_id.
3. Добавить позиции
Заголовок раздела «3. Добавить позиции»По одной позиции на запрос. :id — ID документа из предыдущего шага.
curl -X POST 'https://api-admin.billz.ai/v2/write-off/ID_СПИСАНИЯ/add' \ -H 'Authorization: Bearer ТОКЕН' \ -H 'Content-Type: application/json' \ -H 'Billz-Response-Channel: HTTP' \ -d '{ "shop_id": "70919136-9481-4c7e-8581-685d750d67a9", "product_id": "aba9d9ad-5d37-4836-81a4-9a60648d087e", "writeoff_measurement_value": 1 }'| Поле | Что это |
|---|---|
shop_id |
магазин списания, тот же, что и в документе |
product_id |
UUID товара из GET /v2/products |
writeoff_measurement_value |
количество к списанию |
4. Провести
Заголовок раздела «4. Провести»curl -X PUT 'https://api-admin.billz.ai/v2/write-off/finish/ID_СПИСАНИЯ' \ -H 'Authorization: Bearer ТОКЕН' \ -H 'Content-Type: application/json' \ -H 'Billz-Response-Channel: HTTP'Проведение и списание остатка (FIFO) выполняются в одной транзакции.
Отклонить непроведённый документ — PUT /v2/write-off/cancel/:id.
Для пользователя веб-интерфейса списание разведено на четыре независимых права:
| Право | Что открывает |
|---|---|
| Просмотр списка списаний | список списаний, позиции, выгрузки |
| Просмотр себестоимости списаний | карточку документа с себестоимостью |
| Создание списания | создание, /add, /remove, правка и отклонение (cancel) |
| Завершение списаний | PUT /v2/write-off/finish/:id |
Отчёт по списаниям — отдельное право («Отчёт „Списания“»).
Как проверить результат
Заголовок раздела «Как проверить результат»| Что | Метод |
|---|---|
| Отчёт по списаниям | GET /v1/write-off-report-table |
| Остаток товара сейчас | GET /v2/products → shop_measurement_values[].active_measurement_value |
Похожие процессы
Заголовок раздела «Похожие процессы»Трансфер и заказ поставщику устроены по той же схеме «собрать → наполнить → провести» — см. складские процессы.