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

Позиции отгрузок

Состав отгрузки заказа интернет-магазина: какая позиция корзины и в каком количестве входит в отгрузку.

Битрикс24 API: sale.shipmentitem.* Скоуп: sale

Создать позицию отгрузки

POST /v1/shipment-items

Добавляет позицию корзины заказа интернет-магазина в отгрузку в указанном количестве.

Поля передаются плоско в корне JSON, без обёртки fields. Откуда берётся свободное количество позиции корзины — Позиции отгрузок.

Поля запроса (body)

Поле Тип Обяз. Описание
orderDeliveryId number да ID отгрузки. Список: GET /v1/shipments. После создания не меняется
basketId number да ID позиции корзины того же заказа, к которому относится отгрузка. Список: GET /v1/basket-items. После создания не меняется
quantity number да Количество товара в отгрузке. Дробное значение, например 0.5, сохраняется без округления. Принимается и число строкой с точкой, например "0.5". Не больше свободного количества позиции корзины
xmlId string нет Внешний код. Если не передать, генерируется автоматически

Полный список полей — GET /v1/shipment-items/fields.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/shipment-items" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderDeliveryId": 1207,
    "basketId": 1387,
    "quantity": 0.5
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/shipment-items" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderDeliveryId": 1207,
    "basketId": 1387,
    "quantity": 0.5
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/shipment-items', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderDeliveryId: 1207,
    basketId: 1387,
    quantity: 0.5,
  }),
})

const { success, data } = await res.json()
console.log('ID позиции отгрузки:', data.id)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/shipment-items', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderDeliveryId: 1207,
    basketId: 1387,
    quantity: 0.5,
  }),
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean true при успехе. HTTP-статус ответа — 201
data object Созданная позиция отгрузки
data.id number ID созданной позиции отгрузки
data.orderDeliveryId number ID отгрузки
data.basketId number ID позиции корзины
data.quantity number Количество товара в отгрузке
data.reservedQuantity number Зарезервированное количество
data.xmlId string Внешний код. Если не передан в запросе — сгенерированный, вида bx_6ac608ffa0d41
data.dateInsert datetime Дата создания, ISO 8601

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

JSON 
{
  "success": true,
  "data": {
    "basketId": 1387,
    "dateInsert": "2026-10-07T09:55:27.000Z",
    "id": 1353,
    "orderDeliveryId": 1207,
    "quantity": 0.5,
    "reservedQuantity": 0,
    "xmlId": "bx_6ac608ffa0d41"
  }
}

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

422 — quantity больше свободного количества позиции корзины:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "В корзине недостаточное количество свободного товара \"товар\" для добавления в отгрузку. Возможно, вы уже добавили часть товара по этому заказу в другие отгрузки",
    "b24Code": "SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY"
  }
}

Ошибки

HTTP Код Описание
400 MISSING_REQUIRED_FIELDS Не передано или пустое обязательное поле. Поля проверяются в порядке orderDeliveryId, basketId, quantity, в message — имя первого недостающего
400 NESTED_FIELDS_ENVELOPE Тело содержит объект fields вместо плоских полей в корне JSON; позиция не создаётся
400 READONLY_FIELD В теле передано поле только для чтения, например reservedQuantity. Имя поля — в message
400 INVALID_PARAMS Значение поля не подходит под его тип, например строка "abc" в числовом quantity. Имя поля — в message
422 BITRIX_ERROR quantity больше свободного количества позиции корзины, b24Code равен SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY
422 BITRIX_ERROR Позиция корзины уже входит в эту отгрузку — Duplicate entry for key [basketId, orderDeliveryId]. Меняйте количество существующей позиции через PATCH /v1/shipment-items/:id
422 BITRIX_ERROR Отгрузки с таким orderDeliveryId нет или позиция корзины basketId относится к другому заказу — shipment not exists, b24Code равен 201240400002
422 BITRIX_ERROR Позиции корзины с таким basketId нет — shipment not exists, b24Code равен 201240400003
422 BITRIX_ERROR Битрикс24 отклонил создание по другой причине. Текст причины — в message
403 BITRIX_ACCESS_DENIED У пользователя ключа нет прав на изменение заказов в Битрикс24
403 WRITE_BLOCKED_READONLY_KEY Ключ работает в режиме только для чтения
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-ключ не имеет настроенных токенов

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

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

Неизвестное скалярное имя не отклоняется. Неизвестное скалярное поле проходит проверку без ошибки 400, не сохраняется и не вызывает предупреждения. Объект fields — отдельный случай: он отклоняется с 400 NESTED_FIELDS_ENVELOPE до создания. Передавайте поля позиции отгрузки в корне JSON.

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