# Отгрузки

Отгрузки заказа интернет-магазина: служба доставки, стоимость доставки, трек-номер, документ отгрузки и отметка «отгружено».

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

## Операции

- [Создать отгрузку](./shipments/create.md) — `POST /v1/shipments`
- [Список отгрузок](./shipments/list.md) — `GET /v1/shipments`
- [Получить отгрузку](./shipments/get.md) — `GET /v1/shipments/:id`
- [Обновить отгрузку](./shipments/update.md) — `PATCH /v1/shipments/:id`
- [Удалить отгрузку](./shipments/delete.md) — `DELETE /v1/shipments/:id`
- [Поиск отгрузок](./shipments/search.md) — `POST /v1/shipments/search`
- [Поля отгрузки](./shipments/fields.md) — `GET /v1/shipments/fields`
- [Агрегация отгрузок](./shipments/aggregate.md) — `POST /v1/shipments/aggregate`
- [Поставить отметку «отгружено»](./shipments/ship.md) — `POST /v1/shipments/:id/ship`
- [Снять отметку «отгружено»](./shipments/unship.md) — `POST /v1/shipments/:id/unship`

## Ключевые поля

| Поле | Тип | Описание |
|------|-----|---------|
| `orderId` | number | ID заказа. Список: [`GET /v1/orders`](/docs/entities/orders/list). Задаётся только при создании |
| `deliveryId` | number | ID службы доставки. Список: [`GET /v1/delivery-services`](/docs/entities/delivery-services/list) |
| `deducted` | boolean | Отметка «отгружено». Меняется только через [`ship`](./shipments/ship.md) и [`unship`](./shipments/unship.md) |
| `allowDelivery` | boolean | Доставка разрешена. Новая отгрузка без этого поля создаётся с `false` |
| `statusId` | string | Статус доставки. Список: [`GET /v1/order-statuses?filter[type]=D`](/docs/entities/order-statuses/list) |
| `responsibleId` | number | Ответственный сотрудник. Список: [`GET /v1/users`](/docs/entities/users/list) |
| `priceDelivery` | number | Стоимость доставки |
| `shipmentItems` | array | Позиции отгрузки. Меняются через [позиции отгрузок](/docs/entities/shipment-items) |

Полный список полей — [`GET /v1/shipments/fields`](./shipments/fields.md).

## Что нужно знать перед работой

1. **Отгрузка всегда принадлежит заказу.** Для создания нужны `orderId` и `deliveryId`, перенести отгрузку в другой заказ нельзя. Номер отгрузки `accountNumber` складывается из номера заказа и порядкового номера отгрузки через `/`, например `1027/2`.
2. **Новая отгрузка может прийти без позиций.** Состав отгрузки задаётся отдельно, через [позиции отгрузок](/docs/entities/shipment-items). После создания проверьте `shipmentItems` в [`GET /v1/shipments/:id`](./shipments/get.md).
3. **Отметка «отгружено» ставится отдельным действием.** Поле `deducted` в теле создания и изменения отклоняется с `400 READONLY_FIELD`. Новая отгрузка создаётся без отметки, поставить её можно через [`POST /v1/shipments/:id/ship`](./shipments/ship.md). При включённом складском учёте отметка может списать остатки со склада.
4. **Изменение сохраняет непереданные поля.** [`PATCH /v1/shipments/:id`](./shipments/update.md) перед записью читает отгрузку, поэтому достаточно передать только меняемые поля. Изменение отклоняется, если сохранить отгрузку без потерь нельзя: пустой ответственный, пустая компания отгрузки при другой компании у заказа, ручная стоимость доставки (`customPriceDelivery: true`). Такую отгрузку меняйте в интерфейсе Битрикс24.
5. **Системные отгрузки не возвращаются.** Список и поиск показывают только отгрузки с `system: false`. Фильтр `filter[system]=true` возвращает пустой список.

## Типичный сценарий

1. Найти заказ: [`GET /v1/orders`](/docs/entities/orders/list).
2. Выбрать службу доставки: [`GET /v1/delivery-services`](/docs/entities/delivery-services/list).
3. Создать отгрузку: [`POST /v1/shipments`](./shipments/create.md) с `orderId` и `deliveryId`.
4. Наполнить отгрузку позициями: [позиции отгрузок](/docs/entities/shipment-items).
5. Записать трек-номер и номер документа: [`PATCH /v1/shipments/:id`](./shipments/update.md).
6. Когда товар передан в доставку, поставить отметку: [`POST /v1/shipments/:id/ship`](./shipments/ship.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Записей на запрос списка | до 5000 (`limit`), по умолчанию 50 |
| Агрегация | до 5 выражений `aggregate` в одном запросе, функции `count`, `sum`, `avg`, `min`, `max` |
| Пакетные вызовы | не поддерживаются: [`POST /v1/batch`](/docs/batch) отвечает `ACTION_NOT_SUPPORTED` на `shipments`, эндпоинты раздела вызываются по одному |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Позиции отгрузок](/docs/entities/shipment-items)
- [Заказы](/docs/entities/orders)
- [Службы доставки](/docs/entities/delivery-services)
- [Статусы заказов](/docs/entities/order-statuses)
- [Доставки CRM](/docs/entities/crm-deliveries)
- [Справочник сущностей](/docs/entity-api)