# Returns. Возвраты поставщику > Источник: https://wiki.virtualpos.ru/hc/api/returns > Обновлено: 2026-09-26 Метод возвращает документы «Возврат поставщику» вместе со строками. Документы можно только читать: создание и изменение через API не поддерживаются. > **Примечание:** > Как получить ключ, как формируются запросы и какие бывают ответы и ошибки — в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Здесь описаны только особенности метода `returns`. ## Запрос Все параметры, кроме ключа `apikey` и формата `format`, принимаются и в адресной строке, и в теле POST. ``` GET https://[компания].myvirtualpos.ru/api/returns?apikey=MySecret&days=90&warehouse_id=6&withitems=1 ``` ## Параметры запроса - **id** — Число. Ид документа. Если указан, ищется только этот документ - **external_id** — Строка. Код документа во внешней системе (например, в 1С). Действует, если не указан `id` - **last_id** — Число. Вернуть документы с ид больше указанного: для получения новых документов с прошлого обмена. Действует, если не указаны `id` и `external_id` - **warehouse_id** — Число. Ид точки продаж, с которой оформлен возврат. Если не указан, возвращаются документы всех точек - **ext_warehouse_id** — Строка. Код точки продаж во внешней системе. Действует, если не указан `warehouse_id`. Если точки с таким кодом нет, возвращается пустой список - **date** — Дата `ГГГГММДД`. Документы с этой датой документа - **datefrom**, **dateto** — Дата `ГГГГММДД`. Документы с датой документа с указанной даты и по указанную включительно - **cdatefrom**, **cdateto** — Дата `ГГГГММДД`. То же по дате создания документа в системе - **last_update_date** — Дата `ГГГГММДД`. Документы, изменённые начиная с этой даты. Если указан, ограничение `days` не применяется - **days** — Число. Глубина поиска в днях от текущей даты по дате документа. По умолчанию **30** - **withitems** — `1` — добавить строки документов. По умолчанию возвращаются только шапки - **format** — `json` (по умолчанию) или `xml` Условия объединяются по «и». Даты передаются строго в формате `ГГГГММДД`, иначе метод вернёт ошибку `Incorrect date format`. Документы возвращаются по убыванию `id`: новые первыми. > **Важно:** > **Ограничение `days` действует почти всегда.** Если не указан `last_update_date`, отбираются только документы за последние 30 дней (или за `days`) по дате документа, и это ограничение накладывается вместе со всеми остальными условиями, в том числе `id`, `external_id`, `date` и `datefrom`. Чтобы получить старые документы, добавьте `days` с достаточным значением, например `days=3650`. Значение в ответе `days_limit` показывает выбранную глубину, даже если при заданном `last_update_date` она не применялась. > > При `days=0` ограничение снимается, и метод собирает в одном ответе все документы; на больших базах это может закончиться ошибкой сервера по памяти. ## Статусы документа | Значение | Название | Что означает | | --- | --- | --- | | `draft` | Черновик | Документ наполняется, остатки не менялись | | `accept` | Принят | Возврат проведён, товар списан со склада | ## Структура ответа - **success** — `1` — данные получены - **type** — Тип данных, всегда `returns` - **days_limit** — Число дней глубины поиска: `30` по умолчанию или значение `days` - **count** — Количество документов в ответе - **returns** — Список документов. Каждый обёрнут в объект `return` ### Поля документа Пустые значения в JSON приходят как `null`, в XML — как пустой элемент. - **id** — Число. Ид документа - **external_id** — Строка. Код документа во внешней системе - **guid** — Строка. Уникальный идентификатор документа (GUID) - **docnum** — Строка. Номер документа - **docdate** — Строка. Дата документа, формат `гггг-мм-дд чч:мм:сс` - **status** — Строка. Статус документа, см. раздел «Статусы документа» - **status_name** — Строка. Название статуса на русском - **comment** — Строка. Комментарий - **amount** — Строка. Сумма возврата - **warehouse_id** — Число. Ид точки продаж - **warehouse_external_id** — Строка. Код точки продаж во внешней системе - **supplier_id** — Число. Ид поставщика - **supplier_external_id** — Строка. Код поставщика во внешней системе - **supplier_name**, **supplier_inn**, **supplier_kpp** — Строка. Название, ИНН и КПП поставщика - **supplier_type**, **supplier_type_name** — Ид и название типа поставщика - **supplier_readonly_inflow** — Число. `1` — внутренний поставщик, поступления от которого создаются автоматически - **created_date**, **last_update_date** — Строка. Дата и время создания и последнего изменения - **created_by**, **last_update_by** — Число. Ид пользователя, создавшего и изменившего документ - **items** — Список строк; при `withitems=0` пустой. Каждая строка обёрнута в объект `item` ### Поля строки - **line_id** — Число. Ид строки - **guid** — Строка. Уникальный идентификатор строки (GUID) - **item_id** — Число. Ид товара - **item_ext_id** — Строка. Код товара во внешней системе - **item_name** — Строка. Название товара - **quantity** — Строка. Количество - **barcode** — Строка. Штрихкод - **price** — Строка. Закупочная цена единицы - **amount** — Строка. Сумма по строке - **lot_number** — Строка. Серия (партия) - **manuf_date**, **expir_date** — Строка. Дата изготовления и срок годности. Если не заданы, приходит `0000-00-00` ## Пример ответа ```json { "success": 1, "type": "returns", "days_limit": 90, "count": 1, "returns": [ { "return": { "id": 224, "external_id": "RET-224", "guid": "4DDE87A3-8AC7-DD60-2E7D-1DA863679BF7", "warehouse_id": 7, "docnum": "28.08.26", "docdate": "2026-08-28 00:00:00", "supplier_id": 2, "supplier_name": "Мой поставщик", "supplier_inn": "7805492189", "supplier_kpp": "780501001", "supplier_type": 2, "supplier_type_name": "Внешний поставщик", "supplier_readonly_inflow": 0, "amount": "3500.00", "status": "accept", "status_name": "Принят", "comment": "Брак", "supplier_external_id": "S-2", "warehouse_external_id": "WH-7", "created_date": "2026-08-28 13:58:22", "created_by": 23, "last_update_date": "2026-08-28 14:21:27", "last_update_by": 23, "items": [ { "item": { "line_id": 4927, "guid": "5AEEE85D-A100-D900-6A0E-D7BD519F60AE", "item_id": 34622, "item_ext_id": "SKU-34622", "item_name": "Шампунь для глубокого очищения 1000 мл", "quantity": "1.000", "barcode": null, "price": "1250.0000", "amount": "1250.00", "manuf_date": "0000-00-00", "expir_date": "0000-00-00", "lot_number": "" } } ] } } ] } ``` Тот же ответ при `format=xml` (сокращённо): ```xml 1 returns 90 1 224 accept 4927 34622 1.000 ``` ## Примеры запросов | Задача | Запрос | | --- | --- | | Возвраты за последние 30 дней (шапки) | `/api/returns?apikey=MySecret` | | Возвраты точки за квартал со строками | `/api/returns?apikey=MySecret&days=90&warehouse_id=6&withitems=1` | | Один документ по ид | `/api/returns?apikey=MySecret&id=224&days=3650&withitems=1` | | Новые документы после последнего полученного | `/api/returns?apikey=MySecret&last_id=220&days=90` | | Документы, изменённые с указанной даты | `/api/returns?apikey=MySecret&last_update_date=20260901` | | Документы точки по её коду в 1С | `/api/returns?apikey=MySecret&ext_warehouse_id=WH-7&days=90` | ## Ошибки Ошибка авторизации и общие ошибки описаны в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). | Сообщение | Причина | Что делать | | --- | --- | --- | | Incorrect date format '…'. Valid format is: YYYYMMDD | Дата в параметре не в формате `ГГГГММДД` | Передайте дату как `20260901` | Если по условиям ничего не найдено, метод возвращает успешный ответ с `count` равным `0` и пустым списком `returns`. ## Связанные разделы - [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки - [Supplier. Поставщики](https://wiki.virtualpos.ru/hc/api/supplier) — Справочник поставщиков - [Warehouse. Точки продаж](https://wiki.virtualpos.ru/hc/api/warehouse) — Справочник точек продаж