Возвраты

Возврат DBS

Покупатель оформляет возврат на витрине. Мерчант опрашивает POST /v1/return/list, рассматривает заявку и меняет статус через POST /v1/return/dbs/status/set.

Типичная цепочка рассмотрения: NEW → PENDING / DELIVERY_APPROVED → DELIVERING → DELIVERED → APPROVED (или REJECT_REFUND). Другие статусы из спецификации: NEEDS_INFO, REJECT_PENDING, PARTIAL_REFUND, MONEY_RETURNED_BY_MERCHANT, DELIVERY_TO_CLIENT, CANCELED, CLOSED.

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

В карточке заявки (return/list и return/get) есть поле return_request_reviewed_at — дата и время (RFC3339), до которого мерчант должен рассмотреть заявку. Если решения нет, заявка принимается автоматически: деньги уходят покупателю без участия продавца.

Практика опроса: return/list с filter.status: ["NEW"], разбирать заявки по возрастанию return_request_reviewed_at. Заявки без решения к дедлайну считать проигранными — оспаривать их через API нечем.

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

Обратная доставка: как товар едет назад

Параметры обратной доставки лежат в объекте delivery карточки заявки. Обязательные поля — delivery_type и payer; их задаёт витрина при создании заявки.

Код сдачи, штрихкод и трек мерчант может передать сам — те же поля есть в запросе return/dbs/status/set (return_code, return_barcode_url, return_barcode_base64, tracking_number). recommendation: передавать их вместе со статусом DELIVERY_APPROVED, чтобы покупатель получил инструкцию сдачи сразу после одобрения. Кто генерирует код и ШК — мерчант или витрина — контракт не фиксирует, согласуйте при подключении.

Три ветки сдачи

JSON — сдача через ПВЗ: одобрили и выдали инструкцию покупателю

{
  "return_id": "5001",
  "status": "DELIVERY_APPROVED",
  "changed_at": "2026-06-20T12:00:00+03:00",
  "return_code": "704512",
  "return_barcode_url": "https://cdn.example.com/returns/barcode-ret-5001.png"
}

JSON — сдача почтой, режим MERCHANT_BOOKED: передали трек

{
  "return_id": "5002",
  "status": "DELIVERY_APPROVED",
  "changed_at": "2026-06-20T12:10:00+03:00",
  "tracking_number": "80091234567890"
}

JSON — POST /v1/return/dbs/timeslot/set (перенос слота забора)

ReturnTimeslotUpdateRequest.required: return_id, delivery_date_begin, delivery_date_end, changed_at. changed_by (MERCHANT / CLIENT) и comment — опционально.

{
  "return_id": "5001",
  "delivery_date_begin": "2026-06-21T10:00:00+03:00",
  "delivery_date_end": "2026-06-21T14:00:00+03:00",
  "changed_at": "2026-06-20T13:00:00+03:00",
  "changed_by": "MERCHANT",
  "comment": "Нет курьера на выбранную дату"
}

Чего в контракте нет: сроков, за которые покупатель обязан сдать товар; автоматической смены статуса заявки по треку обратного отправления; отдельного метода «стереть» код или трек. Статусы DELIVERING и DELIVERED по возврату ставит мерчант.

JSON — POST /v1/return/list

ReturnListRequest.required: filter, limit. cursor опционален.

{
  "cursor": "",
  "limit": 100,
  "filter": {
    "status": ["NEW"]
  }
}

JSON — POST /v1/return/dbs/status/set

Обязательны return_id, status, changed_at. При REJECT_PENDING / REJECT_REFUND передайте merchant_comment.code и description.

{
  "return_id": "5001",
  "status": "DELIVERY_APPROVED",
  "changed_at": "2026-06-20T12:00:00+03:00"
}

{
  "return_id": "5001",
  "status": "APPROVED",
  "changed_at": "2026-06-22T16:40:00+03:00"
}

{
  "return_id": "5001",
  "status": "REJECT_REFUND",
  "changed_at": "2026-06-22T16:40:00+03:00",
  "merchant_comment": {
    "code": "DEFECT_NOT_CONFIRMED",
    "description": "Заявленный брак не подтвердился при осмотре"
  }
}

Причина возврата от покупателя — в карточке reason.code (return/list / return/get). Отказ продавца — merchant_comment.code.

Причины возврата (reason.code)

Коды отказа продавца (merchant_comment.code)

Обязательны при REJECT_PENDING и REJECT_REFUND. При NEEDS_INFO код не передаётся. При OTHER обязателен merchant_comment.description.