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

POST /v1/return/dbs/timeslot/set

POST/v1/return/dbs/timeslot/set

Перенос слота курьера для забора товара по возвратной заявке.

Тело запроса

return_id
string
required

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

delivery_date_begin
string
required

Дата и время начала слота забора (date-time, RFC3339, timezone обязателен).

delivery_date_end
string
required

Дата и время окончания слота забора (date-time, RFC3339, timezone обязателен).

changed_at
string
required

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

changed_by
string

Инициатор переноса слота.

MERCHANT: продавец

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

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

Комментарий к переносу слота. Например: нет курьера на выбранную дату; клиент попросил другой день.

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

200A successful response.
application/json
object
return_id
string
required

Идентификатор заявки на возврат. Всегда присутствует (успех и ошибка).

returns
object

Карточка заявки с обновлённым delivery_date (только при успехе).

Показать свойства
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

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

errors
array

Структурированные ошибки (только при неуспехе). Коды — ReturnTimeslotValidationErrorCode.

При ошибке — только return_id + errors; returns отсутствует.

Ошибка валидации/бизнеса для scope «ReturnTimeslotUpdate» (POST /v1/return/dbs/timeslot/set).

Допустимые field: return_id, delivery_date_begin, delivery_date_end, changed_at, changed_by, comment.

Для бизнес-правил витрины: code=STOREFRONT_RULE_VIOLATION.

Ошибка валидации/бизнеса для scope «ReturnTimeslotUpdate» (POST /v1/return/dbs/timeslot/set).

Допустимые field: return_id, delivery_date_begin, delivery_date_end, changed_at, changed_by, comment.

Для бизнес-правил витрины: code=STOREFRONT_RULE_VIOLATION.

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

Путь к полю запроса.

code
string
required

Код ошибки.

REQUIRED: Поле отсутствует или пустое, но обязательно

INVALID_TYPE: Неверный JSON-тип

INVALID_FORMAT: Неверный формат значения

INVALID_ENUM: Значение не из допустимого набора

INVALID_DATE_TIME: Не RFC3339 или нет timezone

INVALID_RANGE: Некорректный диапазон

NOT_FOUND: Сущность не найдена (уточняется полем field)

STATUS_NOT_ALLOWED: Операция недоступна в текущем статусе

CONFLICT: Конфликт состояния

STOREFRONT_RULE_VIOLATION: Отклонено бизнес-правилом витрины (детали в message)

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

Текст для клиента. Для STOREFRONT_RULE_VIOLATION — описание правила.

Ошибки

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/dbs/timeslot/set
1curl https://api.omninet.ru/v1/return/dbs/timeslot/set \2  --request POST \3  --header 'Content-Type: application/json' \4  --data '{5  "return_id": "string",6  "delivery_date_begin": "2026-08-16T10:00:00+03:00",7  "delivery_date_end": "2026-08-16T14:00:00+03:00",8  "changed_at": "2026-07-02T10:25:00+02:00",9  "changed_by": "MERCHANT",10  "comment": "string"11}'
{
  "return_id": "string",
  "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"
      }
    ]
  },
  "errors": [
    {
      "field": "delivery_date_begin",
      "code": "INVALID_DATE_TIME",
      "message": "Ожидается RFC3339 с timezone"
    }
  ]
}

A successful response.