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

Обновить позицию отгрузки

PATCH /v1/shipment-items/:id

Меняет количество товара и внешний код позиции отгрузки в заказе интернет-магазина.

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

Параметры

Параметр Тип Обяз. Описание
id (path) number да ID позиции отгрузки, целое неотрицательное число. Список: GET /v1/shipment-items

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

Поле Тип Обяз. Описание
quantity number да Новое количество товара в отгрузке. Передаётся в каждом запросе, в том числе когда меняется только xmlId. Дробное значение сохраняется без округления. Принимается и число строкой с точкой, например "0.5". Увеличение ограничено свободным количеством позиции корзины
xmlId string нет Внешний код
orderDeliveryId number нет RO. Задаётся только при создании. Чтобы перенести позицию в другую отгрузку, удалите её и создайте заново
basketId number нет RO. Задаётся только при создании
reservedQuantity number нет RO. Зарезервированное количество

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

Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/shipment-items/1353" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 0.75,
    "xmlId": "vibe-doc-si-1"
  }'

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/shipment-items/1353" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 0.75,
    "xmlId": "vibe-doc-si-1"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/shipment-items/1353', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quantity: 0.75,
    xmlId: 'vibe-doc-si-1',
  }),
})

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/shipment-items/1353', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quantity: 0.75,
    xmlId: 'vibe-doc-si-1',
  }),
})

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

Поля ответа

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

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

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

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

404 — позиции отгрузки с таким id нет:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "shipment item is not exists"
  }
}

Ошибки

HTTP Код Описание
400 READONLY_FIELD В теле передано поле только для чтения: orderDeliveryId, basketId, reservedQuantity, id и другие. Имя поля — в message
400 EMPTY_UPDATE_BODY Тело запроса пустое или не является JSON-объектом
400 INVALID_PARAMS Значение поля не подходит под его тип, например строка "abc" в числовом quantity. Имя поля — в message
400 INVALID_PARAMS id в пути не является целым неотрицательным числом
404 ENTITY_NOT_FOUND Позиции отгрузки с таким id нет — shipment item is not exists
404 ENTITY_NOT_FOUND Позиция системной отгрузки, и переданное quantity совпадает с текущим. Изменение не записывается — shipmentItem <id> not found
422 BITRIX_ERROR Позиция системной отгрузки, и передано новое quantity. Изменение не записывается — Системная отгрузка недоступна для изменения, b24Code равен 150
422 BITRIX_ERROR В теле нет quantity, например передан только xmlId или только поле с неизвестным именем — Required fields: quantity
422 BITRIX_ERROR Новое quantity превышает количество, доступное позиции корзины, b24Code равен SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY
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 — Ошибки.

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