amarix

Начало

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

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

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

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

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

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

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

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

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

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

Словарь

Брендbrand
Отдельный магазин внутри платформы: свои товары, склады, заказы, сотрудники и домен. Данные брендов не пересекаются. У бренда есть короткий код латиницей — он встречается в полях siteSource и brand_code.
Витринаstorefront
Публичная часть бренда — сайт, на котором покупатель выбирает товар и оформляет заказ. У каждого бренда своя витрина на своём домене.
Товар и размерproduct, product size
Товар — карточка (название, описание, фотографии, цена). Размер — конкретная позиция внутри товара, у которой есть собственный остаток. Продаётся и списывается всегда размер, а не товар: в заказе и на складе фигурирует именно идентификатор размера.
Складwarehouse
Место хранения остатков. У бренда их может быть несколько. Один из складов назначен онлайн-складом — именно его остаток видит покупатель на витрине.
Остатокstock, quantity
Сколько единиц размера физически лежит на складе. Не путать с доступным остатком: доступный — это физический минус резервы.
Резервreservation
Единицы товара, закреплённые за конкретным заказом. Резерв ставится при оформлении и снимается при отгрузке. До оплаты резерв временный и истекает сам, чтобы брошенные корзины не морозили склад. После оплаты становится бессрочным.
Отгрузкаshipment
Момент, когда товар физически уезжает со склада. Именно в этот момент остаток уменьшается — не при оплате. Это ключевое правило платформы, из него следует поведение отмен и возвратов.
Статус заказаstatus
Стадия работы с заказом: ожидает, в обработке, отправлен, доставлен, отменён. Статус двигается вперёд; возврат назад из «отправлен» отдельно запрещён, для этого есть отмена отгрузки.
Статус оплатыpaymentStatus
Отдельная от статуса заказа шкала: создан, оплачен, не прошёл, ожидает менеджера. Заказ может быть оплачен и не отправлен, и наоборот.
Статус доставкиdeliveryStatus
Стадия по данным перевозчика. Приходит от службы доставки и обновляется автоматически.
Возврат и обменreturn, exchange
Возврат — покупатель отдаёт товар и получает деньги. Обмен — отдаёт один товар и получает другой; при обмене создаётся отдельный дочерний заказ. В обоих случаях товар встаёт на склад в момент приёмки, а не в момент оформления.
Производственная площадкаproduction facility
Цех или мастерская, которая шьёт товар. У площадки свой ключ доступа и свой бренд. Товары могут быть закреплены за конкретной площадкой.
Очередь на изготовлениеproduction queue
Расчётный список: какие размеры и в каком количестве нужно произвести. Считается на лету из остатков, порога и размера партии — в базе не хранится.
Порог и партияthreshold, batch size
Порог — остаток, ниже которого позиция попадает в очередь. Партия — сколько штук изготавливают за раз. Размер партии, равный нулю, означает, что позиция в очередь не попадает никогда.
Честный знакchestny_znak
Код маркировки размера для государственной системы прослеживаемости. Хранится у размера и отдаётся в производственном API.

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