Перейти к содержимому

Жизненный цикл продажи

Продажа в 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, иначе в ответ приходит только идентификатор запроса.