# Pricelist. Цены на товары

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

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

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

## Методы

| Метод | Адрес | Что делает |
| --- | --- | --- |
| Получить цены | `/api/pricelist` | Возвращает цены товаров прайс-листа |
| Создать или изменить прайс-лист | `/api/pricelist/update` | Обновляет заголовок прайс-листа или создаёт новый |
| Установить цену товара | `/api/pricelist/updateItem` | Задаёт цену одного товара в прайс-листе |
| Массовая установка цен | `/api/pricelist/batchUpdate` | Задаёт цены многим товарам одним XML |
| Назначить точке продаж | `/api/pricelist/assign` | Делает прайс-лист основным для точки продаж |
| Прайс-листы точки продаж | `/api/pricelist/listForWarehouse` | Возвращает прайс-листы точки и основной |

> **Важно:**
> **Где передавать параметры.** Ключ `apikey` и формат `format` принимаются и в адресной строке, и в теле POST-запроса. Параметры, по которым ищется прайс-лист, товар или точка продаж — `id`, `external_id`, `name`, `item_id`, `item_ext_id` в методе получения, `id`, `external_id`, `item_id`, `item_ext_id` в `updateItem`, `id`, `external_id`, `warehouse_id`, `warehouse_ext_id` в `assign`, `warehouse_id`, `warehouse_external_id` в `listForWarehouse` — читаются **только из адресной строки (GET)**. Остальные параметры можно передавать и в адресной строке, и в теле POST. Значения с кириллицей и пробелами кодируйте.

## Получение цен

```
GET https://[компания].myvirtualpos.ru/api/pricelist?apikey=MySecret&id=1&item_id=52
```

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

- **id** — Число. Ид прайс-листа. Нужно указать `id`, `external_id` или `name`. Только GET
- **external_id** — Строка. Код прайс-листа во внешней системе. Только GET
- **name** — Строка. Название прайс-листа. Только GET
- **item_id** — Число. Ид товара: вернётся цена только этого товара. Только GET
- **item_ext_id** — Строка. Код товара во внешней системе. Используется, если не указан `item_id`. Только GET
- **item_article** — Строка. Артикул: вернутся цены товаров с таким артикулом. Используется, если не указаны `item_id` и `item_ext_id`
- **fields** — Дополнительные поля товара через двоеточие, например `item_name:item_ean13`. Допустимые значения перечислены ниже
- **format** — `json` (по умолчанию) или `xml`

Прайс-лист ищется по `id`, затем по `external_id`, затем по `name`.

> **Важно:**
> **Без фильтра по товару метод возвращает весь прайс-лист.** В нём могут быть десятки тысяч строк, и ответ получается большим. Если нужны цены отдельных товаров, задавайте `item_id` или `item_ext_id`. Постраничной выдачи у метода нет.

**Дополнительные поля (`fields`).** Через двоеточие можно перечислить любые поля вида `item_<поле товара>`, например `item_name`, `item_article`, `item_external_id`, `item_type`, `item_volume`, `item_vat_percent`, `item_manufacturer_id`, а также:

- **item_ean13** — Штрихкоды товара через запятую
- **item_manufacturer_name** — Название производителя товара

Если указано неизвестное поле, метод вернёт ошибку со списком допустимых полей.

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

- **success** — `1` — данные получены
- **type** — Тип данных, всегда `pricelistLines`
- **pricelist_id** — Число. Ид прайс-листа
- **count** — Количество строк в ответе
- **pricelines** — Список цен. Каждая обёрнута в объект `priceline`

**Поля строки прайс-листа**

- **item_id** — Число. Ид товара
- **price** — Строка. Цена товара в прайс-листе
- **item_…** — Дополнительные поля товара, если они запрошены в `fields`

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

```json
{
  "success": 1,
  "type": "pricelistLines",
  "pricelist_id": 1,
  "count": 1,
  "pricelines": [
    {
      "priceline": {
        "item_id": 52,
        "price": "929.00",
        "item_name": "Шампунь для волос",
        "item_ean13": "4627087168773"
      }
    }
  ]
}
```

Тот же ответ при `format=xml`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <success>1</success>
  <type>pricelistLines</type>
  <pricelist_id>1</pricelist_id>
  <count>1</count>
  <pricelines>
    <priceline>
      <item_id>52</item_id>
      <price>929.00</price>
    </priceline>
  </pricelines>
</root>
```

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

| Задача | Запрос |
| --- | --- |
| Цена товара по ид | `/api/pricelist?apikey=MySecret&id=1&item_id=52` |
| Цена товара по коду товара и прайс-листа из 1С | `/api/pricelist?apikey=MySecret&external_id=PL-RETAIL&item_ext_id=SKU-52` |
| Цена с названием и штрихкодами | `/api/pricelist?apikey=MySecret&id=1&item_id=52&fields=item_name:item_ean13` |
| Цены товаров по артикулу | `/api/pricelist?apikey=MySecret&id=1&item_article=SH-1000` |

## Создание и изменение прайс-листа

```
POST https://[компания].myvirtualpos.ru/api/pricelist/update?apikey=MySecret&external_id=PL-RETAIL&create_if_not_exist=1
name=Розничный&description=Основные цены
```

Прайс-лист ищется по `id`, а если он не указан — по `external_id`. Метод меняет заголовок прайс-листа, но не цены. Изменяются только переданные параметры.

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

- **id** — Число. Ид изменяемого прайс-листа
- **external_id** — Строка. Код прайс-листа во внешней системе. Если `id` не указан, по нему ищется прайс-лист; одновременно это поле прайс-листа
- **create_if_not_exist** — `1` — создать прайс-лист, если он не найден
- **name** — Строка, до 255 символов. Название; должно быть уникальным и не содержать `::`. Обязательно при создании
- **description** — Строка, до 1023 символов. Описание

### Ответ

```json
{"success":1,"id":"11","isnew":"1"}
```

- **success** — `1` — прайс-лист сохранён
- **id** — Ид прайс-листа. При создании приходит строкой, при изменении — числом
- **isnew** — `"1"` — создан, `"0"` — изменён существующий

## Установка цены товара

```
GET https://[компания].myvirtualpos.ru/api/pricelist/updateItem?apikey=MySecret&external_id=PL-RETAIL&item_id=52&price=150.5
```

- **id** — Число. Ид прайс-листа. Нужно указать `id` или `external_id`. Только GET
- **external_id** — Строка. Код прайс-листа во внешней системе. Только GET
- **item_id** — Число. Ид товара. Нужно указать `item_id` или `item_ext_id`. Только GET
- **item_ext_id** — Строка. Код товара во внешней системе. Только GET
- **price** — Число. Новая цена. Обязательно. Нечисловое значение отклоняется

Если товара в прайс-листе ещё нет, строка создаётся, иначе цена меняется.

```json
{"success":1,"line_id":"77028","isnew":"1","price_before":null}
```

- **success** — `1` — цена сохранена
- **line_id** — Ид строки прайс-листа. При создании приходит строкой, при изменении — числом
- **isnew** — `"1"` — строка создана, `"0"` — изменена существующая
- **price_before** — Строка. Цена до изменения; `null`, если строка создана

## Массовая установка цен

```
POST https://[компания].myvirtualpos.ru/api/pricelist/batchUpdate?apikey=MySecret
batch=<pricelist><external_id>PL-RETAIL</external_id><items>...</items></pricelist>
```

Параметр `batch` — XML. Корневой элемент содержит прайс-лист и его строки:

```xml
<pricelist>
  <external_id>PL-RETAIL</external_id>
  <items>
    <item>
      <external_id>SKU-52</external_id>
      <price>200.50</price>
    </item>
    <item>
      <id>53</id>
      <price>7</price>
    </item>
  </items>
</pricelist>
```

- **id**, **external_id** — В корне: ид или код прайс-листа. Нужен один из них
- **items/item/id**, **items/item/external_id** — Ид или код товара. Нужен один из них
- **items/item/price** — Новая цена. Если у товара уже была цена, прежняя сохраняется как старая цена

Все строки сохраняются в одной транзакции: если хотя бы один товар не найден или цена не сохранена, не сохраняется ничего. Успешный ответ: `{"success":1,"info":"Saved price data"}`.

## Назначение прайс-листа точке продаж

```
GET https://[компания].myvirtualpos.ru/api/pricelist/assign?apikey=MySecret&external_id=PL-RETAIL&warehouse_id=6
```

- **id** — Число. Ид прайс-листа. Нужно указать `id` или `external_id`. Только GET
- **external_id** — Строка. Код прайс-листа во внешней системе. Только GET
- **warehouse_id** — Число. Ид точки продаж. Нужно указать `warehouse_id` или `warehouse_ext_id`. Только GET
- **warehouse_ext_id** — Строка. Код точки продаж во внешней системе. Только GET

Прайс-лист становится основным для точки продаж, прежний основной прайс-лист переводится в архив. Параметр `main` не влияет на результат: прайс-лист всегда назначается основным. Ответ: `{"success":1,"warehouse_id":6,"price_id":11}`.

## Прайс-листы точки продаж

```
GET https://[компания].myvirtualpos.ru/api/pricelist/listForWarehouse?apikey=MySecret&warehouse_id=6
```

- **warehouse_id** — Число. Ид точки продаж. Нужно указать `warehouse_id` или `warehouse_external_id`. Только GET
- **warehouse_external_id** — Строка. Код точки продаж во внешней системе. Только GET

```json
{
  "success": 1,
  "warehouse_id": 6,
  "warehouse_external_id": "WH-6",
  "default_pricelist_id": 1,
  "default_pricelist_external_id": "PL-RETAIL",
  "pricelist_ids": "1,2",
  "pricelist_external_ids": "PL-RETAIL,PL-WHOLESALE"
}
```

- **warehouse_id**, **warehouse_external_id** — Ид и код точки продаж
- **default_pricelist_id**, **default_pricelist_external_id** — Ид и код основного прайс-листа точки
- **pricelist_ids** — Строка. Ид всех прайс-листов, доступных точке, через запятую
- **pricelist_external_ids** — Строка. Коды тех же прайс-листов через запятую в том же порядке. Для прайс-листов без кода — пустое значение

## Ошибки

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

| Сообщение | Метод | Причина | Что делать |
| --- | --- | --- | --- |
| You have to specify pricelist using [id], [external_id] or [name] parameters | получение | Не указан прайс-лист | Передайте один из параметров |
| Pricelist not found | получение | Прайс-лист не найден | Проверьте ид, код или название |
| Item not found / Items not found | получение | Товар или артикул не найдены | Проверьте `item_id`, `item_ext_id`, `item_article` |
| Field '…' not found. Use combination of: […] | получение | Неизвестное поле в `fields` | Используйте поля из списка в сообщении |
| You have to specify [id] or [external_id] to update record | update | Нет идентификатора и `create_if_not_exist` | Передайте идентификатор или `create_if_not_exist=1` |
| Record not found | update | Прайс-лист не найден | Проверьте идентификатор |
| Data validation failed. … | update, updateItem | Название пустое, уже занято или содержит `::`; цена не задана | Исправьте значения |
| Cannot save data. … | update, updateItem | Ошибка сохранения | Текст после точки поясняет причину |
| You have to specify pricelist`s [id] or [external_id] | updateItem, assign | Нет идентификатора прайс-листа | Передайте `id` или `external_id` |
| You have to specify item`s [id] or [external_id] | updateItem | Нет идентификатора товара | Передайте `item_id` или `item_ext_id` |
| You have to specify [price] value | updateItem | Не передана цена | Передайте `price` |
| Pricelist not found. id=…, external_id=… | updateItem, assign | Прайс-лист не найден | Проверьте идентификатор |
| Item not found. id=…, external_id=… | updateItem | Товар не найден | Проверьте идентификатор |
| You have to specify warehouse`s [id] or [external_id] | assign | Нет идентификатора точки продаж | Передайте `warehouse_id` или `warehouse_ext_id` |
| Warehouse not found. id=…, external_id=… | assign, listForWarehouse | Точка продаж не найдена | Проверьте идентификатор |
| Internal error. … | batchUpdate | Не найден прайс-лист или товар, некорректный XML; все изменения отменены | Текст после точки поясняет причину |

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

- [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки
- [Item. Номенклатура](https://wiki.virtualpos.ru/hc/api/item) — Товары, для которых задаются цены
- [Warehouse. Точки продаж](https://wiki.virtualpos.ru/hc/api/warehouse) — Точки продаж, которым назначаются прайс-листы
- [PricelistAdjustment. Корректировка розничных цен](https://wiki.virtualpos.ru/hc/api/pricelistadjustment) — Документы корректировки цен