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

Модель данных

Почти всё в BILLZ существует в разрезе магазина.

Единица каталога. product_type_id принимает одно из трёх значений: товар, услуга или комплект; справочник — GET /v2/product-type. Вариативность — отдельный флаг is_variative; и вариативный товар, и его вариации имеют тип «товар».

Поле Смысл
id UUID товара
name, sku, barcode название, артикул, штрихкод
is_variative признак товара с вариациями
parent_id ссылка на родителя у вариации; у самостоятельного товара — пустая строка
product_type_id товар / услуга / комплект (ровно три значения)
categories[], brand_id классификация
custom_fields[] произвольные характеристики компании: custom_field_id, custom_field_name, custom_field_system_name, custom_field_value, from_parent (значение унаследовано от родителя)
product_attributes[] атрибуты вариации: attribute_id, attribute_name, attribute_value_id, attribute_value

Дочерний товар со своим штрихкодом и набором атрибутов. Ссылается на родителя через parent_id. Имя вариации собирается как «имя родителя / значение атрибута / значение атрибута»; исходное имя родителя лежит отдельно в base_name.

Группировка group_variations=true поддерживается только в POST /v2/product-search-with-filters: там в списке остаётся родитель, а вариации приходят вложенно в variations. У GET /v2/products такого параметра нет: вариации приходят плоским списком.

Атрибут и кастомное поле — разные сущности, хотя в фильтрах используется общий параметр product_field_filters с разделением по field_type: attribute или custom.

Физическая точка продаж. К shop_id привязаны остатки, цены, кассы, продажи и складские процессы. Пользователь работает в контексте «текущего магазина».

// GET /v2/products
{
"shop_measurement_values": [
{ "shop_id": "...", "shop_name": "Nike Store", "active_measurement_value": 5 }
],
"shop_prices": [
{ "shop_id": "...", "shop_name": "Nike Store",
"retail_price": 1000000, "retail_currency": "UZS",
"supply_price": 600000, "supply_currency": "UZS",
"promo_price": 500000, "promos": [ ] }
]
}

Структура зависит от метода: в POST /v2/product-search-with-filters вместо active_measurement_value — total_measurement_value, total_active_measurement_value, total_inactive_measurement_value, total_in_transfer_measurement_value и другие.

promo_price учитывается только при непустом promos; в promos приходит только акция с минимальной ценой.

В GET /v2/products поля supply_price и supply_currency обнуляются (0 и ""), если у роли ключа нет права видеть себестоимость. От реальной нулевой себестоимости по ответу это не отличается.

Покупатель компании: телефон, карты, кешбэк, долги. В API соседствуют два набора методов — client (создание и поиск, в том числе по chat_id для ботов) и customer (детали, баланс). Модели разные.

Ключу интеграции доступны: POST /v1/client, GET /v1/client, PUT /v1/client/:id, POST /v1/client-card, GET /v1/client-by-chat-id, GET /v1/customer/:id, PATCH /v1/customer/set-balance/:id.

Полный перечень структур с описанием каждого поля — в справочнике.