## Создать отгрузку `POST /v1/shipments` Создаёт отгрузку в существующем заказе интернет-магазина и привязывает к ней службу доставки. Поля передаются плоско в корне JSON, без обёртки `fields`. ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|---------| | `orderId` | number | да | ID заказа, в котором создаётся отгрузка. Список: [`GET /v1/orders`](/docs/entities/orders/list). После создания не меняется | | `deliveryId` | number | да | ID службы доставки. Список: [`GET /v1/delivery-services`](/docs/entities/delivery-services/list) | | `allowDelivery` | boolean | нет | Доставка разрешена. Если не передать, отгрузка создаётся с `false` | | `statusId` | string | нет | Статус доставки. Список: [`GET /v1/order-statuses?filter[type]=D`](/docs/entities/order-statuses/list). Если не передать, отгрузка получает начальный статус доставки портала, в примере ниже это `DN` | | `trackingNumber` | string | нет | Трек-номер | | `deliveryDocNum` | string | нет | Номер документа отгрузки | | `deliveryDocDate` | datetime | нет | Дата документа отгрузки | | `priceDelivery` | number | нет | Стоимость доставки. Если не передать, подставляется стоимость службы доставки | | `basePriceDelivery` | number | нет | Базовая стоимость доставки | | `responsibleId` | number | нет | ID ответственного сотрудника. Список: [`GET /v1/users`](/docs/entities/users/list). Если не передать, ответственный назначается автоматически | | `companyId` | number | нет | ID компании CRM. Список: [`GET /v1/companies`](/docs/entities/companies/list). Существование компании не проверяется | | `comments` | string | нет | Комментарий к отгрузке | | `xmlId` | string | нет | Внешний код. Если не передать, генерируется автоматически | Полный список полей — [`GET /v1/shipments/fields`](./fields.md). ## Примеры ### curl — личный ключ ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/shipments" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "orderId": 1027, "deliveryId": 1, "trackingNumber": "VIBE-DOC-1", "comments": "Тестовая отгрузка для документации" }' ``` ### curl — OAuth-приложение ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/shipments" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "orderId": 1027, "deliveryId": 1, "trackingNumber": "VIBE-DOC-1", "comments": "Тестовая отгрузка для документации" }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/shipments', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ orderId: 1027, deliveryId: 1, trackingNumber: 'VIBE-DOC-1', comments: 'Тестовая отгрузка для документации', }), }) const { success, data } = await res.json() console.log('ID отгрузки:', data.id) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/shipments', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ orderId: 1027, deliveryId: 1, trackingNumber: 'VIBE-DOC-1', comments: 'Тестовая отгрузка для документации', }), }) const { success, data } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | `true` при успехе. HTTP-статус ответа — `201` | | `data` | object | Созданная отгрузка со всеми полями — [Поля отгрузки](./fields.md) | | `data.id` | number | ID созданной отгрузки | | `data.accountNumber` | string | Номер отгрузки: номер заказа и порядковый номер отгрузки через `/` | | `data.deducted` | boolean | Отметка «отгружено». У новой отгрузки всегда `false` | | `data.deliveryName` | string | Название службы доставки из `deliveryId` | | `data.shipmentItems` | array | Позиции отгрузки. Пустой массив, если позиции ещё не добавлены | | `data.system` | boolean | Системная отгрузка. У созданной через API всегда `false` | ## Пример ответа ```json { "success": true, "data": { "accountNumber": "1027/2", "allowDelivery": false, "basePriceDelivery": 500, "canceled": false, "comments": "Тестовая отгрузка для документации", "companyId": null, "currency": "RUB", "customPriceDelivery": false, "dateAllowDelivery": null, "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": null, "deliveryId": 1, "deliveryName": "Доставка курьером", "deliveryXmlId": null, "discountPrice": 0, "empAllowDeliveryId": null, "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-1", "trackingStatus": null, "updated1c": false, "version1c": null, "xmlId": "bx_6ac4cdd46e442" } } ``` ## Пример ответа при ошибке 422 — заказа с таким `orderId` не существует: ```json { "success": false, "error": { "code": "BITRIX_ERROR", "message": "Не удается загрузить заказ", "b24Code": "0" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `MISSING_REQUIRED_FIELDS` | Не передано или пустое обязательное поле `orderId` или `deliveryId`. Имя поля — в `message` | | 400 | `READONLY_FIELD` | В теле передано `deducted`. Ответ содержит `hint` с адресами [`ship`](./ship.md) и [`unship`](./unship.md) | | 400 | `READONLY_FIELD` | В теле передано другое поле только для чтения, например `customPriceDelivery` или `accountNumber`. Имя поля — в `message` | | 400 | `INVALID_PARAMS` | Значение поля не подходит под его тип, например слово в числовом `deliveryId` или объект в текстовом `comments`. Имя поля — в `message` | | 422 | `BITRIX_ERROR` | Битрикс24 отклонил создание. Например, заказа с таким `orderId` нет — `Не удается загрузить заказ` | | 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). ## Смотрите также - [Отгрузки](/docs/entities/shipments) - [Получить отгрузку](./get.md) - [Обновить отгрузку](./update.md) - [Поставить отметку «отгружено»](./ship.md) - [Удалить отгрузку](./delete.md) - [Позиции отгрузок](/docs/entities/shipment-items) - [Заказы](/docs/entities/orders) - [Службы доставки](/docs/entities/delivery-services)