Отгрузка (shipment) в Битрикс24 отвечает на вопрос, как и когда заказ уезжает покупателю. Это самостоятельная сущность внутри заказа со своей службой доставки, составом и статусами. Управляется группой методов sale.shipment, а ключевые флаги — deducted и allowDelivery.
Отгрузка в структуре заказа
Заказ Битрикс24 состоит из корзины, оплат и отгрузок. Отгрузка (sale.shipment) описывает логистическую часть: какая служба доставки, какая стоимость доставки, какой состав товаров едет и в каком статусе процесс.
- У одного заказа может быть несколько отгрузок — например, часть со склада, часть под заказ.
- Отгрузка привязана к службе доставки через
deliveryId. - Состав отгрузки задают отдельные методы
sale.shipmentitem.*.
Флаги deducted и allowDelivery
Два булевых поля определяют состояние отгрузки и напрямую влияют на складской учёт:
| Поле | Значение Y | Смысл |
|---|---|---|
| allowDelivery | Доставка разрешена | Заказ готов к передаче в доставку (согласован, оплачен и т.п.) |
| deducted | Отгружено | Товар списан со склада, отгрузка выполнена |
Отдельно есть строковый statusId отгрузки из справочника статусов доставки (sale.deliverystatus.*), который отражает этап процесса без влияния на склад.
Ключевые поля отгрузки
| Поле | Назначение |
|---|---|
| id | Идентификатор отгрузки |
| orderId | Заказ, к которому относится отгрузка |
| deliveryId | Служба доставки (из sale.delivery.*) |
| deliveryName | Название службы доставки |
| allowDelivery | Разрешение на доставку (Y/N) |
| deducted | Признак отгрузки/списания (Y/N) |
| statusId | Статус доставки |
| priceDelivery | Стоимость доставки |
| currency | Валюта |
| trackingNumber | Трек-номер отправления |
| responsibleId | Ответственный сотрудник |
Методы sale.shipment и состав
CRUD-методы отгрузки:
sale.shipment.add— создать отгрузку;sale.shipment.get/sale.shipment.list— чтение;sale.shipment.update— изменить, в том числе выставить allowDelivery/deducted;sale.shipment.delete— удалить;sale.shipment.getfields— описание полей.
Состав отгрузки — какие позиции корзины и в каком количестве едут — задаётся отдельно:
sale.shipmentitem.add— добавить позицию в отгрузку (ссылка наbasketIdиquantity);sale.shipmentitem.list/update/delete— управление составом.
Примеры запросов
Создание отгрузки курьерской службой для заказа 145:
POST https://portal.bitrix24.ru/rest/1/xxxxx/sale.shipment.add.json
{ "fields": { "orderId": 145, "deliveryId": 2, "priceDelivery": 350, "currency": "RUB" } }Добавление позиции в отгрузку:
sale.shipmentitem.add?fields[shipmentId]=88&fields[basketId]=501&fields[quantity]=2Разрешение доставки и отметка об отгрузке:
sale.shipment.update?id=88&fields[allowDelivery]=Y&fields[deducted]=Y&fields[trackingNumber]=RA123456789RUВыборка неотгруженных заказов:
sale.shipment.list?filter[=deducted]=N&select[]=id&select[]=orderId&select[]=deliveryName
Службы доставки и статусы
Идентификатор deliveryId должен указывать на реальную настроенную службу доставки портала. Справочники и статусы:
sale.delivery.*— службы доставки и их настройки;sale.deliverystatus.*— справочник статусов доставки;sale.deliveryservice.*— расширенные интеграционные службы (агрегаторы, ПВЗ).
Порядок обычно такой: заказ согласован → выставляется allowDelivery=Y → комплектование → deducted=Y и заполняется trackingNumber. Статус доставки в statusId ведёт клиента по этапам без прямого влияния на склад.
Практика и подводные камни
- Права sale. Как и остальные методы онлайн-магазина, отгрузки требуют разрешения
sale. - Склад и deducted. При активном складском учёте флаг
deductedдвигает остатки — тестируйте только на тестовом портале. - Согласованность составов. Сумма количеств по shipmentitem не должна превышать количество в корзине заказа.
- Отгрузка по умолчанию. Прежде чем создавать новую отгрузку, проверьте, нет ли уже системной с распределённым составом.
- Batch. Создание отгрузки и её позиций удобно объединять в
batch, используя результат первого вызова как$result.
Итог
Отгрузка в Битрикс24 — это логистическая часть заказа: служба доставки (deliveryId), стоимость, трек-номер и два ключевых флага — allowDelivery (разрешение) и deducted (фактическая отгрузка и списание). Состав задаётся через sale.shipmentitem, а статусы — через справочник доставки. Главная осторожность связана со складом: deducted двигает остатки.
Когда логистика заказов синхронизируется с 1С, складом и службами доставки, важно корректно отражать отгрузки и трек-номера в обе стороны. Мы проектируем и сопровождаем такие интеграции с Битрикс24, включая обмен с учётными системами.
Частые вопросы
Чем отличаются флаги deducted и allowDelivery?
allowDelivery=Y означает, что доставка разрешена (заказ готов к передаче), а deducted=Y — что товар фактически отгружен и списан со склада. Это разные этапы процесса.
Как задать состав отгрузки?
Позиции добавляются отдельными методами sale.shipmentitem, где указываются basketId позиции корзины и quantity. Одна отгрузка может содержать несколько shipmentitem.
Влияет ли отгрузка на складские остатки?
Да, при подключённом складском учёте установка deducted=Y списывает остатки, а возврат в N возвращает их. Поэтому флаг тестируют только на тестовом портале.
Как привязать отгрузку к службе доставки?
Через поле deliveryId, которое должно указывать на настроенную службу из sale.delivery. Название дублируется в deliveryName.
Где хранится трек-номер?
В поле trackingNumber отгрузки. Его обычно заполняют одновременно с отметкой deducted=Y при передаче отправления в доставку.
Может ли у заказа быть несколько отгрузок?
Да, например часть товара едет со склада, а часть под заказ. Каждая отгрузка имеет свой состав, службу доставки и статус.
Какие права нужны для sale.shipment?
Вебхуку или приложению требуется право sale (Онлайн-магазин), иначе методы группы вернут ошибку доступа.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.