amarix

Справочник API

Склад и остатки

Остатки хранятся по размерам, а не по товарам. Физический остаток — это то, что лежит на полке; доступный — физический минус резервы под неотгруженные заказы. Покупатель на витрине видит доступный, кладовщик работает с физическим, и путать их нельзя. Общее для всего раздела, кроме списка складов: раздел «Склад» может быть недоступен по тарифу — тогда любой из этих эндпоинтов ответит 403 {"error":"Раздел недоступен на вашем тарифе","section":"warehouse"}, а без определённого бренда в контексте — 400 {"error":"Бренд не определён"}. Это не повторяется в каждом эндпоинте отдельно.

GET/warehouses

Склады бренда

Список складов с пометкой, какой из них онлайн-склад и какой производственный.

Доступ:Ключ интеграцииСессия сотрудникаПраво:view_stock, manage_stock или manage_orders

Онлайн-склад — тот, чей остаток показывается покупателю на витрине. Именно с него списывается товар при отгрузке, если у заказа не указан другой.

Параметры запроса

ПараметрТипОбязателенОписание
includeDeactivatedtrue | 1нетПоказать выключенные склады. По умолчанию они скрыты.

Поля ответа

ПолеТипОписание
warehousesarrayСклады бренда.
onlineWarehouseIdint | nullСклад, остаток которого видит покупатель.
productionWarehouseIdint | nullСклад, на который приходует готовую продукцию производство.

Ошибки

КодОтвет сервераКогда возникаетЧто делать
403{"error":"Forbidden: Missing required permission"}Нет права на чтение склада.—
GET/warehouses/{id}/stock

Остатки склада

Остатки по каждому размеру: физический, зарезервированный и доступный.

Доступ:Ключ интеграцииСессия сотрудникаПраво:view_stock или manage_stock

Параметры пути

ПараметрТипОбязателенОписание
idnumberдаИдентификатор склада.

Параметры запроса

ПараметрТипОбязателенОписание
productIdnumberнетОставить только размеры этого товара.
brandIdnumberнетФильтр по бренду товара — актуально для ключей с доступом к нескольким брендам.

Поля ответа

ПолеТипОписание
idnumberИдентификатор строки остатка.
quantitynumberФизический остаток. Может быть отрицательным, если товар отгрузили в минус.
reservednumberСколько единиц закреплено за неотгруженными заказами.
availablenumberФизический минус резервы. Тоже может быть отрицательным.
createdAtstringКогда строка остатка появилась.
updatedAtstringКогда остаток последний раз меняли.
productSizeobjectРазмер и его товар.
productSize.productIdnumberТовар размера.
productSize.deletedAtstring | nullКогда размер удалили, если удалён.
productSize.product.slugstringАдресное имя товара.
productSize.product.pricenumberЦена товара.в копейках
productSize.product.imagesstring[]Картинки товара.
productSize.product.isDeletedbooleanТовар удалён.
ответ
[
  {
    "id": 5501,
    "warehouseId": 4,
    "productSizeId": 1923,
    "quantity": 12,
    "reserved": 3,
    "available": 9,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-09-02T09:00:00.000Z",
    "productSize": {
      "id": 1923,
      "size": "M",
      "productId": 341,
      "deletedAt": null,
      "product": {
        "id": 341,
        "name": "Футболка «Пример» чёрная",
        "slug": "futbolka-primer-chernaya",
        "price": 199000,
        "images": ["https://cdn.amarix.ru/products/341/1.jpg"],
        "isDeleted": false
      }
    }
  }
]

Ошибки

КодОтвет сервераКогда возникаетЧто делать
400{"error":"Некорректный id склада"}В пути не число.—
404{"error":"Склад не найден"}Формально задокументировано, но на практике почти никогда не возвращается — см. notes.—
403{"error":"Forbidden: Missing required permission"}Нет права на чтение склада.—
POST/warehouses/{id}/stock

Установить остаток

Записывает остаток по размерам. Это установка значения, а не прибавка.

Доступ:Ключ интеграцииСессия сотрудникаПраво:manage_stock

Передаётся итоговое количество, а не дельта. Режим physical означает, что вы сообщаете физическое наличие на полке, и платформа сама вычтет из него уже собранные, но не отгруженные заказы.

Параметры пути

ПараметрТипОбязателенОписание
idnumberдаИдентификатор склада.

Тело запроса

ПараметрТипОбязателенОписание
itemsarrayнетСписок из объектов с полями productSizeId/productVariantId и quantity. Обязателен, если не передаёте одну позицию плоско (см. ниже).
productSizeIdnumberнетАльтернатива items для одной позиции: id легаси-размера прямо в теле, без массива.
productVariantIdnumberнетТо же самое для товара на системе атрибутов (без легаси-размера) — вариант вместо productSizeId, плоско или внутри items[].
quantitynumberнетКоличество для той же плоской формы — вместе с productSizeId/productVariantId.
modestringнетphysical — вы сообщаете наличие на полке; без него значение записывается как есть и не опускается ниже нуля.physical
curl -s -X POST "https://api.amarix.ru/warehouses/4/stock" \
  -H "Authorization: Bearer $AMARIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "mode": "physical",
        "items": [
          { "productSizeId": 1923, "quantity": 12 },
          { "productSizeId": 1924, "quantity": 0 }
        ]
      }'
ответ
{
  "ok": true,
  "mode": "physical",
  "updated": 2,
  "results": [
    { "warehouseId": 4, "productSizeId": 1923, "previous": 10, "quantity": 12, "delta": 2, "physical": 12, "committed": 0 },
    { "warehouseId": 4, "productSizeId": 1924, "previous": 3, "quantity": 0, "delta": -3, "physical": 0, "committed": 0 }
  ]
}

Ошибки

КодОтвет сервераКогда возникаетЧто делать
400{"error":"Нет позиций для сохранения"}Пустой список позиций.—
400{"error":"Склад архивный или деактивирован"}Склад выключен.—
404{"error":"Склад не найден"}Склада нет или он чужого бренда.—
403{"error":"Forbidden: Missing permission manage_stock"}Нет права на изменение склада.—
GET/warehouses/audit

История движений

Журнал изменений остатков: кто, когда, на сколько и почему.

Доступ:Ключ интеграцииСессия сотрудникаПраво:view_stock или manage_stock

Основной инструмент разбора «куда делся товар». Каждая запись содержит знаковое изменение количества и причину.

Параметры запроса

ПараметрТипОбязателенОписание
takenumberнетпо умолчанию 50Сколько записей вернуть, не больше 200.
skipnumberнетпо умолчанию 0Сколько пропустить.
warehouseIdnumberнетТолько по этому складу.
productSizeIdnumberнетТолько по этому размеру.
orderIdnumberнетТолько движения, связанные с этим заказом.
productIdsstringнетТовары через запятую.
productIdnumberнетОдин товар — то же самое, что productIds с одним значением.
sizesstringнетРазмеры через запятую (M,L,XL).
actorUserIdnumberнетТолько движения, сделанные этим пользователем/ключом.
actionstringнетПричина движения.
qstringнетПоиск по названию товара.

Поля ответа

ПолеТипОписание
rowsarrayЗаписи журнала.
totalnumberВсего записей по фильтру.
quantityDeltanumberИзменение количества: со знаком, минус означает списание.
warehouse.idnumberСклад движения.
warehouse.namestringНазвание склада.
warehouse.slugstringАдресное имя склада.
warehouse.brandIdnumberБренд склада.
productSize.idnumberИдентификатор размера.
productSize.sizestringЗначение размера.
productSize.productIdnumberТовар размера.
productSize.product.idnumberИдентификатор товара.
productSize.product.namestringНазвание товара.
productSize.product.slugstringАдресное имя товара.
actor.idnumberКто сделал движение.
actor.emailstringПочта автора движения.
actor.firstNamestringИмя автора движения.
actor.lastNamestringФамилия автора движения.
order.idnumberСвязанный заказ, если движение из-за заказа.
order.orderNumberstringНомер связанного заказа.

Ошибки

КодОтвет сервераКогда возникаетЧто делать
403{"error":"Forbidden: Missing required permission"}Нет права на чтение склада.—
GET/warehouses/reservations

Резервы

Единицы товара, закреплённые за заказами, с признаком срока годности.

Доступ:Ключ интеграцииСессия сотрудникаПраво:view_stock или manage_stock

Резерв до оплаты живёт ограниченное время — по умолчанию тридцать минут — и снимается сам, если заказ не оплатили. После оплаты становится бессрочным и снимается только при отгрузке.

Параметры запроса

ПараметрТипОбязателенОписание
statusstringнетпо умолчанию activeКакие резервы показать.active · expired · released · all
searchstringнетПоиск по товару или номеру заказа.
limitnumberнетпо умолчанию 100От 1 до 500.
offsetnumberнетпо умолчанию 0Сколько пропустить.
ответ
{
  "rows": [
    {
      "id": 77,
      "quantity": 2,
      "createdAt": "2026-09-01T10:00:00.000Z",
      "expiresAt": "2026-09-01T10:30:00.000Z",
      "releasedAt": null,
      "releaseReason": null,
      "isExpired": false,
      "orderId": 501,
      "orderNumber": "CSH-000501",
      "orderStatus": "pending",
      "orderPaymentStatus": "PAID",
      "customer": "Иванов Иван",
      "productId": 123,
      "productName": "Футболка Basic",
      "size": "M",
      "stockQuantity": 12
    }
  ],
  "total": 1
}

Ошибки

КодОтвет сервераКогда возникаетЧто делать
403{"error":"Forbidden: Missing required permission"}Нет права на чтение склада.—
POST/warehouses/transfer

Перемещение между складами

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

Доступ:Ключ интеграцииСессия сотрудникаПраво:manage_stock

Тело запроса

ПараметрТипОбязателенОписание
fromWarehouseIdnumberдаОткуда.
toWarehouseIdnumberдаКуда.
linesarrayдаСтроки с productSizeId и quantity.
notestringнетКомментарий, который сохранится в истории.
ответ
{
  "id": 15,
  "fromWarehouseId": 3,
  "toWarehouseId": 4,
  "actorUserId": 12,
  "note": "Плановое перемещение",
  "createdAt": "2026-09-01T10:00:00.000Z"
}

Ошибки

КодОтвет сервераКогда возникаетЧто делать
400{"error":"Некорректные склады"}Склады не указаны или совпадают.—
400{"error":"Пустой список строк"}Нечего переносить.—
400{"error":"Недостаточно остатка sizeId=<N> на складе <ID>: есть <X>, нужно <Y>"}На складе-источнике не хватает товара.Сообщение содержит фактический и требуемый остаток — по нему видно, чего не хватило.
400{"error":"Склад не найден или деактивирован"}code: WAREHOUSE_NOT_FOUNDОдин из складов не существует или деактивирован. Отдельная ошибка от «Некорректные склады» — та про совпадающие/отсутствующие id, эта про реально несуществующие.—
403{"error":"Forbidden: Missing permission manage_stock"}Нет права на изменение склада.—
POST/warehouses/reservations/release

Снять резерв вручную

Досрочно освобождает один или несколько резервов.

Доступ:Ключ интеграцииСессия сотрудникаПраво:manage_stock

Тело запроса

ПараметрТипОбязателенОписание
idsnumber[]нетИдентификаторы резервов из GET /warehouses/reservations. Если передан непустой ids, orderId игнорируется.
orderIdnumberнетСнять все резервы этого заказа разом — только если ids не передан.
ответ
{"ok":true,"released":2}

Ошибки

КодОтвет сервераКогда возникаетЧто делать
400{"error":"Не указаны резервы"}code: VALIDATIONНе передано ни ids, ни orderId.—
403{"error":"Нет доступа к резервам другого бренда"}code: FORBIDDENСреди резервов есть чужие для этого ключа/сессии.—
403{"error":"Forbidden: Missing permission manage_stock"}Нет права на изменение склада.—