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

Остатки и цены

Остаток и цена в BILLZ существуют только в разрезе магазина.

Метод GET /v2/products возвращает в каждом товаре два массива:

{
"shop_measurement_values": [
{ "shop_id": "...", "shop_name": "Nike Store", "active_measurement_value": 5 }
],
"shop_prices": [
{
"shop_id": "...",
"retail_price": 1000000,
"retail_currency": "UZS",
"supply_price": 600000,
"promo_price": 500000,
"promos": [
{ "id": "...", "name": "discount 50%", "discount_type": "PERCENTAGE", "discount_value": 50 }
]
}
]
}

active_measurement_value — доступный к продаже остаток в точке, за вычетом отложек; для витрины используется он.

Полный остаток раскладывается так:

Мера Что входит
активный доступное к продаже
неактивный товар в пути между магазинами плюс отложки
полный активный + неактивный

В /v2/products разбивки нет — только active_measurement_value. Подробные меры видны в /v2/product-search-with-filters: total_in_transfer_measurement_value, total_sold_measurement_value, total_written_off_measurement_value, total_imported_measurement_value, total_transfered_measurement_value, total_transfer_arrived_measurement_value, import_started_measurement_value, а также is_small_left и small_left_measurement_value.

Возвраты отдельным числом по товару не выгружаются.

promo_price учитывается только при заполненном promos.

Как считается: PERCENTAGE → retail_price − retail_price × discount_value / 100; FIXED PRICE → discount_value как есть. Если акций на товар в этом магазине несколько, берётся минимальная цена, и в promos приходит только победившая акция. Акции остальных типов (1+1, карусель, по сумме чека, по количеству позиций) promo_price не формируют.

supply_price придёт нулём, а supply_currency — пустой строкой, если у роли ключа нет права видеть себестоимость; по умолчанию оно снято — см. права роли ключа.

Стратегия Когда подходит
Сумма остатков по всем магазинам один склад отгрузки, магазины — витрины
Остаток одного «интернет-магазина» есть выделенная точка под онлайн-заказы
Максимум по точкам + самовывоз покупатель выбирает магазин при оформлении

Цена берётся из той же точки, по которой считается остаток.

Изменение остатка на каждой продаже попадает в дельту GET /v2/products.

Общий лимит — 2 запроса в секунду; при превышении — 429.

Остаток единичных позиций перепроверяется в момент оформления заказа.

Резервирование в BILLZ — это отложка: active_measurement_value уменьшается на количество в отложке и возвращается при её снятии.

Как это делается:

  1. создать продажу — POST /v2/order с телом {shop_id, cashbox_id};
  2. добавить позиции — только POST /v2/order-product/:order_id (см. интернет-заказ);
  3. отложить чек — POST /v2/order/create_postpone, в теле order_id и time; поле time обязательно и строгого формата.

Вернуть отложку в работу — POST /v2/order/return-postpone, дальше чек оплачивается как обычная продажа. Подробнее о стадиях чека — в жизненном цикле продажи.