3. Первая продажа
Продажа в BILLZ собирается по шагам: создать продажу → добавить позиции → (привязать клиента, применить скидки) → оплатить.
1. Создать продажу
Заголовок раздела «1. Создать продажу»curl -X POST 'https://api-admin.billz.ai/v2/order?Billz-Response-Channel=HTTP' \ -H 'Authorization: Bearer ТОКЕН' \ -H 'Content-Type: application/json' \ -d '{ "shop_id": "ID_МАГАЗИНА", "cashbox_id": "ID_КАССЫ" }'Параметр cashbox_id можно опустить.
Метод асинхронный: Billz-Response-Channel=HTTP (здесь — query-параметром, можно и
одноимённым заголовком) заставляет API дождаться результата и вернуть его в конверте.
{ "status_code": 200, "id": "38c3920a-ffdd-4233-a823-8af3266f5f4f", "data": { "id": "38c3920a-ffdd-4233-a823-8af3266f5f4f", "order_number": "5632631379", "order_type": "SALE" }, "correlation_id": "3674f28e-7b96-4683-87c3-80892698f421"}UUID продажи — поле id (то же значение лежит в data.id), он понадобится во всех
следующих шагах. order_number — короткий номер, который видно в интерфейсе BILLZ.
Магазин задаётся полем shop_id, касса — cashbox_id; список магазинов возвращает
GET /v1/shop.
2. Добавить товар
Заголовок раздела «2. Добавить товар»curl -X POST 'https://api-admin.billz.ai/v2/order-product/ID_ПРОДАЖИ' \ -H 'Authorization: Bearer ТОКЕН' \ -H 'Content-Type: application/json' \ -H 'Billz-Response-Channel: HTTP' \ -d '{ "product_id": "ID_ТОВАРА", "sold_measurement_value": 1 }'Только этот метод запускает пересчёт корзины, без которого оплата отклоняется.
3. Привязать клиента (необязательно)
Заголовок раздела «3. Привязать клиента (необязательно)»curl -X PUT 'https://api-admin.billz.ai/v2/order-customer-new/ID_ПРОДАЖИ' \ -H 'Authorization: Bearer ТОКЕН' \ -H 'Content-Type: application/json' \ -H 'Billz-Response-Channel: HTTP' \ -d '{ "customer_id": "ID_КЛИЕНТА", "check_auth_code": false }'4. Оплатить
Заголовок раздела «4. Оплатить»Доступные способы оплаты возвращает
GET /v1/company-payment-type.
Чек можно закрыть несколькими платежами сразу.
curl -X POST 'https://api-admin.billz.ai/v2/order-payment/ID_ПРОДАЖИ' \ -H 'Authorization: Bearer ТОКЕН' \ -H 'Content-Type: application/json' \ -d '{ "payments": [ { "company_payment_type_id": "ID_ТИПА_ОПЛАТЫ", "paid_amount": 1000000, "returned_amount": 0 } ], "comment": "интернет-магазин" }'Ответ — {"order_type": "SALE", "should_print_cheque": true}.
Частые ошибки
Заголовок раздела «Частые ошибки»| Симптом | Обычная причина |
|---|---|
401 |
истёк access_token — обновление пары токенов |
403 |
маршрут не входит в список, разрешённый ключу — что может ключ |
200 с одним полем message |
забыт заголовок Billz-Response-Channel: HTTP |
400, data.error_code = 20084 |
товары добавлены не тем методом — см. шаг 2 |
400, код 20020 |
сумма оплат не сходится с итогом чека |
400, data.error_code = 20010 |
в магазине нет открытой кассы |
408 ровно через 10 минут |
результат не доставлен по HTTP-каналу; состояние продажи проверяется отдельным запросом |
Дальше: проверить результат в BILLZ.