# Inventory. Инвентаризации

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

Метод возвращает документы «Инвентаризация» вместе со строками: сверку фактических остатков с учётными по точке продаж. Документы можно только читать: создание и изменение через API не поддерживаются.

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

## Запрос

Все параметры, кроме ключа `apikey` и формата `format`, принимаются и в адресной строке, и в теле POST.

```
GET https://[компания].myvirtualpos.ru/api/inventory?apikey=MySecret&days=90&warehouse_id=6&withitems=1
```

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

- **id** — Число. Ид документа. Если указан, ищется только этот документ
- **external_id** — Строка. Код документа во внешней системе (например, в 1С). Действует, если `id` не указан
- **last_id** — Число. Вернуть документы с ид больше указанного: для получения новых документов с прошлого обмена. Действует, если не указаны `id` и `external_id`
- **warehouse_id** — Число. Ид точки продаж. Если не указан, возвращаются документы всех точек
- **external_warehouse_id** — Строка. Код точки продаж во внешней системе. Действует, если не указан `warehouse_id`. Если точки с таким кодом нет, возвращается пустой список
- **date** — Дата `ГГГГММДД`. Документы с этой датой документа
- **datefrom**, **dateto** — Дата `ГГГГММДД`. Документы с датой документа с указанной даты и по указанную включительно
- **cdatefrom**, **cdateto** — Дата `ГГГГММДД`. То же по дате создания документа в системе
- **days** — Число. Глубина поиска в днях от текущей даты по дате документа. По умолчанию **30**
- **withitems** — `1` — добавить строки документов. По умолчанию возвращаются только шапки
- **format** — `json` (по умолчанию) или `xml`

Условия объединяются по «и». Даты передаются строго в формате `ГГГГММДД`, иначе метод вернёт ошибку `Incorrect date format`. Документы возвращаются по убыванию `id`: новые первыми.

> **Важно:**
> **Ограничение `days` действует всегда.** По умолчанию отбираются документы только за последние 30 дней по дате документа, и это ограничение накладывается вместе со всеми остальными условиями, в том числе `id`, `external_id` и датами. Например, запрос `datefrom=20241006&dateto=20241006` про документ 2024 года вернёт пустой список, если не добавить `days` с достаточным значением (`days=1000`). Чтобы получить старые документы, всегда указывайте `days`.
>
> При `days=0` ограничение снимается, и метод пытается собрать в один ответ **все** документы. У больших баз это заканчивается ошибкой сервера по памяти, поэтому лучше указывать конкретную глубину и дополнительно ограничивать выборку точкой продаж или датами.

## Статусы и типы

**Статус документа** (`status`)

| Значение | Название |
| --- | --- |
| `NEW` | Новая |
| `INPROGRESS` | В работе |
| `CLOSED` | Закрыта: остатки на складе скорректированы по результатам подсчёта |
| `CLOSED_WCH` | Закрыта без изменения складских остатков |

**Тип инвентаризации** (`type`)

| Значение | Название |
| --- | --- |
| `G` | Инвентаризация товаров |
| `M` | Инвентаризация материальных ценностей |

**Состояние строки** (`state`)

| Значение | Смысл |
| --- | --- |
| Не обработана | Товар ещё не пересчитан |
| Излишек | Фактическое количество больше учётного |
| Недостача | Фактическое количество меньше учётного |
| Ровно | Фактическое количество совпадает с учётным |

Поле `state` содержит русское название, а не код.

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

- **success** — `1` — данные получены
- **type** — Тип данных, всегда `inventory`
- **days_limit** — Число дней, за которые отобраны документы: `30` по умолчанию или значение `days`
- **count** — Количество документов в ответе
- **inventories** — Список документов. Каждый обёрнут в объект `inventory`

### Поля документа

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

- **id** — Число. Ид документа
- **external_id** — Строка. Код документа во внешней системе
- **guid** — Строка. Уникальный идентификатор документа (GUID)
- **docnum** — Строка. Номер документа
- **docdate** — Строка. Дата документа, формат `гггг-мм-дд чч:мм:сс`
- **status** — Строка. Статус документа, см. раздел «Статусы и типы»
- **type** — Строка. Тип инвентаризации: `G` или `M`
- **comment** — Строка. Комментарий
- **warehouse_id** — Число. Ид точки продаж
- **warehouse_external_id** — Строка. Код точки продаж во внешней системе
- **created_date**, **last_update_date** — Строка. Дата и время создания и последнего изменения
- **created_by**, **last_update_by** — Число. Ид пользователя, создавшего и изменившего документ
- **attribute1** … **attribute15** — Строка. Значения гибких полей документа
- **items** — Список строк; при `withitems=0` пустой. Каждая строка обёрнута в объект `item`

### Поля строки

- **id** — Число. Ид строки
- **inventory_id** — Число. Ид документа
- **item_id** — Число. Ид товара
- **item_external_id** — Строка. Код товара во внешней системе
- **item_name** — Строка. Название товара
- **onhand_id** — Число. Ид товарного остатка
- **quantity_initial** — Строка. Учётное количество на момент инвентаризации
- **quantity** — Строка. Фактическое количество по результатам подсчёта
- **lot_number** — Строка. Серия (партия)
- **cogs**, **cogs_initial** — Строка. Закупочная цена и закупочная цена по учёту на момент инвентаризации
- **price** — Строка. Цена продажи
- **expir_date**, **expir_date_initial** — Строка. Срок годности: фактический и по учёту. Если не задан, приходит `0000-00-00`
- **state** — Строка. Состояние строки, см. раздел «Статусы и типы»
- **guid** — Строка. Уникальный идентификатор строки
- **created_date**, **last_update_date** — Строка. Дата и время создания и последнего изменения строки
- **created_by**, **last_update_by** — Число. Ид пользователя, создавшего и изменившего строку

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

```json
{
  "success": 1,
  "type": "inventory",
  "days_limit": 90,
  "count": 1,
  "inventories": [
    {
      "inventory": {
        "id": 9906,
        "warehouse_id": 6,
        "status": "CLOSED",
        "docnum": null,
        "docdate": "2026-09-06 00:00:00",
        "comment": "Ежемесячная инвентаризация",
        "created_date": "2026-09-06 18:50:05",
        "created_by": 44,
        "last_update_date": "2026-09-06 20:03:56",
        "last_update_by": 44,
        "external_id": null,
        "type": "G",
        "guid": "F9825B9C-3F35-7114-1F44-7AF7B82BEC6C",
        "warehouse_external_id": "WH-6",
        "items": [
          {
            "item": {
              "id": 144630297,
              "inventory_id": 9906,
              "item_id": 2313,
              "onhand_id": 14794,
              "quantity_initial": "1105.000",
              "quantity": "1300.000",
              "lot_number": null,
              "cogs": "0.64",
              "price": "5.00",
              "cogs_initial": "0.64",
              "expir_date": "0000-00-00",
              "expir_date_initial": "0000-00-00",
              "guid": "62315839-83C9-11EF-9186-00155DCD4602",
              "item_external_id": "ITEM-2313",
              "item_name": "Перчатки полиэтиленовые",
              "state": "Излишек"
            }
          }
        ]
      }
    }
  ]
}
```

В примере для краткости опущены гибкие поля `attribute1`…`attribute15` и служебные поля создания и изменения.

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

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <success>1</success>
  <type>inventory</type>
  <days_limit>90</days_limit>
  <count>1</count>
  <inventories>
    <inventory>
      <id>9906</id>
      <status>CLOSED</status>
      <!-- остальные поля шапки -->
      <items>
        <item>
          <id>144630297</id>
          <item_id>2313</item_id>
          <quantity_initial>1105.000</quantity_initial>
          <quantity>1300.000</quantity>
          <state>Излишек</state>
          <!-- остальные поля строки -->
        </item>
      </items>
    </inventory>
  </inventories>
</root>
```

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

| Задача | Запрос |
| --- | --- |
| Документы за последние 30 дней (шапки) | `/api/inventory?apikey=MySecret` |
| Документы за квартал со строками | `/api/inventory?apikey=MySecret&days=90&withitems=1` |
| Один документ по ид | `/api/inventory?apikey=MySecret&id=9906&days=3650&withitems=1` |
| Документы за конкретный день по точке продаж | `/api/inventory?apikey=MySecret&date=20260906&days=90&warehouse_id=6` |
| Новые документы после последнего полученного | `/api/inventory?apikey=MySecret&last_id=9906&days=90` |
| Документы точки по её коду в 1С | `/api/inventory?apikey=MySecret&external_warehouse_id=WH-6&days=90` |

## Ошибки

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

| Сообщение | Причина | Что делать |
| --- | --- | --- |
| Incorrect date format '…'. Valid format is: YYYYMMDD | Дата в параметре не в формате `ГГГГММДД` | Передайте дату как `20260906` |

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

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

- [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки
- [Инвентаризация](https://wiki.virtualpos.ru/hc/stock/inventory) — Работа с инвентаризациями в панели управления
- [Warehouse. Точки продаж](https://wiki.virtualpos.ru/hc/api/warehouse) — Справочник точек продаж