amarix

Начало

Термины и понятия

Словарь, на котором говорит платформа. Названия полей в API повторяют эти понятия, поэтому десять минут здесь сэкономят часы в отладке.

Деньги — в копейках

Все денежные значения в API — целые числа в копейках. Сумма 450000 — это 4500 рублей, а не 450 тысяч. Так сделано намеренно: дробные числа в деньгах рано или поздно дают расхождение в копейку, а на масштабе тысяч заказов эта копейка находится в отчётах и портит сверку.

преобразование
// из ответа API — в rubles для показа человеку
const rubles = (kopecks: number) => (kopecks / 100).toFixed(2);

// из введённого человеком — в kopecks для отправки
const kopecks = (rubles: string) => Math.round(parseFloat(rubles) * 100);

Время и часовой пояс

Даты приходят в формате ISO 8601 в зоне UTC. Сотрудники работают по московскому времени, поэтому при показе дат переводите их в Europe/Moscow, иначе заказ, оформленный в 2 часа ночи по Москве, будет выглядеть сделанным вчера.

Идентификаторы

У заказа present три разных способа на него сослаться, и они не взаимозаменяемы. Идентификатор — число, для запросов к API. Номер заказа — то, что видит customer и staffUser; он может содержать буквы и префикс бренда. Хеш — случайная строка для публичной ссылки отслеживания, по ней заказ открывается без авторизации.

Словарь

Брендbrand
Отдельный магазин внутри платформы: свои товары, склады, заказы, сотрудники и домен. Данные брендов не пересекаются. У бренда есть короткий код латиницей — он встречается в полях siteSource и brand_code.
Витринаstorefront
Публичная часть бренда — сайт, на котором покупатель выбирает товар и оформляет заказ. У каждого бренда своя витрина на своём домене.
Товар и размерproduct, product size
Товар — карточка (название, описание, фотографии, цена). Размер — легаси-модель: единственная ось выбора (S/M/L/XL, ONESIZE…) со своим остатком. Работает и сейчас, но с 16.09.2026 это частный случай более общей системы атрибутов — см. «Атрибут и вариант» ниже. Продаётся и списывается всегда конкретная позиция (размер либо вариант), а не товар целиком.
Атрибут и вариантattribute, product variant
Обобщение размера на произвольное число осей выбора. Атрибут — параметр товара (Размер, Цвет, Принт…) со своим набором значений. Вариант — конкретная комбинация значений одного или нескольких атрибутов (например Цвет=Жёлтый + Размер=M) со своим собственным остатком, доступным для продажи независимо от остальных вариантов. Товар с одним атрибутом «Размер» ведёт себя так же, как раньше вело себя поле размера — это не замена, а расширение: старые интеграции, читающие sizeId/size, продолжают работать, а variantId — рекомендуемый способ адресации для новых. В ответах API атрибуты и варианты приходят полями attributes[] и variants[] у товара.
Складwarehouse
Место хранения остатков. У бренда их может быть несколько. Один из складов назначен онлайн-складом — именно его остаток видит покупатель на витрине.
Остатокstock, quantity
Сколько единиц размера физически лежит на складе. Не путать с доступным остатком: доступный — это физический минус резервы.
Резервreservation
Единицы товара, закреплённые за конкретным заказом. Резерв ставится при оформлении и снимается при отгрузке. До оплаты резерв временный и истекает сам, чтобы брошенные корзины не морозили склад. После оплаты становится бессрочным.
Отгрузкаshipment
Момент, когда товар физически уезжает со склада. Остаток уменьшается именно тогда, а не при оплате. Из этого правила следует всё поведение отмен и возвратов.
Статус заказаstatus
Стадия работы с заказом: ожидает, в обработке, отправлен, доставлен, отменён. Статус двигается вперёд; возврат назад из «отправлен» отдельно запрещён, для этого есть отмена отгрузки.
Статус оплатыpaymentStatus
Отдельная от статуса заказа шкала: создан, оплачен, не прошёл, ожидает менеджера. Заказ может быть оплачен и не отправлен, и наоборот.
Статус доставкиdeliveryStatus
Стадия по данным перевозчика. Приходит от службы доставки и обновляется автоматически.
Возврат и обменreturn, exchange
Возврат — покупатель отдаёт товар и получает деньги. Обмен — отдаёт один товар и получает другой; при обмене создаётся отдельный дочерний заказ. В обоих случаях товар встаёт на склад в момент приёмки, а не в момент оформления.
Производственная площадкаproduction facility
Цех или мастерская, которая шьёт товар. У площадки свой ключ доступа и свой бренд. Товары могут быть закреплены за конкретной площадкой.
Очередь на изготовлениеproduction queue
Расчётный список: какие варианты (размеры или комбинации атрибутов) и в каком количестве нужно произвести. Считается на лету из остатков, порога и размера партии — в базе не хранится.
Порог и партияthreshold, batch size
Порог — остаток, ниже которого позиция попадает в очередь. Партия — сколько штук изготавливают за раз. Размер партии, равный нулю, означает, что позиция в очередь не попадает никогда.
Честный знакchestny_znak
Код маркировки для государственной системы прослеживаемости. Хранится у легаси-размера и у варианта (своё поле на каждом) и отдаётся в производственном API и API отгрузки независимо от того, заведён товар на размерах или на атрибутах.

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