## Обновить отгрузку `PATCH /v1/shipments/:id` Обновляет существующую отгрузку заказа интернет-магазина. Непереданные поля сохраняются. Поля передаются плоско в корне JSON, без обёртки `fields`. Как сохраняются непереданные поля — [Отгрузки](/docs/entities/shipments). ## Параметры | Параметр | Тип | Обяз. | Описание | |----------|-----|:-----:|---------| | `id` (path) | number | да | ID отгрузки. Список: [`GET /v1/shipments`](./list.md) | ## Поля запроса (body) | Поле | Тип | Описание | |------|-----|---------| | `trackingNumber` | string | Трек-номер | | `deliveryDocNum` | string | Номер документа отгрузки | | `deliveryDocDate` | datetime | Дата документа отгрузки | | `allowDelivery` | boolean | Доставка разрешена | | `statusId` | string | Статус доставки. Список: [`GET /v1/order-statuses?filter[type]=D`](/docs/entities/order-statuses/list) | | `deliveryId` | number | ID службы доставки. Список: [`GET /v1/delivery-services`](/docs/entities/delivery-services/list) | | `priceDelivery` | number | Стоимость доставки | | `basePriceDelivery` | number | Базовая стоимость доставки | | `responsibleId` | number | ID ответственного сотрудника. Список: [`GET /v1/users`](/docs/entities/users/list). Пустое значение `null` или `0` не принимается | | `companyId` | number | ID компании CRM. Список: [`GET /v1/companies`](/docs/entities/companies/list). Существование компании не проверяется. Пустое значение принимается, только если у заказа тоже нет компании — поле `companyId` в [`GET /v1/orders/:id`](/docs/entities/orders/get) | | `comments` | string | Комментарий к отгрузке | | `xmlId` | string | Внешний код | | `orderId` | number | RO. Задаётся только при [создании](./create.md) | | `deducted` | boolean | RO. Меняется через [`ship`](./ship.md) и [`unship`](./unship.md) | | `customPriceDelivery` | boolean | RO. Признак ручной стоимости доставки | Полный список полей — [`GET /v1/shipments/fields`](./fields.md). ## Примеры ### curl — личный ключ ```bash curl -X PATCH "https://vibecode.bitrix24.tech/v1/shipments/1205" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "trackingNumber": "VIBE-DOC-2", "deliveryDocNum": "ТН-1205", "allowDelivery": true }' ``` ### curl — OAuth-приложение ```bash curl -X PATCH "https://vibecode.bitrix24.tech/v1/shipments/1205" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "trackingNumber": "VIBE-DOC-2", "deliveryDocNum": "ТН-1205", "allowDelivery": true }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/shipments/1205', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ trackingNumber: 'VIBE-DOC-2', deliveryDocNum: 'ТН-1205', allowDelivery: true, }), }) const { success, data } = await res.json() ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/shipments/1205', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ trackingNumber: 'VIBE-DOC-2', deliveryDocNum: 'ТН-1205', allowDelivery: true, }), }) const { success, data } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | `true` при успехе | | `data` | object | Обновлённая отгрузка со всеми полями, включая непереданные. Все поля — [Поля отгрузки](./fields.md) | ## Пример ответа ```json { "success": true, "data": { "accountNumber": "1027/2", "allowDelivery": true, "basePriceDelivery": 500, "canceled": false, "comments": "Тестовая отгрузка для документации", "companyId": null, "currency": "RUB", "customPriceDelivery": false, "dateAllowDelivery": "2026-10-06T11:31:17.000Z", "dateCanceled": null, "dateDeducted": null, "dateInsert": "2026-10-06T11:30:44.000Z", "dateMarked": null, "dateResponsibleId": "2026-10-06T11:30:44.000Z", "deducted": false, "deliveryDocDate": null, "deliveryDocNum": "ТН-1205", "deliveryId": 1, "deliveryName": "Доставка курьером", "deliveryXmlId": null, "discountPrice": 0, "empAllowDeliveryId": 1317, "empCanceledId": null, "empDeductedId": null, "empMarkedId": null, "empResponsibleId": 1317, "externalDelivery": false, "id": 1205, "id1c": null, "marked": false, "orderId": 1027, "priceDelivery": 500, "reasonMarked": null, "reasonUndoDeducted": null, "responsibleId": 1295, "shipmentItems": [], "statusId": "DN", "statusXmlId": null, "system": false, "trackingDescription": null, "trackingLastCheck": null, "trackingNumber": "VIBE-DOC-2", "trackingStatus": null, "updated1c": false, "version1c": null, "xmlId": "bx_6ac4cdd46e442" } } ``` ## Пример ответа при ошибке 400 — передан пустой `responsibleId`: ```json { "success": false, "error": { "code": "INVALID_PARAMS", "message": "Bitrix24 cannot preserve an empty shipment responsibleId and its assignment metadata. Set an explicit nonzero responsibleId or update the shipment in Bitrix24." } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `READONLY_FIELD` | В теле передано `deducted`. Ответ содержит `hint` с адресами [`ship`](./ship.md) и [`unship`](./unship.md) | | 400 | `READONLY_FIELD` | В теле передано другое поле только для чтения: `customPriceDelivery`, `orderId`, `accountNumber` и другие. Имя поля — в `message` | | 400 | `EMPTY_UPDATE_BODY` | Тело запроса пустое | | 400 | `INVALID_PARAMS` | В теле нет ни одного известного поля отгрузки — `At least one writable shipment field is required.` | | 400 | `INVALID_PARAMS` | Одно поле передано дважды под разными именами, например `trackingNumber` и `TRACKING_NUMBER` — `Duplicate field alias` | | 400 | `INVALID_PARAMS` | Ответственный после записи оказался бы пустым: передан `responsibleId`, равный `null` или `0`, либо он не передан, а у сохранённой отгрузки ответственного нет. Передайте ненулевой `responsibleId` | | 400 | `INVALID_PARAMS` | Компания отгрузки после записи оказалась бы пустой, а у заказа указана другая компания. Передайте ненулевой `companyId` | | 400 | `INVALID_PARAMS` | У сохранённой отгрузки задана ручная стоимость доставки, `customPriceDelivery` равен `true`. Такую отгрузку меняйте в интерфейсе Битрикс24 | | 400 | `INVALID_PARAMS` | Значение поля не подходит под его тип, например слово в числовом `priceDelivery` или объект в текстовом `comments`. Имя поля — в `message` | | 400 | `INVALID_PARAMS` | `id` в пути не является целым неотрицательным числом | | 404 | `ENTITY_NOT_FOUND` | Отгрузки с таким `id` нет | | 422 | `BITRIX_NO_EFFECT` | Битрикс24 не вернул поля отгрузки или заказ, без которых непереданные поля не сохранить. Запись не выполнялась | | 422 | `BITRIX_ERROR` | Битрикс24 отклонил запись или чтение заказа отгрузки. Текст причины — в `message` | | 403 | `BITRIX_ACCESS_DENIED` | У пользователя ключа нет прав на изменение заказов в Битрикс24 | | 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ работает в режиме только для чтения | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` | | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **Разрешение доставки фиксирует дату и сотрудника.** После `allowDelivery: true` в ответе заполняются дата разрешения `dateAllowDelivery` и ID сотрудника `empAllowDeliveryId`. **Имена полей принимаются и в верхнем регистре.** `TRACKING_NUMBER` записывается так же, как `trackingNumber`. ## Смотрите также - [Отгрузки](/docs/entities/shipments) - [Получить отгрузку](./get.md) - [Создать отгрузку](./create.md) - [Поставить отметку «отгружено»](./ship.md) - [Снять отметку «отгружено»](./unship.md) - [Поля отгрузки](./fields.md) - [Позиции отгрузок](/docs/entities/shipment-items)