# Orders. Заказы

> Источник: https://wiki.virtualpos.ru/hc/api/orders  
> Обновлено: 2026-11-05

Методы для работы с заказами покупателей: получение заказов клиента, точки продаж или конкретного заказа, создание заказа, изменение его данных, добавление, изменение и удаление строк, справочники типов оплаты и доставки.

> **Примечание:**
> Как получить ключ, как формируются запросы и какие бывают ответы и ошибки — в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Здесь описаны только особенности методов раздела `orders`.

## Методы

| Метод | Адрес | Что делает |
| --- | --- | --- |
| Типы оплаты | `/api/orders/get_payment_types` | Справочник доступных типов оплаты |
| Типы доставки | `/api/orders/get_delivery_types` | Справочник доступных типов доставки |
| Заказы | `/api/orders` | Возвращает заказы клиента или всех клиентов |
| Один заказ | `/api/orders/get_order` | Возвращает заказ по ид или коду |
| Создать заказ | `/api/orders/add_order` | Создаёт заказ клиента со строками |
| Изменить заказ | `/api/orders/update_order` | Меняет данные заказа |
| Добавить строки | `/api/orders/add_orders_item` | Добавляет строки в заказ |
| Изменить строки | `/api/orders/update_order_item` | Меняет строки заказа |
| Удалить строки | `/api/orders/delete_orders_item` | Удаляет строки заказа |

> **Важно:**
> **Где передавать параметры.** Ключ `apikey` и формат `format` принимаются и в адресной строке, и в теле POST-запроса. Параметры `id` и `external_id` в методах `update_order`, `add_orders_item`, `update_order_item` и `delete_orders_item` читаются **только из адресной строки (GET)**; в остальных методах их можно передавать и в теле POST. Данные заказа и строк передаются в параметрах `order` и `items` в формате JSON: используйте POST.
>
> **Что означают `id` и `external_id`.** В методах `orders` и `add_order` это идентификаторы **клиента**, а в остальных методах — идентификаторы **заказа**. Код заказа во внешней системе (`external_id`) хранится в поле `guid` заказа.

## Справочники

```
GET https://[компания].myvirtualpos.ru/api/orders/get_payment_types?apikey=MySecret
GET https://[компания].myvirtualpos.ru/api/orders/get_delivery_types?apikey=MySecret
```

Методы возвращают только доступные к выбору типы. Ид из этих справочников указывается в `payment_type_id` и `delivery_type_id` при создании заказа.

```json
{
  "success": 1,
  "payment_types": [
    { "type": { "id": 1, "name": "Оплата при получении" } },
    { "type": { "id": 2, "name": "Оплата онлайн" } }
  ]
}
```

Для типов доставки список приходит в поле `delivery_types`, структура такая же. Если типов нет, `success` равен `0`, а список — `null`.

## Получение заказов

```
GET https://[компания].myvirtualpos.ru/api/orders?apikey=MySecret&id=40823&days=90
```

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

- **id** — Число. Ид **клиента**: вернутся заказы этого клиента. Если не указан вместе с `external_id`, возвращаются заказы всех клиентов
- **external_id** — Строка. Код клиента во внешней системе. Работает так же, как `id`
- **warehouse_id** — Число. Ид точки продаж: вернутся заказы, которые выдаются из этой точки
- **ext_warehouse_id** — Строка. Код точки продаж во внешней системе. Используется, если не указан `warehouse_id`. Если точки с таким кодом нет, список заказов пустой
- **datefrom** — Дата `ГГГГММДД`. Заказы, созданные с этой даты. Снимает ограничение `days`
- **dateto** — Дата `ГГГГММДД`. Заказы, созданные не позднее этой даты
- **datechangefrom** — Дата `ГГГГММДД`. Заказы, изменённые с этой даты
- **days** — Число. Глубина поиска в днях по дате создания. По умолчанию **30**. Не применяется, если указан `datefrom`
- **extra_data** — `1` или `true` — добавить к заказам данные модулей, например номер отправления и штрихкоды Озона. См. [Данные модулей (extra_data)](https://wiki.virtualpos.ru/hc/api/orders#данные_модулей_extra_data). По умолчанию выключен
- **format** — `json` (по умолчанию) или `xml`

Условия объединяются по «и». Заказы возвращаются по убыванию ид: новые первыми. Если клиент не найден, метод возвращает ошибку «Клиент не найден».

> **Важно:**
> **Ограничение в 30 дней.** Без `datefrom` отбираются заказы только за последние 30 дней (или за `days`). Для более старых заказов задайте `days` или `datefrom`.

## Получение одного заказа

```
GET https://[компания].myvirtualpos.ru/api/orders/get_order?apikey=MySecret&id=24237
```

- **id** — Число. Ид заказа
- **external_id** — Строка. Код заказа во внешней системе (поле `guid`). Используется, если не указан `id`
- **extra_data** — `1` или `true` — добавить к заказу данные модулей. См. [Данные модулей (extra_data)](https://wiki.virtualpos.ru/hc/api/orders#данные_модулей_extra_data)

Ответ по структуре совпадает с ответом метода `orders`, с одним заказом в списке. Ограничения по дате нет.

### Структура ответа

- **success** — `1` — данные получены
- **type** — Тип данных, `orders` (в методе `orders` и `get_order`)
- **count** — Количество заказов в ответе
- **orders** — Список заказов. Каждый обёрнут в объект `order`

### Поля заказа

Пустые значения в JSON приходят как `null`, в XML — как пустой элемент.

- **id** — Число. Ид заказа
- **external_id** — Строка. Код заказа во внешней системе
- **customer_id** — Число. Ид клиента. Пусто у заказов без клиента
- **state** — Строка. Статус заказа, см. раздел «Статусы заказа»
- **state_name** — Строка. Название статуса заказа из справочника статусов, например «Готов к выдаче»
- **assembled** — Логическое. Заказ собран и готов к выдаче
- **cancelled** — Логическое. Заказ отменён
- **completed** — Логическое. Заказ завершён
- **paid** — Число. `1` — заказ оплачен
- **created_date** — Строка. Дата и время создания, формат `гггг-мм-дд чч:мм:сс`
- **amount** — Строка. Сумма заказа по строкам
- **discount** — Число. Общая скидка
- **shipping_address** — Строка. Адрес доставки
- **shipping_cost** — Строка. Стоимость доставки
- **comment** — Строка. Комментарий
- **pickup_receipt_id** — Число. Ид чека, которым заказ выдан покупателю
- **pickup_from_warehouse_id**, **pickup_from_warehouse_name** — Ид и название точки продаж, откуда заказ выдаётся
- **delivery_type_id**, **delivery_type_name** — Ид и название типа доставки
- **payment_type_id**, **payment_type_name** — Ид и название типа оплаты
- **items** — Список строк заказа. Каждая обёрнута в объект `item`

В XML логические поля (`assembled`, `cancelled`, `completed`) для значения «нет» приходят пустыми элементами.

**Строка заказа**

- **item_id** — Число. Ид товара
- **item_external_id** — Строка. Код товара, сохранённый в строке заказа
- **item_name** — Строка. Название товара
- **image** — Строка. Полный адрес изображения товара, пусто если изображения нет
- **quantity** — Строка. Количество
- **unit_base_price** — Строка. Цена за единицу по прайс-листу без скидки
- **discount** — Строка. Скидка по строке
- **amount** — Строка. Сумма по строке с учётом скидки

### Данные модулей (extra_data)

С параметром `extra_data=1` в заказ добавляются данные подключённых модулей. Без параметра (или с `extra_data=0`) ответ остаётся прежним. Параметр работает в методах `orders` и `get_order`, а также в ответах `update_order`, `add_orders_item`, `update_order_item` и `delete_orders_item`.

**Блок `ozon`** есть только у заказов, пришедших с Озона (см. [Озон](https://wiki.virtualpos.ru/hc/online/ozon)). У остальных заказов блока нет. Поля и их значения передаются так, как их отдаёт Озон, без изменений.

- **posting_number** — Строка. Номер отправления Озона
- **tracking_number** — Строка. Трек-номер сторонней службы доставки (агрегатора). При доставке Озоном — пустая строка
- **scanit** — Строка. Номер с этикетки отправления, например `ii50247192380`. Озон присваивает его, когда отправление собрано
- **barcodes** — Объект. Штрихкоды с этикетки отправления: `upper_barcode` — верхний, `lower_barcode` — нижний

Данные берутся из отправления, сохранённого при последнем обмене с Озоном, — запрос к Озону метод не делает. Если у отправления ещё нет какого-то поля, оно приходит как `null` (в XML — пустой элемент).

```
GET https://[компания].myvirtualpos.ru/api/orders/get_order?apikey=MySecret&id=24240&extra_data=1
```

```json
{
  "success": 1,
  "count": 1,
  "type": "orders",
  "orders": [
    {
      "order": {
        "id": 24240,
        "state": "PREPARING",
        "state_name": "Комплектуется",
        "items": [ … ],
        "ozon": {
          "posting_number": "12345678-0001-1",
          "tracking_number": "",
          "scanit": "ii50247192380",
          "barcodes": {
            "upper_barcode": "500100000000001",
            "lower_barcode": "500100000000001"
          }
        }
      }
    }
  ]
}
```

В XML блок приходит элементом `<ozon>` с теми же полями.

### Статусы заказа

Статус хранится в поле `state`. Набор статусов настраивается в системе; в базовой поставке:

| Значение | Название |
| --- | --- |
| `NEW` | Новый |
| `PREPARING` | Комплектуется |
| `PAYMENT_EXPECTED` | Готов к оплате |
| `PREPARED` | Готов к выдаче |
| `CARRIER` | Отправлен |
| `SHIPPED` | Получен |
| `COMPLETED` | Завершён |
| `CANCELED` | Отменён |
| `RETURNED` | Возврат |
| `CHANGED` | Изменён |

Актуальный список — в разделе настройки статусов заказов панели управления.

### Пример ответа

```json
{
  "success": 1,
  "count": 1,
  "type": "orders",
  "orders": [
    {
      "order": {
        "id": 24238,
        "paid": 1,
        "customer_id": 40823,
        "state": "NEW",
        "state_name": "Новый",
        "assembled": false,
        "cancelled": false,
        "completed": false,
        "shipping_address": "г. Москва, ул. Тверская, д. 3",
        "shipping_cost": "130.00",
        "pickup_receipt_id": null,
        "comment": "После шести",
        "external_id": "WEB-1001",
        "created_date": "2026-09-26 10:31:01",
        "amount": "200.00",
        "discount": 10,
        "pickup_from_warehouse_id": 6,
        "pickup_from_warehouse_name": "Точка на Тверской",
        "delivery_type_id": 1,
        "delivery_type_name": "Самовывоз",
        "payment_type_id": 1,
        "payment_type_name": "Оплата при получении",
        "items": [
          {
            "item": {
              "item_id": 795,
              "item_external_id": null,
              "item_name": "Форма для наращивания",
              "image": "https://[компания].myvirtualpos.ru/data/images/795_1612871937.3154.jpg",
              "quantity": "2.000",
              "unit_base_price": "100.00",
              "discount": "10.00",
              "amount": "190.00"
            }
          }
        ]
      }
    }
  ]
}
```

Тот же ответ при `format=xml` (сокращённо):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <success>1</success>
  <count>1</count>
  <orders>
    <order>
      <id>24238</id>
      <customer_id>40823</customer_id>
      <state>NEW</state>
      <state_name>Новый</state_name>
      <assembled/>
      <!-- остальные поля заказа -->
      <items>
        <item>
          <item_id>795</item_id>
          <quantity>2.000</quantity>
          <!-- остальные поля строки -->
        </item>
      </items>
    </order>
  </orders>
</root>
```

## Создание заказа

```
POST https://[компания].myvirtualpos.ru/api/orders/add_order?apikey=MySecret&id=40823
order={"delivery_type_id":1,"payment_type_id":1,"items":[{"item_id":795,"quantity":2,"unit_base_price":100,"discount":10}]}
```

### Параметры

- **id** — Число. Ид клиента, для которого создаётся заказ
- **external_id** — Строка. Код клиента во внешней системе. Используется, если не указан `id`. Один из двух обязателен
- **order** — JSON-объект заказа, см. ниже. Обязателен
- **enable_lock** — `1` — зарезервировать товар в заказе на складе. Без параметра резерв не выполняется

**Поля объекта `order`**

- **delivery_type_id** — Число. Ид типа доставки. Обязательно
- **payment_type_id** — Число. Ид типа оплаты. Обязательно
- **items** — Массив строк заказа. Обязателен и не должен быть пустым
- **external_id** — Строка. Код заказа во внешней системе, до 1024 символов
- **shipping_address** — Строка. Адрес доставки
- **shipping_cost** — Число. Стоимость доставки
- **comment** — Строка. Комментарий
- **pickup_from_warehouse_id** — Число. Ид точки продаж, откуда заказ выдаётся покупателю
- **pickup_from_warehouse_external_id** — Строка. Код точки продаж во внешней системе
- **pickup_receipt_id** — Число. Ид чека выдачи

**Поля строки заказа (`items`)**

- **item_id** — Число. Ид товара
- **item_external_id** — Строка. Код товара во внешней системе; используется, если не указан `item_id`. Должен существовать в системе
- **quantity** — Число. Количество
- **unit_base_price** — Число. Цена за единицу по прайс-листу
- **discount** — Число. Скидка на всю строку
- **lot_number** — Строка. Серия (партия)
- **external_id** — Строка. Код строки во внешней системе

Сумма строки рассчитывается автоматически: `unit_base_price × quantity − discount`.

### Ответ

```json
{
  "success": 1,
  "order": {
    "delivery_type_id": 1,
    "payment_type_id": 1,
    "customer_id": 40823,
    "shipping_address": "г. Москва, ул. Тверская, д. 3",
    "shipping_cost": "130.00",
    "pickup_from_warehouse_id": 6,
    "external_id": "WEB-1001",
    "comment": "После шести",
    "items": [
      { "item": { "item_id": 795, "quantity": 2, "unit_base_price": 100, "discount": 10, "amount": 190 } }
    ],
    "order_id": 24238
  }
}
```

В ответе возвращаются переданные данные заказа, а ид созданного заказа — в поле `order_id`. Полные данные заказа можно получить методом `get_order`.

## Изменение заказа

```
POST https://[компания].myvirtualpos.ru/api/orders/update_order?apikey=MySecret&id=24238
order={"paid":1,"state":"PREPARED","comment":"Оплачен"}
```

- **id** — Число. Ид заказа. Только GET
- **external_id** — Строка. Код заказа во внешней системе. Только GET
- **order** — JSON-объект с изменяемыми полями заказа: например `paid`, `state`, `comment`, `shipping_address`, `shipping_cost`. Нельзя передать пустой объект

Ответ содержит полные данные заказа в том же формате, что и метод `get_order`: `{"success":1,"order":{…}}`. Если указан `state`, это должен быть код существующего статуса заказа.

> **Важно:**
> Ид заказа в этом методе — ид **заказа**, а не клиента. Метод не проверяет, кому принадлежит заказ.

## Строки заказа

```
POST https://[компания].myvirtualpos.ru/api/orders/add_orders_item?apikey=MySecret&id=24238
items=[{"item_id":5565,"quantity":1,"unit_base_price":50,"discount":5}]
```

Три метода работают с массивом `items` в формате JSON. Заказ определяется параметром `id` или `external_id` (только GET). Операции над несколькими строками выполняются в одной транзакции: при ошибке в любой строке не сохраняется ничего.

- **add_orders_item** — Добавляет строки. Каждая строка — объект с `item_id`, `quantity`, `unit_base_price`, `discount`, `lot_number`. Если товар уже есть в заказе, вернётся ошибка
- **update_order_item** — Меняет строки. Строка определяется товаром (`item_id`), остальные поля — новые значения. Если товара нет в заказе, вернётся ошибка
- **delete_orders_item** — Удаляет строки. В объекте достаточно указать `item_id`

Во всех случаях в объекте строки нужно указать `item_id`; вместо него можно передать `external_id` — код товара из поля `guid` номенклатуры. Сумма строки пересчитывается по правилу `unit_base_price × quantity − discount`.

Ответ каждого метода: `{"success":1,"order":{…}}` с полными данными заказа после изменения.

## Примеры запросов

| Задача | Запрос |
| --- | --- |
| Типы оплаты и доставки | `/api/orders/get_payment_types?apikey=MySecret`, `/api/orders/get_delivery_types?apikey=MySecret` |
| Заказы клиента за 90 дней | `/api/orders?apikey=MySecret&id=40823&days=90` |
| Заказы клиента по коду из внешней системы | `/api/orders?apikey=MySecret&external_id=CRM-1001&datefrom=20260101` |
| Заказы точки продаж за 7 дней | `/api/orders?apikey=MySecret&warehouse_id=6&days=7` |
| Заказы всех клиентов, изменённые с даты | `/api/orders?apikey=MySecret&datechangefrom=20260925&days=3650` |
| Заказ по ид | `/api/orders/get_order?apikey=MySecret&id=24238` |
| Заказ по коду | `/api/orders/get_order?apikey=MySecret&external_id=WEB-1001` |
| Заказы за 7 дней с номерами отправлений и штрихкодами Озона | `/api/orders?apikey=MySecret&days=7&extra_data=1` |

## Ошибки

Ошибка авторизации и общие ошибки описаны в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Ошибки приходят с кодом HTTP 200 и `success` равным `0`:

| Сообщение | Метод | Причина | Что делать |
| --- | --- | --- | --- |
| Клиент не найден | orders | Клиент не найден по `id` или `external_id` | Проверьте идентификатор клиента |
| Вы не указали идентификатор заказа в поле [id] или [external_id | get_order | Нет `id` и `external_id` | Передайте один из них |
| Заказ не найден / Order not found | get_order, update_order, строки | Заказ не найден | Проверьте ид заказа |
| You have to specify customer's [id] or [external_id] | add_order | Нет идентификатора клиента | Передайте `id` или `external_id` клиента |
| Customer not found | add_order | Клиент не найден | Проверьте идентификатор клиента |
| Parameter [order] not found | add_order | Не передан `order` | Передайте JSON заказа |
| Parameter [order] must contain a non-empty array [items] | add_order | Нет строк заказа | Добавьте хотя бы одну строку |
| Json error: … | add_order, строки | Некорректный JSON | Проверьте формат `order` или `items` |
| Error while saving: … | add_order, update_order | Заказ не сохранён: не указан тип доставки или оплаты, несуществующий тип, товар не найден | Исправьте данные; текст после двоеточия поясняет причину |
| Товар со внешним идентификатором '…' не найден | add_order | Нет товара с таким `item_external_id` | Проверьте код товара |
| Не заданы параметр [order] / Не заданы параметры заказа | update_order | Нет `order` или он пустой | Передайте изменяемые поля |
| Некорректный формат запрроса | update_order | `order` не JSON | Проверьте формат |
| Неизвестный статус заказа [state]: … | update_order | Такого статуса нет | Используйте существующий статус |
| Parameter [items] not found | строки | Не передан `items` | Передайте JSON строк |
| You have to specify order's [id] or [external_id] | строки | Нет ид заказа | Передайте `id` заказа |
| Order`s item is already exists | add_orders_item | Товар уже есть в заказе | Используйте `update_order_item` |
| Order`s item is not exists | update_order_item, delete_orders_item | Товара нет в заказе | Проверьте `item_id` |

Если заказов, подходящих под условия, нет, метод `orders` возвращает успешный ответ с `count` равным `0` и пустым списком.

## Связанные разделы

- [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки
- [Customer. Клиенты](https://wiki.virtualpos.ru/hc/api/customer) — Клиенты, для которых создаются заказы
- [Item. Номенклатура](https://wiki.virtualpos.ru/hc/api/item) — Товары в заказах
- [Озон](https://wiki.virtualpos.ru/hc/online/ozon) — Заказы с Озона и обмен отправлениями