Для 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 — личный ключ

Terminal
curl -g "https://vibecode.bitrix24.tech/v1/catalog-document-elements?filter[docId]=299" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal
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 — личный ключ

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-приложение

javascript
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

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

JSON
{
  "success": true,
  "data": [
    {
      "amount": 3,
      "docId": 299,
      "elementId": 6595,
      "id": 33,
      "purchasingPrice": 11000,
      "storeFrom": null,
      "storeTo": 11
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}

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

400 — фильтр по полю, которого нет в схеме позиции:

JSON
{
  "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.

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