Создание отгрузки

Что делает отгрузка

Отгрузка фиксирует факт поставки товара или оказания услуги. По ней формируются отчётные документы и фискальный чек, а у заказов с холдированием — списываются заблокированные на карте средства.

Отгрузок по заказу может быть несколько: например, поставка партиями. На каждую оформляются свои документы.
Сумма всех отгрузок не превышает сумму заказа.
Когда в отгрузках закрыты все позиции заказа, деньги списываются целиком. Если часть заказа не состоялась, последнюю отгрузку отправляют с final = true: заказ считается выполненным, а остаток резерва разблокируется — подробнее в холдировании.

Отгрузка создаётся одним запросом:

метод: POST
ресурс: /v3/billing/api/order/shipment
тело запроса - объект CreateShipmentRequest
тело ответа - объект ShipmentResponse
Возможные ошибки

Пример запроса

POST /v3/billing/api/order/shipment
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
    "orderId": "0187c6db-1637-c1ca-bef7-f6706799c41e",
    "basketItems": [
        {
            "sku": "01GZ3DP5HADMSBAXRKVCES5FJX",
            "name": "iPhone 5s",
            "measure": "шт",
            "measureCode": "796",
            "originCountry": "Россия",
            "originCountryCode": "643",
            "grossWeight": 1010.55,
            "netWeight": 1000.66,
            "quantity": 1,
            "amount": 122.00,
            "amountWoVat": 100.00,
            "totalAmount": 122.00,
            "totalVatAmount": 22.00,
            "vatCode": "RUS_VAT22",
            "type": "commodity",
            "paymentType": "full_prepayment"
        }
    ]
}

Ответ (по схеме):

{
  "data": {
    "id": 1,
    "orderId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "basketItems": [
      {
        "sku": "string",
        "name": "string",
        "groupName": "string",
        "measure": "string",
        "measureCode": "string",
        "originCountry": "string",
        "originCountryCode": "string",
        "grossWeight": 100.5,
        "netWeight": 100.5,
        "quantity": 100.5,
        "amount": 100.5,
        "amountWoVat": 100.5,
        "totalAmount": 100.5,
        "totalVatAmount": 100.5,
        "vatCode": "RUS_VAT22",
        "type": "string",
        "gtdNumber": "string",
        "paymentType": "string",
        "excise": 100.5,
        "metaData": {},
        "tnved": "string",
        "rnpt": "string",
        "gtin": "string",
        "category": "string",
        "categoryType": "string",
        "serviceDate": "2026-08-03T12:00:00+03:00"
      }
    ],
    "createdAt": "2026-08-03T12:00:00+03:00",
    "type": "string",
    "status": "draft",
    "amount": 100.5,
    "vatAmount": 100.5,
    "final": false,
    "documentNumber": "string",
    "description": "string",
    "documentDate": "2026-08-03T12:00:00+03:00"
  },
  "metaData": {
    "totalCount": 1,
    "pageSize": 1,
    "page": 1
  },
  "extendedData": [
    {
      "type": "string",
      "data": {}
    }
  ]
}

Список отгрузок

По одному заказу отгрузок бывает несколько, и перед оформлением новой полезно посмотреть, что уже отгружено: сумма всех отгрузок не превышает сумму заказа, а состав повторно не отгружается.

метод: GET
ресурс: /v3/billing/api/order/shipment
тело ответа — конверт с массивом объектов ShipmentResponse в data и счётчиками в metaData
_extend[]=merchant добавляет в ответ данные магазина
Возможные ошибки

Пример запроса

GET /v3/billing/api/order/shipment?_extend[]=merchant
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Accept: application/json

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

{
  "data": [
    {
      "id": 2,
      "orderId": "01771534-1a57-f184-dee3-ebeb91dded75",
      "merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "basketItems": [
        {
          "sku": "01GZ3DP5HADMSBAXRKVCES5FJX",
          "name": "iPhone 5s",
          "measure": "шт",
          "measureCode": "796",
          "quantity": 1,
          "amount": 122.00,
          "amountWoVat": 100.00,
          "totalAmount": 122.00,
          "totalVatAmount": 22.00,
          "vatCode": "RUS_VAT22"
        }
      ],
      "createdAt": "2026-08-03T12:00:00+03:00",
      "type": "shipment",
      "status": "completed",
      "amount": 122.00,
      "vatAmount": 22.00,
      "final": true,
      "documentNumber": "123",
      "documentDate": "2026-08-03T12:00:00+03:00"
    }
  ],
  "metaData": {
    "totalCount": 1,
    "pageSize": 20,
    "page": 1
  },
  "extendedData": []
}

Статусы отгрузки

Статус	Что означает
`draft`	черновик: состав можно изменить
`pending`	отгрузка в обработке
`completed`	отгрузка завершена, по ней сформированы документы
`canceled`	отгрузка отменена

Документы формируются по завершённой отгрузке — какие именно, зависит от схемы документооборота. О движении документов в ЭДО магазин узнаёт из событий ЭДО.

CreateShipmentRequest

Свойство	Тип	Описание	Пример значения
orderId *	string(36)	Id заказа	`01771534-1a57-f184-dee3-ebeb91dded75`
documentNumber	string(36)	Номер документа (накладная, счёт-фактура и пр.)	`123`
documentDate	date	Дата документа	`2026-08-12`
basketItems *	array of BasketItem	Корзина заказа
type	string, enum	Тип отгрузки, по умолчанию `shipment`	`shipment`, `cancel`
final	bool	Завершающая ли отгрузка по заказу, по умолчанию `false`	`true`, `false`

ShipmentResponse

Повторяет свойства объекта CreateShipmentRequest с дополнительными свойствами:

Свойство	Тип	Описание	Пример значения
id *	int	Идентификатор отгрузки в системе Инвойсбокс	`2`
merchantId *	string(36)	Идентификатор магазина	`01771534-1a57-f184-dee3-ebeb91dded76`

BasketItem

Корзина заказа. Пожалуйста, внимательно ознакомьтесь с требованиями по заполнению наименования номенклатуры.

Свойство	Тип	Описание
sku *	string(500)	Артикул, например: `5fe0adcfa7fb4`
name *	string(500)	Наименование, например `Бронирование номера`
groupName	string(500)	Наименование группы позиций заказа, используется для формирования отчетных документов
measure *	string(10)	Единица измерения (для России - по ОКЕИ), например `шт.`
measureCode *	string(4)	Код единицы измерения (для России - по ОКЕИ), например `796`
originCountry	string(20)	Страна происхождения товара, например, `Россия`
originCountryCode	string(4)	Код страны происхождения, например, Россия `643`
grossWeight	float	Вес брутто, например `125.45`
netWeight	float	Вес нетто, например `125.45`
quantity *	float	Количество, например `3`
amount *	float	Стоимость единицы, например `100.55`
amountWoVat *	float	Стоимость единицы без учёта НДС
totalAmount *	float	Стоимость всех единиц с НДС, например`123.55`
totalVatAmount *	float	Итого сумма НДС, например `23`
excise	float	Сумма акциза, например, `10.00`
vatCode *	string(20) enum	Код процента НДС, допустимые значения: `VATNONE` - не облагается,`VATNONE` - не облагается, `RUS_VAT0` - 0%, `RUS_VAT10` - 10/110, `RUS_VAT10_ADDED` - 10%, `RUS_VAT20` - 20/120, `RUS_VAT20_ADDED` - 20% `RUS_VAT22` - 22/122, `RUS_VAT22_ADDED` - 22%
type *	string(10) или int	Тип позиции, в соответствии со справочником или service - сервис, commodity - товар
paymentType *	string(20) enum	Тип оплаты, допустимые значения: `full_prepayment`, `prepayment`, `advance`, `full_payment`
metaData	object	Дополнительные данные элемента корзины