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

Список позиций отгрузок

GET /v1/shipment-items

Возвращает список позиций отгрузок заказов интернет-магазина с поддержкой фильтрации, сортировки и автоматической пагинации.

Параметры

Параметр Тип По умолч. Описание
limit (query) number 50 Количество записей, от 1 до 5000. Значение больше 5000 приводится к 5000 без ошибки
offset (query) number 0 Пропустить N записей: offset=7 начинает выборку с 8-й записи
select (query) string — Выборка полей через запятую: ?select=id,orderDeliveryId,quantity. Неизвестное поле не вызывает ошибку: его нет в элементах data, а в meta.warnings приходит предупреждение UNKNOWN_SELECT_FIELD с именем поля в field
sort (query) string — Сортировка кратким синтаксисом: ?sort=-id, минус означает убывание
order (query) object — Сортировка: ?order[id]=desc
filter (query) object — Фильтрация по полям GET /v1/shipment-items/fields.
Синтаксис фильтрации. Пример: ?filter[orderDeliveryId]=1207
withTotal (query) string — Нужно ли количество записей в meta.total: true или false. Подробнее — Листание и количество записей

Пагинация. При limit > 50 Вайбкод собирает ответ из нескольких последовательных чтений по 50 записей и возвращает все записи одним ответом. Есть ли записи дальше, показывает meta.hasMore.

Примеры

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

Terminal 
curl -g "https://vibecode.bitrix24.tech/v1/shipment-items?filter[basketId]=1387" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl -g "https://vibecode.bitrix24.tech/v1/shipment-items?filter[basketId]=1387" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/shipment-items?filter[basketId]=1387', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
const total = data.reduce((sum, item) => sum + item.quantity, 0)
console.log(`Позиция корзины распределена по ${data.length} отгрузкам, всего ${total}`)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/shipment-items?filter[basketId]=1387', {
  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[].orderDeliveryId number ID отгрузки. Список: GET /v1/shipments
data[].basketId number ID позиции корзины. Список: GET /v1/basket-items
data[].quantity number Количество товара в отгрузке, бывает дробным
data[].reservedQuantity number Зарезервированное количество
data[].xmlId string Внешний код позиции
data[].dateInsert datetime Дата создания, ISO 8601
meta.total number Общее количество записей, соответствующих фильтру. Может не прийти — см. параметр withTotal
meta.hasMore boolean Есть ли ещё записи за пределами limit
meta.warnings array Предупреждения о параметрах запроса: code, message, field. Приходит, только если предупреждения есть
meta.pageErrorSample object Код и текст ошибки, из-за которой автоматическая пагинация остановилась раньше. data тогда содержит записи до места остановки

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

JSON 
{
  "success": true,
  "data": [
    {
      "basketId": 1387,
      "dateInsert": "2026-10-04T22:01:08.000Z",
      "id": 1347,
      "orderDeliveryId": 1195,
      "quantity": 0.25,
      "reservedQuantity": 0,
      "xmlId": "bx_6ac2be9427875"
    },
    {
      "basketId": 1387,
      "dateInsert": "2026-10-07T09:55:27.000Z",
      "id": 1353,
      "orderDeliveryId": 1207,
      "quantity": 0.75,
      "reservedQuantity": 0,
      "xmlId": "vibe-doc-si-1"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

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

400 — фильтр по несуществующему полю:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'foo' for entity 'shipment-items'. Available: basketId, dateInsert, id, orderDeliveryId, quantity, reservedQuantity, xmlId"
  }
}

Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Фильтр по полю, которого нет в схеме. Список полей: GET /v1/shipment-items/fields
400 INVALID_FILTER_FIELD Имя поля в фильтре начинается с неподдерживаемого префикса @ или !@
400 INVALID_FILTER_OPERATOR Неизвестный оператор фильтра, пустой объект в значении условия или логическое условие $or
400 INVALID_FILTER Параметр filter не является ни объектом, ни JSON-строкой, либо в одном запросе смешаны обе формы записи фильтра
400 INVALID_DUPLICATE_FILTER_FIELD Два условия фильтра сводятся к одному условию Битрикс24, например $ne и != на одном поле. Передайте одно из них
400 UNKNOWN_SORT_FIELD Сортировка по полю, которого нет в схеме
400 INVALID_SORT_DIRECTION Направление в order или в объектной форме sort не из списка asc, desc, ASC, DESC, 1, -1
403 SCOPE_DENIED API-ключ не имеет скоупа sale
403 MANAGEMENT_KEY_NO_ENTITY_ACCESS Запрос сделан ключом управления. Для сущностей нужен ключ приложения или личный ключ со скоупом sale
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Переданный API-ключ не найден
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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

В выборку входят строки системной отгрузки. Фильтр по basketId возвращает все отгрузки, по которым распределена позиция корзины, включая системную отгрузку с нераспределённым остатком. В примере выше позиция корзины 1387 с количеством 1 разложена на 0.75 в отгрузке 1207 и 0.25 в системной отгрузке 1195. Подробнее — Что нужно знать перед работой.

Не каждая строка списка открывается по id. Позиции системной отгрузки и позиции отгрузок, которых уже нет, приходят в списке, но GET /v1/shipment-items/:id отвечает на них 404. В примере выше так отвечает позиция 1347. Состав конкретной отгрузки берите этим списком с filter[orderDeliveryId].

Когда использовать search вместо list: POST /v1/shipment-items/search передаёт параметры в теле запроса, а не в строке запроса, и разбивает выборку по временны́м окнам при фильтре по диапазону dateInsert шире 14 дней.

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