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

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

GET /v1/warehouses/:id/stock

Возвращает остатки товаров на складе — по строке на каждый товар, который числится на этом складе. Только для чтения: изменить количество через этот эндпоинт нельзя.

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

Параметр Тип Описание
Параметрid Типnumber ОписаниеИдентификатор склада из списка складов

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

Параметр Тип По умолч. Описание
ПараметрproductId Типnumber По умолч.— ОписаниеИдентификатор товара из списка товаров каталога, каноническое положительное безопасное целое. Отбирает строки этого товара только на указанном складе
Параметрlimit Типnumber По умолч.50 ОписаниеКоличество строк (до 5000). При limit > 50 ответ автоматически собирается из нескольких страниц Битрикс24
Параметрoffset Типnumber По умолч.0 ОписаниеСмещение от начала выборки, построчное: offset=1 начинает со второй строки. Битрикс24 сдвигает выборку только на целую страницу по 50, поэтому Вайбкод запрашивает накрывающую страницу и отсекает лишние строки с начала. Если запрошенное окно не покрывается одной страницей, data придёт пустым при hasMore: true, а в meta.warnings — OFFSET_BEYOND_FETCHED_PAGE: увеличьте limit

Примеры

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

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

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/warehouses/1/stock?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/1/stock?productId=200', {
  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/1/stock?productId=200', {
  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[].id Типnumber ОписаниеИдентификатор строки остатка. По нему одна строка читается методом Строка остатка склада
Полеdata[].productId Типnumber ОписаниеИдентификатор товара — см. список товаров каталога
Полеdata[].storeId Типnumber ОписаниеИдентификатор склада из списка складов, совпадает с id в пути
Полеdata[].amount Типnumber ОписаниеКоличество на складе. Может быть null — трактуйте как 0
Полеdata[].quantityReserved Типnumber ОписаниеЗарезервированное количество. Может быть null — трактуйте как 0
Полеmeta.total Типnumber ОписаниеКоличество строк остатков на складе
Полеmeta.hasMore Типboolean ОписаниеЕсть ли строки за пределами текущей страницы (offset + длина data < total). Если true — увеличьте limit (до 5000) либо сдвиньте offset

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 3,
      "productId": 200,
      "storeId": 1,
      "amount": 15,
      "quantityReserved": 30
    },
    {
      "id": 5,
      "productId": 201,
      "storeId": 1,
      "amount": 54,
      "quantityReserved": null
    },
    {
      "id": 9,
      "productId": 202,
      "storeId": 1,
      "amount": null,
      "quantityReserved": null
    }
  ],
  "meta": {
    "total": 3,
    "hasMore": false
  }
}

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

400 — некорректный id склада:

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

Ошибки

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

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

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

Пустой склад. Если на складе нет товаров с остатками, data — пустой массив, meta.total — 0.

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