Создание заказа с подбором и резервированием ячейки

Создание заказа на доставку в постамат с автоматическим подбором и резервированием ячеек под посылки заказа.

Генерация штрих-кодов и номера заказа осуществляется на стороне внешней системы.

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

Логика подбора ячеек

При создании заказа платформа:

Определяет ячейки, доступные маркетплейсу на постамате (capacity).
Исключает ячейки с флагами: неисправна, грязная, требуется инвентаризация, заблокирована.
Учитывает ячейки, занятые заказами партнёра.
Примешивает к расчёту ячейки с заказами в статусе Ожидает возврат.
Сортирует ячейки по размеру.
Подбирает подходящие ячейки для всех посылок, начиная с наименьших по габаритам.
Учитывает ротацию габаритов посылки и возможность размещения нескольких посылок в одной ячейке.
Резервирует ячейки и возвращает результат.

`PUT` /smartorder/create

Инициатор запроса внешняя система

Header parameters

	desc	type
`X-Smartix-Api-Key`	Ключ авторизации	string	required
`Content-Type`	Со значением `application/json`	string	required

Request body

	desc	type
`externalId`	Идентификатор заказа во внешней системе	string	required
`number`	Номер заказа (может быть использован при отображении клиенту/курьеру)	string	no required
`postamatId`	Идентификатор постамата, куда осуществляется доставка	int32	required
`dateDelivery`	Дата предполагаемой доставки	date	required
`parcels`	Данные по кол-ву загружаемых посылок	array	required
`clientInvoice`	Данные по составу заказа	object	required
`notification`	Данные по клиенту (используются для идентификации клиента в поддержке)	object	required

`parcels` array

	desc	type
`barcode`	Штрих-код посылки	string	required
`additionalBarcodes`	Дополнительные штрих-коды, по которым возможно идентифицировать заказ (используется при закладке курьера на постамате)	array of strings	no required
`dimension`	Информация о размере посылки	object	no required

`dimension` object

	desc	type
`height`	Высота коробки, мм ( >=1 )	int32	no required
`length`	Длина коробки, мм ( >=1 )	int32	no required
`width`	Ширина коробки, мм ( >=1 )	int32	no required

`clientInvoice` object

	desc	type
`cart`	Данные по составу заказа (используется для претензионной работы)	object	required

`cart` object

	desc	type
`items`	Данные по товарам	array of object	required
`prePaymentSum`	Оплаченная стоимость всего заказа в копейках	int64	required

`items` array

	desc	type
`count`	Количество товаров	int32	required
`barcode`	Штрих-код посылки (указывается для связки с parcels)	string	no required
`name`	Наименование товара	string	required
`subjectType`	Тип товара согласно 54 ФЗ документ	int32	required
`price`	Стоимость одного товара в копейках	int64	required
`totalSum`	Полная стоимость за все товары в копейках	int64	required
`taxId`	Код ставки НДС согласно 54 ФЗ документ	int32	required
`taxSystemId`	Система налогообложения	int32	required

`notification` object

	desc	type
`emails`	Email клиента	array of strings	required
`phones`	Телефон клиента. Телефон передается в формате +79996543421	array of strings	required

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

shell

curl -X 'PUT' \
  'https://api-stage.selftech.ru/postamat/marketplace/v4/auth/delivery/smartorder/create' \
  -H 'accept: */*' \
  -H 'X-Smartix-Api-Key: KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientInvoice": {
        "cart": {
            "items": [
                {
                    "count": 1,
                    "name": "remax. Защитные стекла",
                    "price": 28100,
                    "subjectType": 1,
                    "taxId": 1,
                    "taxSystemId": 16,
                    "totalSum": 28100,
                    "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.1.0"
                },
                {
                    "count": 1,
                    "name": "Francua. Сыворотки",
                    "price": 28000,
                    "subjectType": 1,
                    "taxId": 1,
                    "taxSystemId": 16,
                    "totalSum": 28000,
                    "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.2.0"
                },
                {
                    "count": 1,
                    "name": "bsc-opt. Ватные палочки",
                    "price": 7200,
                    "subjectType": 1,
                    "taxId": 1,
                    "taxSystemId": 16,
                    "totalSum": 7200,
                    "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.4.0"
                },
                {
                    "count": 1,
                    "name": "remax. Защитные стекла",
                    "price": 28100,
                    "subjectType": 1,
                    "taxId": 1,
                    "taxSystemId": 16,
                    "totalSum": 28100,
                    "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.1.1"
                },
                {
                    "count": 1,
                    "name": "Lanisha. Вилки столовые",
                    "price": 21900,
                    "subjectType": 1,
                    "taxId": 1,
                    "taxSystemId": 16,
                    "totalSum": 21900,
                    "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.5.0"
                }
            ],
            "prePaymentSum": 113300
        }
    },
    "externalId": "test123-886c-455a-973e-6eb5fe973c60;0fbfd2cf-7584-45fa-9ea9-e581e7fbda95",
    "notification": {
        "emails": [
            "noemail@email.ru"
        ],
        "phones": [
            "+79999999999"
        ]
    },
    "parcels": [
        {
            "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.1.0",
            "additionalBarcodes": [
                "50499597157",
                "50499597157",
                "",
                "*C8ICs2Un"
            ],
            "dimension": {
                "width": 20,
                "height": 15,
                "length": 1
            }
        },
        {
            "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.2.0",
            "additionalBarcodes": [
                "41250151185",
                "41250151185",
                "",
                "*CZqzWxEB"
            ],
            "dimension": {
                "width": 110,
                "height": 150,
                "length": 10
            }
        },
        {
            "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.4.0",
            "additionalBarcodes": [
                "49165340384",
                "49165340384",
                "",
                "*C3J7juBF"
            ],
            "dimension": {
                "width": 20,
                "height": 5,
                "length": 8
            }
        },
        {
            "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.1.1",
            "additionalBarcodes": [
                "50499597109",
                "50499597109",
                "",
                "*C8ICszUn"
            ],
            "dimension": {
                "width": 30,
                "height": 50,
                "length": 10
            }
        },
        {
            "barcode": "eb8.i47dc8c90b77fd7cb0a7435a196566a75.5.0",
            "additionalBarcodes": [
                "49502029883",
                "49502029883",
                "",
                "*C4aNCDth"
            ],
            "dimension": {
                "width": 211,
                "height": 112,
                "length": 110
            }
        }
    ],
    "postamatId": 220,
    "dateDelivery": "2026-06-10"
}'

Описание объектов ответа

Response body

	desc	type
`reserved`	Успешно зарезервированные ячейки	array of objects
`temporarilyRejectedItems`	Посылки, не размещённые из-за нехватки доступных ячеек	array of strings
`permanentlyRejectedItems`	Посылки, не влезающие ни в одну ячейку постамата	array of strings
`toReturn`	Заказы в статусе «Ожидает возврата» в постамате	array of objects

`reserved` array

	desc	type
`cellId`	Идентификатор ячейки постамата	int32
`externalId`	Идентификатор заказа	string
`barcodes`	Штрих-коды посылок, размещённых в ячейке	array of strings

`toReturn` array

	desc	type
`cellId`	Идентификатор ячейки с заказом в статусе «Ожидает возврата»	int32
`externalId`	Идентификатор заказа в статусе «Ожидает возврата»	string
`barcodes`	Штрих-коды посылок заказа в статусе «Ожидает возврата»	array of strings

Справочник: значения полей ответа

Поле	Когда заполняется
`reserved`	Есть хотя бы одна успешно зарезервированная ячейка
`temporarilyRejectedItems`	Посылка влезает по габаритам, но нет доступных ячеек (capacity)
`permanentlyRejectedItems`	Посылка не влезает ни в одну bp ячеек постамата при ротации
`toReturn`	В постамате есть заказы в статусе «Ожидает возврата». Возвращается независимо от результата резервирования

Возможные варианты ответа

1. Успешное резервирование всех посылок

Все посылки размещены. Блок toReturn присутствует, если в постамате есть заказы ОВ.

json

{
  "reserved": [
    {
      "cellId": 4142,
      "externalId": "21fb04ee-e5a6-4ffc-ae2a-0776f97fd734",
      "barcodes": [
        "6de5c5b0af274e48b75a813fee2ea580.1",
        "6de5c5b0af274e48b75a813fee2ea580.2",
        "6de5c5b0af274e48b75a813fee2ea580.3",
        "6de5c5b0af274e48b75a813fee2ea580.4",
        "6de5c5b0af274e48b75a813fee2ea580.5"
      ]
    }
  ],
  "temporarilyRejectedItems": [],
  "permanentlyRejectedItems": [],
  "toReturn": [
    {
      "cellId": 4135,
      "externalId": "321fb04ee-e5a6-4ffc-ae2a-0776f97fd734",
      "barcodes": ["566de5c5b0ae48b75a813fee2ea580.22"]
    }
  ]
}

2. Частичное резервирование - нехватка ячеек (`temporarilyRejectedItems`)

Часть посылок размещена, часть не удалось разместить из-за нехватки ёмкости (заняты или неисправны).

json

{
  "reserved": [
    {
      "cellId": 4137,
      "externalId": "21fb04ee-e5a6-4ffc-ae2a-0776f97fd734",
      "barcodes": ["566de5c5b0ae48b75a813fee2ea580.01"]
    },
    {
      "cellId": 4139,
      "externalId": "321fb04ee-e5a6-4ffc-ae2a-0776f97fd734",
      "barcodes": ["566de5c5b0ae48b75a813fee2ea580.02"]
    }
  ],
  "temporarilyRejectedItems": [
    "566de5c5b0ae48b75a813fee2ea580.03",
    "566de5c5b0ae48b75a813fee2ea580.04",
    "566de5c5b0ae48b75a813fee2ea580.05"
  ],
  "permanentlyRejectedItems": [],
  "toReturn": []
}

3. Посылки не влезают по габаритам (`permanentlyRejectedItems`)

Ни одна посылка не проходит по размерам ячеек постамата (не влезает).

json

{
  "reserved": [],
  "temporarilyRejectedItems": [],
  "permanentlyRejectedItems": [
    "566de5c5b0ae48b75a813fee2ea580.22",
    "566de5c5b0ae48b75a813fee2ea580.21",
    "566de5c5b0ae48b75a813fee2ea580.23"
  ],
  "toReturn": [
    {
      "cellId": 4147,
      "externalId": "21fb04ee-e5a6-4ffc-ae2a-0776f97fd734",
      "barcodes": ["566de5c5b0ae48b75a813fee2ea580.01"]
    }
  ]
}

4. Смешанный случай

Часть посылок зарезервирована, часть отклонена из-за нехватки ячеек, часть не влезает.

json

{
  "reserved": [
    {
      "cellId": 4142,
      "externalId": "21fb04ee-e5a6-4ffc-ae2a-0776f97fd734",
      "barcodes": ["566de5c5b0ae48b75a813fee2ea580.01", "566de5c5b0ae48b75a813fee2ea580.02"]
    }
  ],
  "temporarilyRejectedItems": ["566de5c5b0ae48b75a813fee2ea580.03"],
  "permanentlyRejectedItems": ["566de5c5b0ae48b75a813fee2ea580.04"],
  "toReturn": []
}

5. Ничего не зарезервировано - исчерпан capacity

Все посылки влезают по габаритам, но свободных ячеек нет.

json

{
  "reserved": [],
  "temporarilyRejectedItems": [
    "566de5c5b0ae48b75a813fee2ea580.01",
    "566de5c5b0ae48b75a813fee2ea580.02",
    "566de5c5b0ae48b75a813fee2ea580.03"
  ],
  "permanentlyRejectedItems": [],
  "toReturn": [
    {
      "cellId": 4135,
      "externalId": "21fb04ee-e5a6-4ffc-ae2a-0776f97fd734",
      "barcodes": ["566de5c5b0ae48b75a813fee2ea580.11"]
    }
  ]
}

Создание заказа с подбором и резервированием ячейки ​

Логика подбора ячеек ​

PUT /smartorder/create ​

parcels array ​

dimension object ​

clientInvoice object ​

cart object ​

items array ​

notification object ​

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

Описание объектов ответа ​

Response body ​

reserved array ​

toReturn array ​

Справочник: значения полей ответа ​

Возможные варианты ответа ​

1. Успешное резервирование всех посылок ​

2. Частичное резервирование - нехватка ячеек (temporarilyRejectedItems) ​

3. Посылки не влезают по габаритам (permanentlyRejectedItems) ​

4. Смешанный случай ​

5. Ничего не зарезервировано - исчерпан capacity ​

Создание заказа с подбором и резервированием ячейки

Логика подбора ячеек

`PUT` /smartorder/create

`parcels` array

`dimension` object

`clientInvoice` object

`cart` object

`items` array

`notification` object

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

Описание объектов ответа

Response body

`reserved` array

`toReturn` array

Справочник: значения полей ответа

Возможные варианты ответа

1. Успешное резервирование всех посылок

2. Частичное резервирование - нехватка ячеек (`temporarilyRejectedItems`)

3. Посылки не влезают по габаритам (`permanentlyRejectedItems`)

4. Смешанный случай

5. Ничего не зарезервировано - исчерпан capacity