Список заявок на возвраты клиента

POST /v1/return/list

POST/v1/return/list

Одна заявка соответствует одному заказу продавца (1 merchant_order_id = 1 return_id).

В ответе список заявок на возврат по товарам с детализацией причин возврата товара и прикрепленным фото/видео.

Тело запроса

filter
object
required

Фильтр. Если поле фильтра не передано, равно null или передан пустой массив [], фильтрация по этому полю не применяется. При одновременном указании нескольких фильтров условия объединяются по AND.

Показать свойства
status
array

Фильтр по статусам возврата.

NEW: новая заявка (создана витриной; ждёт, пока мерчант возьмёт в работу)

PENDING: мерчант взял заявку в работу (NEW → PENDING через status/set)

NEEDS_INFO: требуется дополнительная информация

REJECT_PENDING: отказ в рассмотрении заявки

PARTIAL_REFUND: предложена денежная компенсация

DELIVERY_APPROVED: доставка возврата одобрена (перед отправкой покупателем)

DELIVERING: отправлен покупателем

DELIVERED: получен продавцом (время на проверку товара)

APPROVED: подтверждён к возврату ДС продавцом

MONEY_RETURNED_BY_MERCHANT: деньги возвращены продавцом (ювелирка / выплата мерчантом вне стандартной выплаты витрины)

REJECT_REFUND: отказ от возврата ДС продавцом

DELIVERY_TO_CLIENT: возврат товара клиенту. Обратную доставку клиенту всегда оплачивает мерчант

CANCELLED: отменено по времени или инициативе покупателя

CLOSED: заявка закрыта. Может поставить мерчант через status/set или витрина / SYSTEM

Допустимые значения
NEWPENDINGNEEDS_INFOREJECT_PENDINGPARTIAL_REFUNDDELIVERY_APPROVEDDELIVERINGDELIVEREDAPPROVEDMONEY_RETURNED_BY_MERCHANTREJECT_REFUNDDELIVERY_TO_CLIENTCANCELLEDCLOSED
return_id
array

Фильтр по идентификаторам заявок на возврат.

client_order_id
array

Фильтр по идентификаторам заказа клиента. Удобно вытащить все заявки возврата по одному client_order_id, когда несколько merchant_order_id (отправлений) относятся к одному клиентскому заказу.

merchant_order_id
array

Фильтр по идентификаторам заказа продавца.

created_at
object

Фильтр по периоду создания заявки.

Показать свойства
since
string

Начало периода (date-time, RFC3339). Формат RFC3339 с обязательным timezone (пример: 2026-07-02T10:25:00+02:00). Несоблюдение формата может привести к непредсказуемому поведению системы и проблемам с заказами.

to
string

Конец периода (date-time, RFC3339). Формат RFC3339 с обязательным timezone (пример: 2026-07-02T10:25:00+02:00). Несоблюдение формата может привести к непредсказуемому поведению системы и проблемам с заказами.

cursor
string

Курсор начала отсчёта.

limit
integer
required

Размер страницы. min = 1; max = 300; default = 100.

Успешный ответ

200A successful response.
application/json
object
returns
array
required

Элементы списка. Возвраты с недоступными или несуществующими return_id в ответ не возвращаются.

ReturnListItem

Показать свойства

ReturnListItem

return_id
string
required

Идентификатор заявки на возврат. (1 заказ = 1 заявка).

merchant_order_id
string
required

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

client_order_id
string
required

Идентификатор заказа клиента. Несколько merchant_order_id могут делить один client_order_id.

location_id
string
required

Идентификатор локации (склада) прямого отправления исходного заказа продавца.

Не путать с delivery.return_location_id (ПВЗ сдачи возврата).

Помогает сверять posting при одинаковых товарах без маркировки.

product_id
string

Идентификатор товара в системе маркетплейса.

offer_id
string

Идентификатор товара в системе продавца — артикул.

status
string
required

Статус возврата.

NEW: новая заявка (создана витриной; ждёт, пока мерчант возьмёт в работу)

PENDING: мерчант взял заявку в работу (NEW → PENDING через status/set)

NEEDS_INFO: требуется дополнительная информация

REJECT_PENDING: отказ в рассмотрении заявки

PARTIAL_REFUND: предложена денежная компенсация

DELIVERY_APPROVED: доставка возврата одобрена (перед отправкой покупателем)

DELIVERING: отправлен покупателем

DELIVERED: получен продавцом (время на проверку товара)

APPROVED: подтверждён к возврату ДС продавцом

MONEY_RETURNED_BY_MERCHANT: деньги возвращены продавцом (ювелирка / выплата мерчантом вне стандартной выплаты витрины)

REJECT_REFUND: отказ от возврата ДС продавцом

DELIVERY_TO_CLIENT: возврат товара клиенту. Обратную доставку клиенту всегда оплачивает мерчант

CANCELLED: отменено по времени или инициативе покупателя

CLOSED: заявка закрыта. Может поставить мерчант через status/set или витрина / SYSTEM

Допустимые значения
NEWPENDINGNEEDS_INFOREJECT_PENDINGPARTIAL_REFUNDDELIVERY_APPROVEDDELIVERINGDELIVEREDAPPROVEDMONEY_RETURNED_BY_MERCHANTREJECT_REFUNDDELIVERY_TO_CLIENTCANCELLEDCLOSED
reason
object
required

Причина возврата и описание от покупателя.

Показать свойства
code
string
required

Код причины.

DEFECT: брак / ненадлежащее качество

POOR_QUALITY: низкое качество изготовления, материала

WRONG_ITEM: привезли не то

NOT_AS_DESCRIBED: не соответствует описанию

INCOMPLETE: неполная комплектация

DAMAGED_IN_DELIVERY: повреждён при доставке

CHANGED_MIND: передумал

SIZE_COLOR_FIT: не подошёл размер / цвет / фасон

SIGNS_OF_USE: товар с признаками использования (как заявлено покупателем / зафиксировано при приёмке на витрине)

NOT_DELIVERED: товар не был доставлен

EXPIRY_ISSUES: проблемы со сроком годности

SUSPECTED_COUNTERFEIT: подозрение на контрафакт

OTHER: прочее

Допустимые значения
DEFECTPOOR_QUALITYWRONG_ITEMNOT_AS_DESCRIBEDINCOMPLETEDAMAGED_IN_DELIVERYCHANGED_MINDSIZE_COLOR_FITSIGNS_OF_USENOT_DELIVEREDEXPIRY_ISSUESSUSPECTED_COUNTERFEITOTHER
description
string

Описание ситуации от покупателя.

product_name
string
required

Название товара.

client_attachments
array

Фото или видео от покупателя (вложения заявки).

merchant_attachments
array

Вложения мерчанта: фото осмотра, видео, акт.

Вложение мерчанта (фото осмотра, видео или акт).

Показать свойства
url
string
required

Ссылка на файл.

kind
string
required

Тип вложения.

PHOTO: фото осмотра

VIDEO: видео осмотра

ACT: акт

Допустимые значения
PHOTOVIDEOACT
delivery
object
required

Параметры обратной доставки.

Показать свойства
delivery_type
string
required

Тип обратной доставки.

COURIER: курьер. Слот выбирает клиент на витрине при создании заявки; курьера всегда бронирует мерчант со своей стороны по этой заявке. Перенос слота — return/dbs/timeslot/set

PICKUP_POINT: сдача в пункт выдачи

RUSSIAN_POST: Почта России. Режим CLIENT_SELF — трек от клиента; MERCHANT_BOOKED — партнёр бронирует после фото и передаёт трек/ШК в status/set. Фото чека ПР (если клиент платил сам) — в client_attachments

Допустимые значения
COURIERPICKUP_POINTRUSSIAN_POST
address_tail
string

Адрес в текстовом формате. Обязателен при delivery_type = COURIER. Формат: «196653, Россия, г. Санкт-Петербург, г. Колпино, ул. Октябрьская, д. 77/27, подъезд 1, этаж 3, кв. 12».

comment
string

Комментарий к адресу обратной доставки.

return_location_id
string

Идентификатор локации (ПВЗ). Для сдачи смотрите is_accepts_returns на локации. Не используется при RUSSIAN_POST.

return_code
string

Код сдачи возврата. Используется клиентом для передачи заказа на точке/курьеру.

return_barcode_url
string

Ссылка на изображение штрихкода возврата. Используется клиентом для передачи заказа на точке/курьеру.

return_barcode_base64
string

Изображение штрихкода возврата в Base64. Используется клиентом для передачи заказа на точке/курьеру.

tracking_number
string

Трек-номер обратной отправления. Используется для отслеживания статуса возвратного заказа.

payer
string
required

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

CLIENT: платит покупатель

MERCHANT: платит продавец. При RUSSIAN_POST покупатель часто платит на почте, затем сумма компенсируется по фото чека ПР в client_attachments

Допустимые значения
CLIENTMERCHANT
cost
object

Стоимость обратной доставки (сумма и валюта; не входит в ReturnMoneyBreakdown возврата ДС клиенту).

Показать свойства
value
integer
required

Сумма, значение умноженное на 100 (например 500.00 ₽ → 50000).

currency_code
string
required

Валюта.

RUB: Российский рубль

BYN: Белорусский рубль

KZT: Тенге

EUR: Евро

USD: Доллар США

CNY: Юань

Допустимые значения
RUBBYNKZTEURUSDCNY
delivery_date
object

Слот забора курьера.

Показать свойства
delivery_date_begin
string
required

Дата и время начала доставки (date-time, RFC3339). Передается локальное время. Формат RFC3339 с обязательным timezone (пример: 2026-07-02T10:25:00+02:00). Несоблюдение формата может привести к непредсказуемому поведению системы и проблемам с заказами.

delivery_date_end
string
required

Ожидаемая дата доставки (date-time, RFC3339). Передается локальное время. Формат RFC3339 с обязательным timezone (пример: 2026-07-02T10:25:00+02:00). Несоблюдение формата может привести к непредсказуемому поведению системы и проблемам с заказами.

return_request_reviewed_at
string

Дата и время, до которого нужно рассмотреть заявку, иначе она будет принята автоматически (date-time, RFC3339). Формат RFC3339 с обязательным timezone (пример: 2026-07-02T10:25:00+02:00). Несоблюдение формата может привести к непредсказуемому поведению системы и проблемам с заказами.

created_at
string
required

Дата создания заявки (date-time, RFC3339). Формат RFC3339 с обязательным timezone (пример: 2026-07-02T10:25:00+02:00). Несоблюдение формата может привести к непредсказуемому поведению системы и проблемам с заказами.

money
object
required

Разбивка сумм к возврату (валюта один раз в currency_code).

Показать свойства
currency_code
string
required

Валюта всех сумм в этом объекте.

RUB: Российский рубль

BYN: Белорусский рубль

KZT: Тенге

EUR: Евро

USD: Доллар США

CNY: Юань

Допустимые значения
RUBBYNKZTEURUSDCNY
product
integer

Стоимость товара к возврату (×100).

original_delivery
integer

Стоимость прямой доставки заказа (справочно; обычно не входит в total к выплате клиенту), ×100.

services
array

Суммы по услугам заказа (код + amount ×100), если применимо.

Сумма по одной услуге (код + amount). Используется в money.services и money.partial_services / status/set.partial_services.

Показать свойства
code
string
required

Код услуги (например prr_option: lift, stairs, none, delivery_default; или иной код услуги из заказа).

amount
integer
required

Сумма, значение умноженное на 100.

partial_product
integer

Частичный возврат ДС за товар при PARTIAL_REFUND (×100).

partial_delivery
integer

Частичный возврат ДС за доставку при PARTIAL_REFUND (×100).

partial_services
array

Частичный возврат ДС за услуги при PARTIAL_REFUND (код + amount ×100).

Сумма по одной услуге (код + amount). Используется в money.services и money.partial_services / status/set.partial_services.

Показать свойства
code
string
required

Код услуги (например prr_option: lift, stairs, none, delivery_default; или иной код услуги из заказа).

amount
integer
required

Сумма, значение умноженное на 100.

total
integer
required

Итого к выплате клиенту (×100).

money_returned
integer

Уже фактически выплачено (×100).

merchant_comment
object

Комментарий или отказ продавца (code + description).

Показать свойства
code
string

Код отказа. Обязателен при REJECT_PENDING и REJECT_REFUND; при NEEDS_INFO не передаётся.

NON_RETURNABLE_CATEGORY: невозвратная категория (fallback, если заявка дошла до продавца)

USED_OR_DAMAGED_BY_BUYER: следы использования / порча клиентом

DEFECT_NOT_CONFIRMED: заявленный брак / проблема не подтвердились при осмотре или экспертизе

APPEARANCE_COMPROMISED: нарушен товарный вид

PACKAGING_OR_SEALS_COMPROMISED: нарушена упаковка / сняты пломбы или ярлыки

INCOMPLETE_KIT: нарушена комплектация по вине покупателя

WARRANTY_EXPIRED: истёк гарантийный срок

WARRANTY_TERMS_VIOLATED: нарушены условия гарантии / эксплуатации

DEVICE_ACTIVATED: устройство или ПО активировано

CUSTOMER_MISSED_COURIER: клиент не принял курьера (не вышел на связь / отсутствовал по адресу)

RETURN_METHOD_NOT_APPLICABLE: выбранный способ возврата неприменим (например, ПВЗ недоступен — только курьер); типично при REJECT_PENDING

INCORRECT_RETURN_REASON_SPECIFIED: некорректно указана причина возврата

OTHER: иное (обязателен merchant_comment.description)

Допустимые значения
NON_RETURNABLE_CATEGORYUSED_OR_DAMAGED_BY_BUYERDEFECT_NOT_CONFIRMEDAPPEARANCE_COMPROMISEDPACKAGING_OR_SEALS_COMPROMISEDINCOMPLETE_KITWARRANTY_EXPIREDWARRANTY_TERMS_VIOLATEDDEVICE_ACTIVATEDCUSTOMER_MISSED_COURIERRETURN_METHOD_NOT_APPLICABLEINCORRECT_RETURN_REASON_SPECIFIEDOTHER
description
string

Текст для покупателя — запрос доп. информации (NEEDS_INFO) или пояснение отказа. Обязателен при NEEDS_INFO, REJECT_PENDING, REJECT_REFUND; при code = OTHER.

status_history
array
required

История статусов заявки.

Запись в истории статусов заявки.

Показать свойства
changed_at
string
required

Время смены статуса (date-time, RFC3339, timezone обязателен).

status
string
required

Статус, в который перешла заявка.

NEW: новая заявка (создана витриной; ждёт, пока мерчант возьмёт в работу)

PENDING: мерчант взял заявку в работу (NEW → PENDING через status/set)

NEEDS_INFO: требуется дополнительная информация

REJECT_PENDING: отказ в рассмотрении заявки

PARTIAL_REFUND: предложена денежная компенсация

DELIVERY_APPROVED: доставка возврата одобрена (перед отправкой покупателем)

DELIVERING: отправлен покупателем

DELIVERED: получен продавцом (время на проверку товара)

APPROVED: подтверждён к возврату ДС продавцом

MONEY_RETURNED_BY_MERCHANT: деньги возвращены продавцом (ювелирка / выплата мерчантом вне стандартной выплаты витрины)

REJECT_REFUND: отказ от возврата ДС продавцом

DELIVERY_TO_CLIENT: возврат товара клиенту. Обратную доставку клиенту всегда оплачивает мерчант

CANCELLED: отменено по времени или инициативе покупателя

CLOSED: заявка закрыта. Может поставить мерчант через status/set или витрина / SYSTEM

Допустимые значения
NEWPENDINGNEEDS_INFOREJECT_PENDINGPARTIAL_REFUNDDELIVERY_APPROVEDDELIVERINGDELIVEREDAPPROVEDMONEY_RETURNED_BY_MERCHANTREJECT_REFUNDDELIVERY_TO_CLIENTCANCELLEDCLOSED
changed_by
string
required

Кто перевёл статус.

MERCHANT: продавец

CLIENT: покупатель

VITRINA: витрина

SYSTEM: платформа (авто-переход)

Допустимые значения
MERCHANTCLIENTVITRINASYSTEM
comment
string

Комментарий к переходу (если был).

next_cursor
string

Курсор начала отсчёта.

total
integer

Общее количество записей.

Ошибки

400Некорректный запрос
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
401Ошибка авторизации
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
429Превышен лимит запросов
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
500Внутренняя ошибка сервера
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
defaultОшибка (неожиданная или прочие)
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
POST/v1/return/list
1curl https://api.omninet.ru/v1/return/list \2  --request POST \3  --header 'Content-Type: application/json' \4  --data '{5  "filter": {6    "status": [7      "NEW"8    ],9    "return_id": [10      "string"11    ],12    "client_order_id": [13      "string"14    ],15    "merchant_order_id": [16      "string"17    ],18    "created_at": {19      "since": "2026-07-02T10:25:00+02:00",20      "to": "2026-07-02T10:25:00+02:00"21    }22  },23  "cursor": "string",24  "limit": 025}'
{
  "returns": [
    {
      "return_id": "string",
      "merchant_order_id": "string",
      "client_order_id": "string",
      "location_id": "string",
      "product_id": "string",
      "offer_id": "string",
      "status": "NEW",
      "reason": {
        "code": "string",
        "description": "string"
      },
      "product_name": "string",
      "client_attachments": [
        "string"
      ],
      "merchant_attachments": [
        {
          "url": "https://cdn.example.com/returns/inspect-R-10001.jpg",
          "kind": "string"
        }
      ],
      "delivery": {
        "delivery_type": "string",
        "address_tail": "string",
        "comment": "string",
        "return_location_id": "string",
        "return_code": "string",
        "return_barcode_url": "https://cdn.example.com/returns/barcode-ret-1001.png",
        "return_barcode_base64": "string",
        "tracking_number": "string",
        "payer": "string",
        "cost": {
          "value": 50000,
          "currency_code": "RUB"
        }
      },
      "delivery_date": {
        "delivery_date_begin": "2026-07-02T10:25:00+02:00",
        "delivery_date_end": "2026-07-02T10:25:00+02:00"
      },
      "return_request_reviewed_at": "2026-07-02T10:25:00+02:00",
      "created_at": "2026-07-02T10:25:00+02:00",
      "money": {
        "currency_code": "RUB",
        "product": 1499000,
        "original_delivery": 35000,
        "services": [
          {
            "code": "lift",
            "amount": 50000
          }
        ],
        "partial_product": 200000,
        "partial_delivery": 0,
        "partial_services": [
          {
            "code": "lift",
            "amount": 50000
          }
        ],
        "total": 1499000,
        "money_returned": 0
      },
      "merchant_comment": {
        "code": "string",
        "description": "string"
      },
      "status_history": [
        {
          "changed_at": "2026-08-10T11:00:00+03:00",
          "status": "NEW",
          "changed_by": "string",
          "comment": "string"
        }
      ]
    }
  ],
  "next_cursor": "string",
  "total": 0
}

A successful response.