Модель данных
Почти всё в 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.
Полный перечень структур с описанием каждого поля — в справочнике.