Подготовка заказа

Метод доступен для моделей: FBS, Экспресс и DBS.

Если вы используете API-Key-токен, для вызова метода необходим один из доступов в списке

Подходит и для DBS

Запрос предназначен для работы с FBS-заказами, но вы можете использовать его для обработки DBS-заказов, если это удобно.

Позволяет выполнить три операции:

  • передать Маркету информацию о распределении товаров по коробкам;
  • передать Маркету коды маркировки для товаров;
  • удалить товар из заказа, если его не оказалось на складе.

Если нужно что-то поправить в переданных данных, просто повторите запрос — это можно делать сколько угодно раз до перевода заказа в статус Готов к отгрузке. ⚠️ Если вы меняете раскладку уже после печати и расклейки ярлыков, не забудьте перепечатать их и наклеить заново.

Как передать информацию о распределении товаров

В этом запросе вам нужно передать Маркету список коробок и указать, какие именно товары лежат в каждой из них. Коробки могут быть двух типов:

  • Содержащие товары целиком. Такая коробка может содержать сколько угодно единиц любых товаров.

  • Содержащие часть товара. Такие коробки содержат по одной части одного товара. Например, одна содержит внешний блок кондиционера, а другая — внутренний блок.

⚠️ Одна коробка не может содержать и товары целиком, и части товаров.

Как передавать коды маркировки и получать статус их проверки

Маркировка товаров в системе «Честный ЗНАК» необязательна для заказов от физических лиц

Для заказов от бизнеса все еще нужно передавать коды маркировки.

Если в заказе есть товары, подлежащие маркировке, в запросе нужно передать соответствующие уникальные коды. Что такое маркировка

Принимаются коды следующих типов:

  • Коды в системе «Честный ЗНАК» или «ASL BELGISI» (для продавцов Market Yandex Go).
  • УИН для ювелирных изделий.
  • РНПТ и ГТД для импортных прослеживаемых товаров.

Для каждой позиции в заказе, требующей маркировки, нужно передать список кодов — по одному для каждой единицы товара. Например, если в заказе две пары тапочек и одна пара туфель, получится список из двух кодов для первой позиции и список из одного кода для второй.

Если товар едет в нескольких коробках, код маркировки нужно передать для каждой из них.

Если вы работаете по модели FBS, EXPRESS

Для заказов, в которых есть ювелирные изделия или товары с маркировкой в системе «Честный ЗНАК», перевод в статус READY_TO_SHIP становится доступен, только когда:

  1. Вы передадите Маркету УИНы по каждому ювелирному изделию в заказе и коды в системе «Честный ЗНАК» по всем товарам в заказе, для которых обязательна эта маркировка.
  2. Все коды маркировки успешно пройдут проверку. Как получить статусы проверки
Как удалить товар из заказа

Чтобы удалить товар из заказа:

  1. Добавьте в запрос allowRemove: true.
  2. Передайте распределение по коробкам без товара, который нужно удалить.

Удаление нельзя отменить

Эта операция необратима: покупатель сразу получит уведомление, а состав заказа изменится.

Чтобы удалить позицию целиком, не передавайте соответствующий OrderBoxLayoutItemDTO. Чтобы уменьшить количество товара, передайте уменьшенное значение в поле fullCount.

Нельзя удалить или уменьшить количество товара, если он:

  • добавлен по акции;
  • составляет 99% стоимости заказа;
  • единственный товар в заказе.

Если вы не можете отгрузить такой товар, отмените заказ. Для этого отправьте запрос методом PUT v2/campaigns/{campaignId}/orders/{orderId}/status и передайте статус заказа CANCELLED с причиной отмены SHOP_FAILED.

Увеличить заказ нельзя

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

Примеры

Товар умещается в коробку

Вот как будет выглядеть запрос, если в одной коробке едут:

  • три единицы одного товара, требующего маркировки;
  • одна единица другого товара, не требущего маркировки.
{
    "boxes": [
        {
            "items": [
                {
                    "id": 123456,
                    "fullCount": 3,
                    "instances": [
                        {
                            "cis": "01030410947874432155Qbag!\u001d93Zjqw"
                        },
                        {
                            "cis": "010304109478gftJ14545762!\u001dhGt264"
                        },
                        {
                            "cis": "010304109478fRs28323ks23!\u001dhet201"
                        }
                    ]
                },
                {
                    "id": 654321,
                    "fullCount": 1
                }
            ]
        }
    ]
}
Товар едет в разных коробках

Вот как будет выглядеть запрос, если товар едет в двух коробках:

{
    "boxes": [
        {
            "items": [
                {
                    "id": 123456,
                    "partialCount": {
                        "current": 1,
                        "total": 2
                    },
                    "instances": [
                        {
                            "cis": "01030410947874432155Qbag!\u001d93Zjqw"
                        }
                    ]
                }
            ]
        },
        {
            "items": [
                {
                    "id": 123456,
                    "partialCount": {
                        "current": 2,
                        "total": 2
                    },
                    "instances": [
                        {
                            "cis": "01030410947874432155Qbag!\u001d93Zjqw"
                        }
                    ]
                }
            ]
        }
    ]
}
Одинаковые товары, где каждый едет в нескольких коробках

Вот как будет выглядеть запрос, если каждый из двух одинаковых товаров едет в двух коробках:

{
    "boxes": [
        {
            "items": [
                {
                    "id": 123456,
                    "partialCount": {
                        "current": 1,
                        "total": 2
                    },
                    "instances": [
                        {
                            "cis": "01030410947874432155Qbag!\u001d93Zjqw"
                        }
                    ]
                }
            ]
        },
        {
            "items": [
                {
                    "id": 123456,
                    "partialCount": {
                        "current": 2,
                        "total": 2
                    },
                    "instances": [
                        {
                            "cis": "01030410947874432155Qbag!\u001d93Zjqw"
                        }
                    ]
                }
            ]
        },
        {
            "items": [
                {
                    "id": 123456,
                    "partialCount": {
                        "current": 1,
                        "total": 2
                    },
                    "instances": [
                        {
                            "cis": "01030410947874432155Qbag!\u001d93Zjqw"
                        }
                    ]
                }
            ]
        },
        {
            "items": [
                {
                    "id": 123456,
                    "partialCount": {
                        "current": 2,
                        "total": 2
                    },
                    "instances": [
                        {
                            "cis": "01030410947874432155Qbag!\u001d93Zjqw"
                        }
                    ]
                }
            ]
        }
    ]
}
Разные товары в разных коробках

Вот как будет выглядеть запрос, если два разных товара разложены по разным коробкам:

{
    "boxes": [
        {
            "items": [
                {
                    "id": 123456,
                    "fullCount": 1
                }
            ]
        },
        {
            "items": [
                {
                    "id": 654321,
                    "fullCount": 1
                }
            ]
        }
    ]
}
⚙️ Лимит: 100 000 запросов в час

Request

PUT

https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/orders/{orderId}/boxes

Path parameters

Name

Description

campaignId

Type: integer

Идентификатор кампании (магазина) — технический идентификатор, который представляет ваш магазин в системе Яндекс Маркета при работе через API. Он однозначно связывается с вашим магазином, но предназначен только для автоматизированного взаимодействия.

Его можно узнать с помощью запроса GET v2/campaigns или найти в кабинете продавца на Маркете. Нажмите на иконку вашего аккаунта → Настройки и в меню слева выберите API и модули:

  • блок Идентификатор кампании;
  • вкладка Лог запросов → выпадающий список в блоке Показывать логи.

⚠️ Не путайте его с:

  • идентификатором магазина, который отображается в личном кабинете продавца;
  • рекламными кампаниями.

Min value: 1

orderId

Type: integer

Идентификатор заказа.

Body

application/json
{
  "boxes": [
    {
      "items": [
        {
          "id": 0,
          "fullCount": 1,
          "partialCount": {},
          "instances": [
            null
          ]
        }
      ]
    }
  ],
  "allowRemove": false
}

Name

Description

boxes

Type: OrderBoxLayoutDTO[]

Список коробок.

Min items: 1

Example
[
  {
    "items": [
      {
        "id": 0,
        "fullCount": 1,
        "partialCount": {
          "current": 1,
          "total": 2
        },
        "instances": [
          {}
        ]
      }
    ]
  }
]

allowRemove

Type: boolean

Передайте true, если вы собираетесь удалить часть товаров из заказа.

Default: false

OrderBoxLayoutPartialCountDTO

Информация о части товара в коробке.

Name

Description

current

Type: integer

Номер части, начиная с 1.

Min value: 1

total

Type: integer

На сколько всего частей разделен товар.

Min value: 2
Example
{
  "current": 1,
  "total": 2
}

Cis

Код идентификации единицы товара в системе «Честный ЗНАК» или «ASL BELGISI» (для продавцов Market Yandex Go).

Не экранируйте косую черту в коде символа-разделителя \u001d

✅ 01030410947874432155Qbag!\u001d93Zjqw

❌ 01030410947874432155Qbag!\\u001d93Zjqw

Косые черты и кавычки в других местах экранируйте по правилам JSON: \\ и \"

Type: string

Example: example

CountryCode

Страна производства в формате ISO 3166-1 alpha-2. Как получить

Type: string

Min length: 2

Max length: 2

Pattern: ^[A-Z]{2}$

Example: RU

BriefOrderItemInstanceDTO

Идентификатор единицы товара.

Заполните только одно поле в зависимости от того, в какой системе маркирован товар.

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

Name

Description

cis

Type: Cis

Код идентификации единицы товара в системе «Честный ЗНАК» или «ASL BELGISI» (для продавцов Market Yandex Go).

Не экранируйте косую черту в коде символа-разделителя \u001d

✅ 01030410947874432155Qbag!\u001d93Zjqw

❌ 01030410947874432155Qbag!\\u001d93Zjqw

Косые черты и кавычки в других местах экранируйте по правилам JSON: \\ и \"

Example: example

countryCode

Type: CountryCode

Страна производства в формате ISO 3166-1 alpha-2. Как получить

Min length: 2

Max length: 2

Pattern: ^[A-Z]{2}$

Example: RU

gtd

Type: string

Грузовая таможенная декларация.

Представляет собой строку из трех чисел, разделенных косой чертой: ХХХХХХХХ/ХХХХХХ/ХХХХХХХ.

Первая часть — код таможни, которая зарегистрировала декларацию на ввезенные товары. Далее — дата и номер декларации.

Example: example

rnpt

Type: string

Регистрационный номер партии товара.

Представляет собой строку из четырех чисел, разделенных косой чертой: ХХХХХХХХ/ХХХХХХ/ХХХХХХХ/ХХХ.

Первая часть — код таможни, которая зарегистрировала декларацию на партию товара. Далее — дата, номер декларации и номер маркированного товара в декларации.

Example: example

uin

Type: string

Уникальный идентификационный номер ювелирного изделия.

Представляет собой число из 16 цифр.

Example: example
Example
{
  "cis": "example",
  "uin": "example",
  "rnpt": "example",
  "gtd": "example",
  "countryCode": "RU"
}

OrderBoxLayoutItemDTO

Информация о товаре в коробке.

Name

Description

id

Type: integer

Идентификатор товара в заказе.

Он приходит в ответе метода POST v1/businesses/{businessId}/orders — параметр id в items.

fullCount

Type: integer

Количество единиц товара в коробке.

Используйте это поле, если в коробке поедут целые товары, не разделенные на части. Не используйте это поле одновременно с partialCount.

Min value: 1

instances

Type: BriefOrderItemInstanceDTO[] | null

Переданные коды маркировки.

Min items: 1

Example
[
  {
    "cis": "example",
    "uin": "example",
    "rnpt": "example",
    "gtd": "example",
    "countryCode": "RU"
  }
]

partialCount

Type: OrderBoxLayoutPartialCountDTO

Информация о части товара в коробке.

Используйте это поле, если в коробке поедет часть большого товара. Не используйте это поле одновременно с fullCount.

Информация о части товара в коробке.

Example
{
  "current": 1,
  "total": 2
}
Example
{
  "id": 0,
  "fullCount": 1,
  "partialCount": {
    "current": 1,
    "total": 2
  },
  "instances": [
    {
      "cis": "example",
      "uin": "example",
      "rnpt": "example",
      "gtd": "example",
      "countryCode": "RU"
    }
  ]
}

OrderBoxLayoutDTO

Информация о коробке.

Name

Description

items

Type: OrderBoxLayoutItemDTO[]

Список товаров в коробке.

Если в коробке едет часть большого товара, в списке может быть только один пункт.

Min items: 1

Example
[
  {
    "id": 0,
    "fullCount": 1,
    "partialCount": {
      "current": 1,
      "total": 2
    },
    "instances": [
      {
        "cis": "example",
        "uin": "example",
        "rnpt": "example",
        "gtd": "example",
        "countryCode": "RU"
      }
    ]
  }
]
Example
{
  "items": [
    {
      "id": 0,
      "fullCount": 1,
      "partialCount": {
        "current": 1,
        "total": 2
      },
      "instances": [
        {
          "cis": "example",
          "uin": "example",
          "rnpt": "example",
          "gtd": "example",
          "countryCode": "RU"
        }
      ]
    }
  ]
}

Responses

200 OK

В ответ придет переданная раскладка с идентификаторами коробок — они понадобятся для запроса ярлыков.

Body

application/json
{
  "status": "OK",
  "result": {
    "boxes": [
      {}
    ]
  }
}

Type: object

All of 2 types

  • Type: ApiResponse

    Стандартная обертка для ответов сервера.

    Example
    {
  "status": "OK"
}
  • Type: object

    result

    Type: OrderBoxesLayoutDTO

    Распределение товаров по коробкам.

    Example
    {
  "boxes": [
    {
      "items": [
        {}
      ],
      "boxId": 0
    }
  ]
}
    Example
    {
  "result": {
    "boxes": [
      {
        "items": [
          null
        ],
        "boxId": 0
      }
    ]
  }
}

ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Type: string

Enum: OK, ERROR

ApiResponse

Стандартная обертка для ответов сервера.

Name

Description

status

Type: ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Enum: OK, ERROR
Example
{
  "status": "OK"
}

EnrichedOrderBoxLayoutDTO

Информация о коробке.

Type: object

All of 2 types

  • Type: OrderBoxLayoutDTO

    Информация о коробке.

    Example
    {
  "items": [
    {
      "id": 0,
      "fullCount": 1,
      "partialCount": {
        "current": 1,
        "total": 2
      },
      "instances": [
        {
          "cis": "example",
          "uin": "example",
          "rnpt": "example",
          "gtd": "example",
          "countryCode": "RU"
        }
      ]
    }
  ]
}
  • Type: object

    boxId

    Type: integer

    Идентификатор коробки.
    Example
    {
  "boxId": 0
}
Example
{
  "items": [
    {
      "id": 0,
      "fullCount": 1,
      "partialCount": {
        "current": 1,
        "total": 2
      },
      "instances": [
        {}
      ]
    }
  ],
  "boxId": 0
}

OrderBoxesLayoutDTO

Распределение товаров по коробкам.

Name

Description

boxes

Type: EnrichedOrderBoxLayoutDTO[]

Список коробок.

Example
[
  {
    "items": [
      {
        "id": 0,
        "fullCount": 1,
        "partialCount": {},
        "instances": [
          null
        ]
      }
    ],
    "boxId": 0
  }
]
Example
{
  "boxes": [
    {
      "items": [
        {}
      ],
      "boxId": 0
    }
  ]
}

400 Bad Request

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

Body

application/json
{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

  • Type: ApiErrorResponse

    Стандартная обертка для ошибок сервера.

    Example
    {
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

ApiErrorDTO

Общий формат ошибки.

Name

Description

code

Type: string

Код ошибки.

Example: example

message

Type: string

Описание ошибки.

Example: example
Example
{
  "code": "example",
  "message": "example"
}

ApiErrorResponse

Стандартная обертка для ошибок сервера.

Type: object

All of 2 types

  • Type: ApiResponse

    Стандартная обертка для ответов сервера.

    Example
    {
  "status": "OK"
}
  • Type: object

    errors

    Type: ApiErrorDTO[] | null

    Список ошибок.

    Min items: 1

    Example
    [
  {
    "code": "example",
    "message": "example"
  }
]
    Example
    {
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}
Example
{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

401 Unauthorized

В запросе не указаны данные для авторизации. Подробнее об ошибке

Body

application/json
{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

  • Type: ApiErrorResponse

    Стандартная обертка для ошибок сервера.

    Example
    {
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

403 Forbidden

Данные для авторизации неверны или доступ к ресурсу запрещен. Подробнее об ошибке

Body

application/json
{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

  • Type: ApiErrorResponse

    Стандартная обертка для ошибок сервера.

    Example
    {
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

404 Not Found

Запрашиваемый ресурс не найден. Подробнее об ошибке

Body

application/json
{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

  • Type: ApiErrorResponse

    Стандартная обертка для ошибок сервера.

    Example
    {
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

420 Method Failure

Превышено ограничение на доступ к ресурсу. Подробнее об ошибке

Body

application/json
{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

  • Type: ApiErrorResponse

    Стандартная обертка для ошибок сервера.

    Example
    {
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

500 Internal Server Error

Внутренняя ошибка Маркета. Подробнее об ошибке

Body

application/json
{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

  • Type: ApiErrorResponse

    Стандартная обертка для ошибок сервера.

    Example
    {
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

No longer supported, please use an alternative and newer version.

Значение cis должно соответствовать регулярному выражению ^(?=.{1,256}$)\u001D?(\(?01\)?\d{14}\(?21\)?([!-~]{6,8}|[!-~]{13}|[!-~]{20})(\u001D\(?240\)?.{1,30})?\u001D\(?9[1,3]\)?.+)$.

Без криптохвоста — ^(?=[!-~]{1,256}$)(\(?01\)?\d{14}\(?21\)?(.{6,8}|.{13}|.{20}))$.

Предыдущая
Информация о заказах
Следующая
Передача внешнего идентификатора заказа