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

3. Первая продажа

Продажа в BILLZ собирается по шагам: создать продажу → добавить позиции → (привязать клиента, применить скидки) → оплатить.

Окно терминала
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.

Окно терминала
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
}'

Только этот метод запускает пересчёт корзины, без которого оплата отклоняется.

Окно терминала
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 }'

Доступные способы оплаты возвращает 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.