Получить список остатков по складам по фильтру v 3.0 catalog.store.product.list
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Scope:
catalogКто может выполнять метод: пользователь с правом «Просмотр каталога товаров» или «Просмотр и выбор склада»
Метод относится к REST 3.0. Особенности вызова и формат ответа новой версии API описаны в обзоре REST 3.0.
Метод catalog.store.product.list возвращает остатки товаров на складах. Каждая запись показывает остаток одного товара на одном складе.
Чтобы узнать остатки товара на всех складах, отфильтруйте список по productId. Чтобы получить все товары склада, отфильтруйте по storeId.
Методы catalog.store.product.* только читают остатки. Изменить остатки можно документами складского учета — методами catalog.document.*. Например, проведенный документ прихода увеличивает остаток на складе, а документ списания уменьшает.
Параметры метода
Обязательные параметры отмечены *
|
Название |
Описание |
|
select |
Массив полей записи остатка, которые нужно вернуть в ответе. Доступные поля:
Идентификатор По умолчанию: все поля |
|
filter |
Фильтр списка в формате REST 3.0: массив условий вида Фильтровать можно по всем полям из параметра Поддерживаются операторы |
|
order |
Сортировка в формате Сортировать можно по всем полям из параметра Возможные значения направления:
|
|
pagination |
Параметры постраничной навигации. Описание структуры объекта |
Параметр pagination
|
Название |
Описание |
|
limit |
Количество записей на странице. Значения больше По умолчанию: |
|
page |
Номер страницы, начиная с |
|
offset |
Количество записей, которые нужно пропустить от начала списка. По умолчанию: |
Чтобы выгрузить все остатки, передайте в order значение {"id": "asc"}, а в каждом следующем запросе — условие фильтра ["id", ">", N], где N — последний id предыдущей страницы. Это лучше, чем наращивать offset: при большом offset база данных перебирает все пропущенные записи.
Примеры кода
Как использовать примеры в документации
Вызов нового API отличается добавлением параметра /api/ в запросе:
https://{адрес_установки}/rest/api/{id_пользователя}/{токен_вебхука}/catalog.store.product.list
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"select":["id","productId","storeId","amount","quantityReserved"],"filter":[["productId","=",6595],["amount",">",0]],"order":{"storeId":"asc"},"pagination":{"limit":10}}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/catalog.store.product.list
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"select":["id","productId","storeId","amount","quantityReserved"],"filter":[["productId","=",6595],["amount",">",0]],"order":{"storeId":"asc"},"pagination":{"limit":10},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/api/catalog.store.product.list
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
type StoreProductListResult = {
items: {
id: number
productId: number
storeId: number
amount: number
quantityReserved: number
}[]
}
try {
const response = await $b24.actions.v3.call.make<StoreProductListResult>({
method: 'catalog.store.product.list',
params: {
select: ['id', 'productId', 'storeId', 'amount', 'quantityReserved'],
filter: [
['productId', '=', 6595],
['amount', '>', 0],
],
order: {
storeId: 'asc',
},
pagination: {
limit: 10,
},
},
requestId: Text.getUuidRfc4122()
})
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
result.items.forEach(stock => console.info(stock.storeId, stock.amount))
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function listStoreProducts() {
try {
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v3.call.make({
method: 'catalog.store.product.list',
params: {
select: ['id', 'productId', 'storeId', 'amount', 'quantityReserved'],
filter: [
['productId', '=', 6595],
['amount', '>', 0],
],
order: {
storeId: 'asc',
},
pagination: {
limit: 10,
},
},
requestId: B24Js.Text.getUuidRfc4122()
})
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
result.items.forEach(stock => console.info(stock.storeId, stock.amount))
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', listStoreProducts)
</script>
У методов catalog.store.product.* REST 3.0 нет готовых оберток в b24pysdk, и SDK отправляет в REST 3.0 только методы из списка Config().api_v3_methods. Добавьте метод в этот список и вызовите его через call_method токена клиента с prefer_version=3.
from b24pysdk import Config
from b24pysdk.errors import BitrixSDKException
from b24pysdk.errors.v3 import BitrixAPIError
method = "catalog.store.product.list"
Config().configure(api_v3_methods=Config().api_v3_methods | {method})
bitrix_token = client.get_token()
try:
response = bitrix_token.call_method(
api_method=method,
params={
"select": ["id", "productId", "storeId", "amount", "quantityReserved"],
"filter": [
["productId", "=", 6595],
["amount", ">", 0],
],
"order": {
"storeId": "asc",
},
"pagination": {
"limit": 10,
},
},
prefer_version=3,
)
result = response["result"]
print(result)
except BitrixAPIError as error:
print(
"Ошибка Bitrix API",
f"code: {error.code}",
f"message: {error.error.message}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
print(f"Непредвиденная ошибка: {error}")
SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.
try {
$response = $b24Service
->core
->call(
'catalog.store.product.list',
[
'select' => ['id', 'productId', 'storeId', 'amount', 'quantityReserved'],
'filter' => [
['productId', '=', 6595],
['amount', '>', 0],
],
'order' => [
'storeId' => 'asc',
],
'pagination' => [
'limit' => 10,
],
]
);
$result = $response
->getResponseData()
->getResult();
print_r($result);
} catch (Throwable $e) {
echo $e->getMessage();
}
SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.
BX24.callMethod(
'catalog.store.product.list',
{
select: ['id', 'productId', 'storeId', 'amount', 'quantityReserved'],
filter: [
['productId', '=', 6595],
['amount', '>', 0],
],
order: {
storeId: 'asc',
},
pagination: {
limit: 10,
},
},
result => {
if (result.error())
console.error(result.error());
else
console.dir(result.data());
}
);
SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.
require_once('crest.php');
$result = CRest::call(
'catalog.store.product.list',
[
'select' => ['id', 'productId', 'storeId', 'amount', 'quantityReserved'],
'filter' => [
['productId', '=', 6595],
['amount', '>', 0],
],
'order' => [
'storeId' => 'asc',
],
'pagination' => [
'limit' => 10,
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "catalog.store.product.list", b24.Params{
"select": []string{"id", "productId", "storeId", "amount", "quantityReserved"},
"filter": []any{
[]any{"productId", "=", 6595},
[]any{"amount", ">", 0},
},
"order": b24.Params{
"storeId": "asc",
},
"pagination": b24.Params{
"limit": 10,
},
}, b24.WithIdempotent())
if err != nil {
return fmt.Errorf("catalog.store.product.list: %w", err)
}
var result struct {
Items []struct {
ID int `json:"id"`
ProductID int `json:"productId"`
StoreID int `json:"storeId"`
Amount float64 `json:"amount"`
QuantityReserved float64 `json:"quantityReserved"`
} `json:"items"`
}
if err := json.Unmarshal(res.Result, &result); err != nil {
return fmt.Errorf("разбор ответа: %w", err)
}
for _, stock := range result.Items {
fmt.Println(stock.StoreID, stock.Amount, stock.QuantityReserved)
}
Обработка ответа
HTTP-статус: 200
{
"result": {
"items": [
{
"id": 3,
"productId": 6595,
"storeId": 1,
"amount": 15,
"quantityReserved": 30
},
{
"id": 1,
"productId": 6595,
"storeId": 11,
"amount": 10,
"quantityReserved": 0
}
]
},
"time": {
"start": 1794922635,
"finish": 1794922635.044875,
"duration": 0.04487490653991699,
"processing": 0,
"date_start": "2026-11-17T16:37:15+03:00",
"date_finish": "2026-11-17T16:37:15+03:00",
"operating_reset_at": 1794922920,
"operating": 0.41770195960998535
}
}
Возвращаемые данные
|
Название |
Описание |
|
result |
Объект с данными ответа |
|
result.items |
Массив записей остатков на странице. Состав полей зависит от |
|
time |
Информация о времени выполнения запроса |
Общее количество записей метод не возвращает. Если в ответе меньше записей, чем limit, страница последняя.
Элемент items
|
Название |
Описание |
|
id |
Идентификатор записи остатка |
|
productId |
Идентификатор товара или вариации |
|
storeId |
Идентификатор склада |
|
amount |
Количество товара на складе |
|
quantityReserved |
Количество товара в резерве. Может быть больше |
Обработка ошибок
HTTP-статус: 400
{
"error": {
"code": "BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION",
"message": "Ошибка при валидации объекта запроса",
"validation": [
{
"message": "Filter OR groups are not supported"
}
]
}
}
|
Название |
Описание |
|
error.code |
Строковый код ошибки. Используйте для идентификации типа исключения |
|
error.message |
Текстовое описание ошибки |
|
error.validation |
Массив c деталями ошибки. Присутствует только в ошибках валидации данных |
|
error.validation[].field |
Название поля, в котором возникла ошибка валидации |
|
error.validation[].message |
Описание ошибки, связанной с указанным полем |
Возможные коды ошибок
Ошибки валидации запроса
Код ошибки: BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Filter OR groups are not supported |
Уберите из фильтра группу с логикой |
|
|
Filter NOT groups are not supported |
Уберите из фильтра отрицание. Используйте оператор |
Ошибка неизвестного поля
Код ошибки: BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Неизвестное поле |
Укажите только поля из описания элемента items |
Ошибка формата фильтра
Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Не удается распознать выражение фильтра |
Передайте |
Ошибка оператора фильтра
Код ошибки: BITRIX_REST_V3_EXCEPTION_UNKNOWNFILTEROPERATOREXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Неизвестный оператор фильтра |
Используйте операторы |
Ошибка сортировки
Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDORDEREXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Не удается распознать выражение сортировки |
Передайте направление |
Ошибка пагинации
Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDPAGINATIONEXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Не удается распознать параметр пагинации |
Передайте |
Ошибка доступа
Код ошибки: BITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Доступ запрещен |
У пользователя нет права «Просмотр каталога товаров» или «Просмотр и выбор склада» |
Статусы и коды системных ошибок
HTTP-статус: 4xx, 5xx
Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.
|
Статус |
Код |
Описание |
|
|
|
Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Превышен лимит на интенсивность запросов |
|
|
|
Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит |
|
|
|
В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука |
|
|
|
Методы вызываются только по протоколу HTTPS |
|
|
|
REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24 |
|
|
|
REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — |
|
|
|
Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом |
|
|
|
Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа |
|
|
|
Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на |
|
|
|
Срок действия access-токена истек |
|
|
|
Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям |
|
|
|
Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта |