Для AI-агентов: markdown этой страницы — /docs-content/entities/catalog-document-elements/list.md индекс документации — /llms.txt
Список позиций складских документов
GET /v1/catalog-document-elements
Возвращает позиции складских документов с фильтрацией, сортировкой и постраничной выдачей.
Параметры
| Параметр | Тип | По умолч. | Описание |
|---|---|---|---|
Параметрfilter (query) |
Типobject | По умолч.— | ОписаниеФильтрация по полям GET /v1/catalog-document-elements/fields.Синтаксис фильтрации. Пример: ?filter[docId]=299 — позиции одного документа, docId берётся из GET /v1/catalog-documents |
Параметрselect (query) |
Типstring | По умолч.— | ОписаниеПоля в ответе через запятую: ?select=id,elementId,amount. Поле id возвращается всегда. Имена — из GET /v1/catalog-document-elements/fields |
Параметрorder (query) |
Типobject | По умолч.— | ОписаниеСортировка: ?order[amount]=desc. Короткая форма — ?sort=-amount, минус означает убывание. Поля — те же, что в фильтре |
Параметрlimit (query) |
Типnumber | По умолч.50 |
ОписаниеКоличество записей, до 5000 |
Параметрoffset (query) |
Типnumber | По умолч.0 |
ОписаниеСколько записей пропустить от начала выборки |
ПараметрwithTotal (query) |
Типstring | По умолч.— | Описаниеtrue или false. При точном false ключ meta.total не возвращается, но Битрикс24 всё равно подсчитывает позиции: параметр не ускоряет запрос. Без параметра или при true сохраняется прежний режим с подсчётом |
Пагинация. При limit больше 50 Вайбкод собирает ответ из нескольких страниц автоматически. Следующую страницу запрашивайте с offset, пока meta.hasMore равно true.
Примеры
curl — личный ключ
curl -g "https://vibecode.bitrix24.tech/v1/catalog-document-elements?filter[docId]=299" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl -g "https://vibecode.bitrix24.tech/v1/catalog-document-elements?filter[docId]=299" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-document-elements?filter[docId]=299', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
},
})
const { success, data, meta } = await res.json()
console.log(`Позиций в документе: ${meta.total}`)
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-document-elements?filter[docId]=299', {
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[].docId |
Типnumber | ОписаниеИдентификатор складского документа. Документ — GET /v1/catalog-documents/:id |
Полеdata[].elementId |
Типnumber | ОписаниеИдентификатор товара. Товар — GET /v1/catalog-products/:id |
Полеdata[].amount |
Типnumber | null | ОписаниеКоличество товара, null — не задано |
Полеdata[].purchasingPrice |
Типnumber | null | ОписаниеЗакупочная цена за единицу, null — не задана |
Полеdata[].storeFrom |
Типnumber | null | ОписаниеСклад отправления, null — склад не задан. Склады — GET /v1/warehouses |
Полеdata[].storeTo |
Типnumber | null | ОписаниеСклад получения, null — склад не задан. Склады — GET /v1/warehouses |
Полеmeta.total |
Типnumber | ОписаниеОбщее количество позиций, подходящих под фильтр. Необязательное поле: при withTotal=false отсутствует |
Полеmeta.hasMore |
Типboolean | ОписаниеЕсть ли ещё позиции за пределами limit |
Полеmeta.warnings |
Типarray | ОписаниеПредупреждения о запросе, каждое с полями code, message, field. Приходит, когда в select есть имя, которого нет в схеме, — код UNKNOWN_SELECT_FIELD |
Пример ответа
{
"success": true,
"data": [
{
"amount": 3,
"docId": 299,
"elementId": 6595,
"id": 33,
"purchasingPrice": 11000,
"storeFrom": null,
"storeTo": 11
}
],
"meta": {
"total": 1,
"hasMore": false
}
}
Пример ответа при ошибке
400 — фильтр по полю, которого нет в схеме позиции:
{
"success": false,
"error": {
"code": "UNKNOWN_FILTER_FIELD",
"message": "Unknown filter field 'bogus' for entity 'catalog-document-elements'. Available: id, docId, elementId, amount, purchasingPrice, storeFrom, storeTo"
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодUNKNOWN_FILTER_FIELD |
ОписаниеФильтр по полю, которого нет в схеме. Сообщение перечисляет допустимые поля |
| HTTP400 | КодUNKNOWN_SORT_FIELD |
ОписаниеСортировка по полю, которого нет в схеме. Сообщение перечисляет допустимые поля |
| HTTP400 | КодINVALID_FILTER |
ОписаниеЗначение filter не распознано: передайте его в скобочной записи ?filter[docId]=299 или JSON-объектом ?filter={"docId":299}. Обе записи в одном запросе тоже отклоняются |
| HTTP400 | КодINVALID_FILTER_OPERATOR |
ОписаниеВ фильтре передан неподдерживаемый оператор. Сообщение перечисляет поддерживаемые |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP401 | КодINVALID_API_KEY |
ОписаниеПереданный API-ключ не найден |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеAPI-ключ не имеет настроенных токенов |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеAPI-ключ не имеет скоупа catalog |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After |
Полный список общих ошибок API — Ошибки.
Известные особенности
Без фильтра — позиции всех документов. Запрос без filter[docId] возвращает позиции всех складских документов портала в одном списке. Чтобы отличить строки разных документов, смотрите на docId каждой позиции.
Несуществующий документ — пустой список. Фильтр по docId документа, которого нет или который удалён, возвращает 200 с пустым data, а не ошибку. Без withTotal=false значение meta.total равно 0; при withTotal=false ключ отсутствует. Проверить, что документ существует, можно через GET /v1/catalog-documents/:id.