Для AI-агентов: markdown этой страницы — /docs-content/entities/warehouses/stock-totals.md индекс документации — /llms.txt

Сводные остатки по товарам

GET /v1/warehouses/stock/totals

Складывает остатки каждого товара по всем складам портала. Для товара возвращает суммарное количество, суммарный резерв и список складов, где товар представлен. Только для чтения.

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

Параметр Тип По умолч. Описание
ПараметрproductId Типnumber По умолч.— ОписаниеСвести остатки только по одному товару
Параметрlimit Типnumber По умолч.— ОписаниеСколько товаров вернуть в ответе
Параметрoffset Типnumber По умолч.0 ОписаниеСмещение по списку товаров

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/warehouses/stock/totals?productId=200" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/warehouses/stock/totals?productId=200" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/warehouses/stock/totals', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/warehouses/stock/totals', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типarray ОписаниеСводка по товарам
Полеdata[].productId Типnumber ОписаниеИдентификатор товара — см. Товары каталога
Полеdata[].amount Типnumber ОписаниеСуммарное количество товара по всем складам
Полеdata[].quantityReserved Типnumber ОписаниеСуммарный резерв товара по всем складам
Полеdata[].storeIds Типarray ОписаниеИдентификаторы складов, где товар представлен
Полеmeta.total Типnumber ОписаниеОбщее количество товаров в сводке до применения limit и offset
Полеmeta.rawTotal Типnumber ОписаниеКоличество исходных строк остатков в выборке Битрикс24. При truncated равном true превышает число строк, вошедших в свод
Полеmeta.truncated Типboolean Описаниеtrue, если исходных строк остатков больше 5000 и часть не вошла в свод

Пример ответа

JSON 
{
  "success": true,
  "data": [
    {
      "productId": 200,
      "amount": 25,
      "quantityReserved": 30,
      "storeIds": [1, 2, 5]
    }
  ],
  "meta": {
    "total": 1,
    "truncated": false,
    "rawTotal": 3
  }
}

Пример ответа при ошибке

400 — некорректный productId:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "productId must be a positive integer in canonical form — digits only, no leading zero, sign, fraction or exponent"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеproductId или limit не каноническое положительное целое (100.9, 100abc, 1e2, 0100 отвергаются), либо offset отрицательный
HTTP400 КодUNSUPPORTED_FILTER Описаниепередан параметр filter[] — эта ручка его не поддерживает и не пересылает в Битрикс24
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа catalog
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен

Полный список общих ошибок API — Ошибки.

Известные особенности

Суммирование по товару. Количество и резерв одного товара суммируются по всем складам, где он представлен. Список таких складов — в storeIds. Если на отдельном складе количество не задано, при суммировании оно считается нулём.

Ограничение свода. Свод считается по первым 5000 строкам остатков. Если строк больше, meta.truncated равно true, и свод получается неполным. В этом случае сузьте выборку параметром productId.

Смотрите также