NNimbusДокументация
СтатусПоддержка
Справочник API / Товары и остатки

Товары и остатки

Товар создаётся один раз и опознаётся по вашему sku. Остаток и цена меняются отдельно и дёшево: пакетом до 1000 позиций.

Объект товара

  • skuстрокаВаш код позиции. Чувствителен к регистру, до 64 символов.
  • nameстрокаНазвание для витрины, до 200 символов.
  • priceцелоеЦена в копейках.
  • old_priceцелое или nullЦена до скидки. Витрина показывает её зачёркнутой.
  • stockцелоеОстаток на полке, как его прислали вы.
  • reservedцелоеРезерв под оплаченные и не собранные заказы. Считаем мы.
  • availableцелоеДоступно к заказу: stock - reserved.
  • activeлогическоеПоказывать ли позицию на витринах.
  • updated_atстрокаВремя последнего изменения, UTC.
Объект
{
  "sku": "TRM-1579",
  "name": "Термокружка 400 мл",
  "price": 129000,
  "old_price": null,
  "stock": 17,
  "reserved": 2,
  "available": 15,
  "active": true,
  "category": "trm",
  "updated_at": "2026-08-11T09:41:22Z"
}

Создать или обновить товар

Если позиции с таким sku нет, она создаётся; если есть - обновляются только переданные поля.

Параметры

  • skuстрокаобязательныйКод позиции в вашем учёте.
  • nameстрокаОбязателен при создании, при обновлении можно не передавать.
  • priceцелоеЦена в копейках, больше нуля.
  • old_priceцелоеЦена до скидки, больше price.
  • categoryстрокаКод категории витрины. От неё зависит минимальная цена.
  • activeлогическоеПо умолчанию true.

Возвращает

Объект товара целиком. Код ответа 201 при создании и 200 при обновлении.

POST/v1/products
curl "$API/v1/products" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sku": "TRM-1579", "name": "Термокружка 400 мл", "price": 129000 }'
const item = await api.products.upsert({
  sku: 'TRM-1579',
  name: 'Термокружка 400 мл',
  price: 129000,
});
item = api.products.upsert(
    sku="TRM-1579",
    name="Термокружка 400 мл",
    price=129000,
)
Ответ 201
{
  "sku": "TRM-1579",
  "name": "Термокружка 400 мл",
  "price": 129000,
  "old_price": null,
  "stock": 17,
  "reserved": 2,
  "available": 15,
  "active": true,
  "category": "trm",
  "updated_at": "2026-08-11T09:41:22Z"
}

Получить товар

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

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

  • skuстрокаобязательныйКод позиции. Регистр важен: trm-1579 и TRM-1579 - разные товары.

Возвращает

Объект товара или 404 с кодом sku_not_found.

GET/v1/products/{sku}
curl
curl "$API/v1/products/TRM-1579" \
  -H "Authorization: Bearer $NIMBUS_KEY"

Список товаров

Товары контура страницами по курсору, новые изменения последними.

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

  • limitцелоеОт 1 до 200, по умолчанию 50.
  • cursorстрокаКурсор из предыдущего ответа.
  • updated_sinceстрокаТолько изменённые после этого момента, ISO 8601.
  • activeлогическоеТолько показанные или только скрытые.
  • categoryстрокаКод категории витрины.

Возвращает

Объект со списком data, курсором и признаком has_more.

GET/v1/products
Ответ
{
  "data": [ { "sku": "TRM-1579", ... }, { "sku": "TRM-1583", ... } ],
  "cursor": "b3M6MTIwNA",
  "has_more": true
}

Удалить товар

Убирает позицию из каталога всех витрин. История заказов по ней сохраняется, а повторное создание с тем же sku начинает позицию с чистого листа.

Скрыть, а не удалятьЕсли товар временно не продаётся, отправьте "active": false: удалённая позиция теряет историю цен.
DELETE/v1/products/{sku}
Ответ
{ "sku": "TRM-2210", "deleted": true }

Остатки пакетом

До 1000 позиций в одном запросе, применяется целиком: если хоть одна строка не прошла проверку, не применится ни одна.

Параметры

  • itemsмассивобязательныйПозиции пакета, от 1 до 1000.
  • items[].skuстрокаобязательныйКод позиции.
  • items[].stockцелоеНовый остаток на полке, не меньше нуля.
  • items[].priceцелоеНовая цена в копейках.
  • items[].activeлогическоеПоказать или скрыть позицию.

Возвращает

Число применённых строк и список отвергнутых с номером строки и кодом причины.

POST/v1/stock/batch
curl "$API/v1/stock/batch" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d @batch.json
const res = await api.stock.batch([
  { sku: 'TRM-1579', stock: 14 },
  { sku: 'TRM-1583', stock: 0 },
]);
console.log(res.applied);  // 2
res = api.stock.batch([
    {"sku": "TRM-1579", "stock": 14},
    {"sku": "TRM-1583", "stock": 0},
])
print(res.applied)  # 2
Ответ
{ "applied": 2, "rejected": [] }

История остатка

Изменения остатка позиции за период, до 90 дней назад. Удобно для сверки, когда витрина и учёт разошлись.

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

  • skuстрокаобязательныйКод позиции.
  • fromстрокаНачало периода, ISO 8601. По умолчанию сутки назад.
  • toстрокаКонец периода. По умолчанию сейчас.
GET/v1/stock/history
Ответ
{
  "sku": "TRM-1579",
  "data": [
    { "at": "2026-08-23T21:00:04Z", "stock": 17, "source": "batch" },
    { "at": "2026-08-24T10:12:51Z", "stock": 15, "source": "order ORD-25161" }
  ]
}
← ВведениеЗаказы и события →