Справочник API

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

Возврат и обмен — это заявки со своим жизненным циклом. Ключевое правило: товар встаёт на склад в момент приёмки, а не в момент оформления заявки. До приёмки вещь физически едет к вам и на остатках не отражается.

GET/orders/admin/order-returns

Список возвратов

Возвраты и обмены бренда с фильтрами по виду и статусу.

Доступ:Ключ интеграцииСессия сотрудникаПраво:view_orders или manage_orders

Параметры запроса

Параметр	Тип	Обязателен	Описание
`kind`	string	нет	Вид заявки.return · exchange
`status`	string	нет	Статус заявки.
`identified`	string	нет	Только опознанные или только неопознанные возвраты. Не boolean — сравнивается буквально с этими строками, true/false ничего не отфильтруют.identified · unidentified
`search`	string	нет	Поиск по номеру заказа или контрагенту.
`limit`	number	нетпо умолчанию 50	От 1 до 200.
`offset`	number	нетпо умолчанию 0	Сколько пропустить.

Поля ответа

Поле	Тип	Описание
`items`	array	Заявки.
`total`	number	Всего по фильтру.
`limit`	number	Эхо применённого лимита.
`offset`	number	Эхо применённого сдвига.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
403	`{"error":"Forbidden: Missing permission view_orders"}`	Нет права на чтение заказов.	—

GET/orders/admin/order-return/{id}

Карточка возврата

Одна заявка: состав, статус, связанный заказ, для обмена — дочерний заказ.

Доступ:Ключ интеграцииСессия сотрудникаПраво:view_orders или manage_orders

Параметры пути

Параметр	Тип	Обязателен	Описание
`id`	number	да	Идентификатор заявки.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
404	`{"error":"Возврат не найден"}`	Заявки нет или она чужого бренда.	—

PATCH/orders/admin/order-return/{id}/status

Сменить статус возврата

Переводит заявку на следующую стадию. Приёмка возвращает товар на склад.

Доступ:Ключ интеграцииСессия сотрудникаПраво:manage_orders

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

Параметры пути

Параметр	Тип	Обязателен	Описание
`id`	number	да	Идентификатор заявки.

Тело запроса

Параметр	Тип	Обязателен	Описание
`status`	string	да	Новый статус. Список переходов — в справочнике значений.
`comment`	string	нет	Комментарий к смене статуса.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
400	`{"error":"Недопустимый переход статуса: <из> -> <в>"}`	Такой переход не разрешён.	Сверьтесь с таблицей переходов в справочнике значений.
404	`{"error":"Возврат не найден"}`	Заявки нет или она чужого бренда.	—

POST/orders/admin/order/{id}/return

Оформить возврат

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

Доступ:Ключ интеграцииСессия сотрудникаПраво:manage_orders

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

Параметры пути

Параметр	Тип	Обязателен	Описание
`id`	number	да	Идентификатор заказа.

Тело запроса

Параметр	Тип	Обязателен	Описание
`mode`	string	да	Способ оформления.manual · auto
`returnLines`	array	да	Позиции: orderItemId и quantity.
`returnMethod`	string	нет	Способ, которым товар едет назад — влияет на выбор курьера/ПВЗ.
`trackMode`	string	нет	Откуда берётся трек возврата. new — платформа заводит новую отправку; existing и manual сами трек не заводят.new · existing · manual
`trackingNumber`	string	нет	Трек-номер — для trackMode existing/manual, если он уже известен.
`senderType`	string	нет	Кто фактически отправляет посылку назад.
`shipmentPoint`	string	нет	Пункт выдачи, куда покупатель сдаст посылку. Обязателен, только когда одновременно trackMode=new, mode=manual и returnMethod=cdek_pvz — и то лишь если у заказа ещё нет своего pvzCode: если он есть, платформа берёт его сама, и shipmentPoint можно не присылать.
`comment`	string	нет	Комментарий.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
400	`{"error":"Возврат доступен только для оплаченных доставленных заказов (статус «Доставлен» / СДЭК «Вручен»)."}`	Заказ не оплачен или ещё не доставлен.	—
400	`{"error":"Укажите позиции для возврата"}`	Пустой список позиций.	—
400	`{"error":"Количество возврата больше заказанного (<товар>)"}`	Просят вернуть больше, чем покупали.	—
400	`{"error":"Автовозврат СДЭК доступен только для полного возврата по заказу с ПВЗ (не курьер). Используйте ручной режим."}`	Автоматический возврат запрошен для курьерской доставки или для части заказа.	—
400	`{"error":"Укажите ПВЗ, куда клиент сдаст возврат"}`	Ручной возврат без пункта выдачи.	—