Жизненный цикл продажи
Продажа в BILLZ — объект, проходящий несколько состояний.
создан черновик ├── добавлены позиции ├── привязан клиент (необязательно) ├── применены скидки (необязательно) ├── добавлен сертификат (необязательно) │ ├──> отложен ──> возвращён в работу │ └──> оплачен ──> продажа (фискальный чек)Черновик
Заголовок раздела «Черновик»Создаётся вызовом POST /v2/order с телом {"shop_id": "…"}.
Это асинхронный метод: с Billz-Response-Channel: HTTP ответ приходит в конверте,
где ID черновика лежит в поле id, а его короткий номер — в data.order_number.
Черновик виден кассиру в магазине и существует, пока его не оплатили или не удалили
(DELETE /v2/order/:id — асинхронный).
Позиции
Заголовок раздела «Позиции»Добавляются по одной: POST /v2/order-product/:order_id (асинхронный), количество —
в поле sold_measurement_value.
Тот же метод и убирает позицию: sold_measurement_value: 0 удаляет строку из чека
вместе с назначенной на неё ручной скидкой.
Отложка
Заголовок раздела «Отложка»Отдельное состояние: чек приостановлен, но не потерян.
Отложить — POST /v2/order/create_postpone (асинхронный), в теле order_id, time
и необязательный comment. Вернуть в работу — POST /v2/order/return-postpone.
Поле time обязательно и требует строгого формата: 2024-07-16 06:47:30.
POST /v2/order-payment/:order_id закрывает чек. Это синхронный метод: заголовок Billz-Response-Channel ему не нужен.
В теле — массив платежей: чек можно оплатить несколькими способами сразу, а также
бонусами клиента через with_cashback. После оплаты черновик становится продажей
и попадает в отчёты.
Оплата требует открытой смены в магазине продажи при наличии кассовых смен. Разбор ошибок оплаты — в интернет-заказе.
Ручная скидка — POST /v2/order-manual-discount/:order_id (асинхронный): на всю корзину
или на конкретный товар, если передан product_id.
Пересчёт суммы чека — POST /v1/recalculate-order-bill/:order_id, синхронный:
ответ содержит пересчитанную детализацию продажи.
Что синхронно, а что нет
Заголовок раздела «Что синхронно, а что нет»У каждого метода свой режим:
| Метод | Как работает |
|---|---|
POST /v1/recalculate-order-bill/:order_id |
синхронно |
POST /v2/order-payment/:order_id |
синхронно |
GET /v2/order/:id, GET /v2/order-notes |
синхронно |
POST /v2/order (создание продажи) |
асинхронно |
POST /v2/order-product/:order_id |
асинхронно |
POST /v2/order-manual-discount/:order_id |
асинхронно |
PUT /v2/order-customer-new/:order_id |
асинхронно |
DELETE /v2/order/:id |
асинхронно |
POST /v2/order/create_postpone |
асинхронно |
POST /v2/order/return-postpone |
асинхронно |
Для асинхронных методов передаётся Billz-Response-Channel: HTTP, иначе в ответ приходит
только идентификатор запроса.