Соглашения

Деньги#

Все суммы — целые числа в копейках. 450000 означает 4500 рублей.

Даты и время#

Даты приходят в формате ISO 8601 в зоне UTC. Фильтры по дате понимают как полную отметку времени, так и просто день.

Важная тонкость: если в фильтре «по дату» указан день, платформа дотягивает его до конца дня по московскому времени. Сотрудники работают по Москве, и фильтр сделан под них, а не под UTC.

new Intl.DateTimeFormat("ru-RU", {
  timeZone: "Europe/Moscow",
  dateStyle: "short",
  timeStyle: "short",
}).format(new Date(заказ.createdAt));

Постраничная выдача#

Там, где она есть, используются limit и offset, а у истории движений — take и skip. Единого стиля нет, смотрите описание конкретного эндпоинта.

Общее число записей отдаётся не всегда. Универсальный признак конца выборки: пришло меньше записей, чем запрашивали.

Фильтры#

• Многие фильтры принимают несколько значений через запятую — например, сразу несколько статусов.
• Значение all в фильтре означает «не фильтровать».
• Неизвестное значение сортировки не вызывает ошибку: платформа молча берёт порядок по умолчанию. Опечатка в названии сортировки останется незамеченной.
• Поиск по телефону работает по цифрам: написание со скобками и дефисами значения не имеет.

Чего в ответах нет#

Набор полей зависит от прав ключа. Служебные поля — физический остаток, коды маркировки, настройки производства — приходят только при наличии прав на товары. Если ожидаемого поля нет, дело чаще всего в правах, а не в ошибке.

Ошибки#

Тело ошибки — объект с полем error, текст на русском. Ветвитесь по коду ответа, а текст пишите в лог целиком. Полный каталог — в разделе «Ошибки».

Повторные запросы#

Общей защиты от повторов в API нет. Каждый эндпоинт ведёт себя по-своему, и это описано в его разделе. Два крайних случая стоит запомнить:

• Приём заказа из внешней системы различает повторы по номеру — повторить безопасно.
• Приёмка продукции с производства повторы не различает — каждый запрос добавляет к остатку.