Глоссарий

Термины, которые встречаются в справочнике API и в интерфейсе BILLZ.

Три слова, которые путают чаще всего

Термин	Что означает в BILLZ
Транзакция	Всё, что происходит на кассе: черновик, отложка, продажа, возврат. Это одна сущность на разных стадиях, в API — Order.
Импорт	То, что приносит товары в систему: приход на склад с позициями, поставщиком и ценами.
Заказ	Только заказ поставщику (закупка). Продажу заказом не называют — ни в интерфейсе, ни в документации.

В API методы транзакции называются /v2/order, /v2/order-product, /v2/order-payment, сущность в моделях — Order; в тексте документации это продажа или транзакция. Подробнее о развилке — в интернет-заказе.

Сущности

Сущность	Название	Что это
Product	Товар	Единица каталога. product_type_id — ровно три значения: товар, услуга, комплект (справочник GET /v2/product-type). Вариативность — отдельный флаг is_variative. Остатки и цены хранятся в разрезе магазинов (shop_measurement_values, shop_prices).
ProductVariation	Вариация товара	Отдельной сущности в API нет: вариация — тот же товар с заполненным parent_id, собственным баркодом и набором атрибутов. Её name собирается как «имя родителя / атрибут / атрибут», исходное имя — в base_name. При group_variations=true (только /v2/product-search-with-filters) вариации возвращаются вложенно в variations — усечённой моделью.
Category	Категория	Иерархический классификатор товаров, parent_id задаёт вложенность.
Brand	Бренд	Справочник производителей/марок товаров.
CustomField	Кастомное поле	Произвольная характеристика товара компании: custom_field_id + custom_field_value (плюс custom_field_name, custom_field_system_name, from_parent — признак наследования значения от родительского товара). Справочник самих полей — GET /v2/product-characteristic. Редактируется через PATCH /v2/product/{id}/patch-props.
Attribute	Атрибут	Свойство вариативного товара (размер, цвет). В product_field_filters — field_type: attribute, field_values — ID значений атрибута (для custom — сами значения).
MeasurementUnit	Единица измерения	Штука, кг, метр и т.п. Справочник компании (GET /v2/measurement-unit), поля precision (дробность), short_name, is_default, is_editable. Делимость товара задаётся его полями is_divisible и measurement_type (COUNTABLE / UNCOUNTABLE).
Shop	Магазин (точка)	Физическая точка продаж компании. Почти все складские и финансовые сущности привязаны к shop_id. Набор магазинов, видимых токену, ограничен правами пользователя: без права видеть остатки всех магазинов фильтр shop_ids молча сужается до доступных, а при пустом пересечении подставляются все магазины компании.
User	Пользователь	Сотрудник компании.
Supplier	Поставщик	Контрагент-поставщик товаров с реквизитами и наценкой по умолчанию.
Customer	Клиент (покупатель)	Покупатель компании: телефон, карты покупателя, программа лояльности, кешбэк, долги.
CustomerCard	Карта покупателя	Имя, код и флаг is_active; срока действия и привязки к программе лояльности нет. Код генерирует сервер (POST /v1/client-card, в теле только customer_id), имя собирается из последних пяти цифр кода. Своё значение передать нельзя. Ответ — {"id": "<ID клиента>", "card_code": "..."}: id здесь — ID клиента.
LoyaltyProgram	Программа лояльности	Правила начисления кешбэка и скидок. Привязана к компании и к клиенту; вторая карта не переводит клиента в другую программу.
Order	Транзакция (чек)	Центральная сущность кассы. Проходит стадии: черновик → (отложка) → оплаченная продажа → (возврат). Содержит позиции, скидки, оплаты и клиента. Заказом в BILLZ называется только заказ поставщику.
OrderItem	Позиция чека	Товар в чеке: количество, цена, скидка, сумма.
Payment	Оплата	Часть чека, оплаченная конкретным типом оплаты (company_payment_type_id); чек может быть оплачен несколькими способами.
GiftCard	Подарочная карта / сертификат	Предоплаченный платёжный инструмент, добавляется в продажу и списывается при оплате.
Promo	Акция	Скидочное правило. Типов семь (процент, фиксированная цена, 1+1, карусель, по сумме чека, по количеству позиций — на товар и на корзину), но в promo_price каталога попадают только PERCENTAGE и FIXED PRICE. Акция учитывается, только если она активна, действует по времени в таймзоне компании, не требует промокода, работает по розничной цене и назначена непосредственно на товары.
Import	Импорт (поставка)	Приход товара на склад: документ с позициями, поставщиком, ценами поставки и ценами продажи (retail_price, wholesale_price, min_price, max_price). До завершения поставки её количество лежит в отдельном остатке import_started_measurement_value.
SupplierOrder	Заказ поставщику	Документ закупки: создаётся, наполняется товарами, отправляется поставщику.
Transfer	Трансфер (перемещение)	Перемещение товаров между магазинами: создать → добавить товары → отправить → принять/отменить.
WriteOff	Списание	Списание товаров с причиной из справочника: создать → добавить товары → завершить/отклонить.
Stocktaking	Инвентаризация	Пересчёт остатков; поле type принимает пять значений — full, partial и служебные import, transfer, order, которые порождаются другими документами. Результат — излишки и недостачи.
CashBox	Касса	Кассовый ящик магазина; операции продажи привязаны к смене кассы.
PaymentType	Тип оплаты	Способ оплаты компании: наличные, UzCard, Humo, терминал и т.д.
Currency	Валюта	Валюта компании и история курсов (company-currency-rates).
ReportRow	Строка отчёта	Элемент постраничного отчёта (*-table).
ReportTotals	Итоги отчёта	Агрегаты по всей выборке (*-totals / *-report); считаются независимо от текущей страницы.
AsyncEnvelope	Конверт асинхронного ответа	Ответ event-методов при Billz-Response-Channel: HTTP: {session_id, company_id, id, status_code, error{code,message}, correlation_id, topic, data}. HTTP-код берётся из status_code, ID созданного объекта — из id. При таймауте (600 с, у экспорта отчётов в Excel — 100 с) приходит укороченное тело без status_code — см. коды ответов и ошибки.
Error	Ошибка	Тело ошибки. Единого формата в API нет: часть методов отвечает {"error": {"code", "message"}}, часть — {"code", "message", "error", "data"}, часть — числовыми кодами вида 20084. См. коды ошибок.

Термины, которые путают

Термины ниже звучат как синонимы, но означают разное.

Пара	Разница
Продажа и заказ	Покупка клиента — это Order, продажа (/v2/order). «Заказ» в BILLZ означает заказ поставщику — закупку (/v2/supplier-order). Интернет-заказ с сайта проводится продажей. См. интернет-заказ.
Черновик и проведённый документ	Созданный документ — черновик: он существует, у него есть ID, но на остатки он не влияет. Остатки двигает проведение — отдельный вызов и отдельное право.
Отложка и черновик	Черновик — незавершённая продажа в работе. Отложка — незавершённая продажа, намеренно приостановленная с указанием времени и комментария, чтобы вернуться к ней позже.
Списание и возврат	Списание убирает товар со склада по причине из справочника (брак, потеря). Возврат отменяет продажу и возвращает товар в остаток. Это разные процессы с разными правами.
id и order_number	id — UUID продажи, ключ для связи систем. order_number — короткий номер, видимый в интерфейсе.
Выручка и сумма чеков	Отчёты считают выручку с учётом возвратов, обменов и валютных пересчётов (net_gross_sales). Сумма total_price по чекам из поиска продаж даст другое число. См. выгрузку продаж.
Право на чтение и право на запись	Разные переключатели доступов: у списаний их пять — просмотр списка, просмотр себестоимости, создание, проведение, удаление. У ключа интеграции маршруты заданы фиксированным списком; переключатели роли меняют содержимое ответа: права роли ключа.

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