Инвентаризации

Инвентаризации

Инвентаризации: сверка фактических остатков на складе с остатками в Controlata. Вы передаете фактическое количество, а Controlata сравнивает его с ожидаемым остатком и корректирует остаток на разницу. Через API инвентаризации можно создавать, редактировать и удалять, менять их статус, получать список и данные инвентаризации. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, строки операций, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/audits/add | Создает инвентаризацию | | v1/audits/edit | Изменяет строки инвентаризации | | v1/audits/delete | Удаляет инвентаризацию | | v1/audits/update_status | Меняет статус инвентаризации | | v1/audits/get_list | Возвращает список инвентаризаций | | v1/audits/get_entry | Возвращает инвентаризацию со строками | Поля инвентаризации | Поле | Тип | Описание | |---|---|---| | id | int | ID инвентаризации | | num | int | Номер. Присваивается автоматически: следующий по порядку | | date | string | Дата инвентаризации, YYYY-MM-DD | | status | int | Статус: 0 План, 1 Проведена | | storage_id | int | Склад, на котором проводится инвентаризация | | storage_name | string | Название склада | | lines | int | Количество строк | | surplus_cost | float | Излишки по себестоимости | | shortage_cost | float | Недостачи по себестоимости, отрицательное число | | total_cost | float | Итог по себестоимости: surplus_cost + shortage_cost | | surplus_price | float | Излишки по цене продажи. Считается только для продуктов, у материалов 0 | | shortage_price | float | Недостачи по цене продажи, отрицательное число. Только для продуктов | | total_price | float | Итог по цене продажи: surplus_price + shortage_price | Материалы или продукты Одна инвентаризация считает либо материалы, либо продукты на одном складе. Строки передаются только в одном из массивов: materials или products. Тип определяется при создании и потом не меняется. Ожидаемый и фактический остаток - Фактический остаток (actual) передаете вы: сколько позиций насчитали на складе. - Ожидаемый остаток (expected) рассчитывает Controlata: сумма всех проведенных движений позиции на этом складе по дату инвентаризации включительно. Запланированные операции не учитываются. Передавать ожидаемый остаток не нужно. Ожидаемый остаток фиксируется в строке при ее добавлении. Если потом появится операция с более ранней датой, ожидаемый остаток уже добавленной строки не пересчитается. Разница между фактом и ожиданием становится корректировкой остатка: - излишек (факт больше) добавляется на склад. Материалы оцениваются по цене из карточки материала. Продукты по себестоимости последнего прихода на этот склад до даты инвентаризации, а если приходов не было, по себестоимости из карточки продукта; - недостача (факт меньше) списывается со склада по FIFO. Статусы | Код | Статус | Остатки | |---|---|---| | 0 | План | Корректировки только запланированы: остаток не меняется, разница учитывается в поле planned остатков | | 1 | Проведена | Остатки скорректированы на разницу | Новая инвентаризация создается в статусе из настройки Статус новой инвентаризации по умолчанию. Сменить статус можно методом v1/audits/update_status. Что можно изменить После создания у инвентаризации меняются только строки: их фактические остатки, заметки и состав. Дату, склад и тип изменить нельзя. Чтобы провести инвентаризацию на другую дату или на другом складе, удалите ее и создайте новую.

Создание инвентаризации

Создает инвентаризацию материалов или продуктов на складе. Передавайте только фактические остатки: ожидаемые Controlata рассчитает сама на дату инвентаризации. v1/audits/add.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | storage_id | int | Да | Склад, на котором проводится инвентаризация | | materials | array | materials или products | Строки инвентаризации материалов | | products | array | materials или products | Строки инвентаризации продуктов | | date | string | Нет | Дата инвентаризации, YYYY-MM-DD. По умолчанию сегодня | Строка materials и products: | Поле | Тип | Обязательное | Описание | |---|---|---|---| | id | int | id или sku | ID материала или продукта | | sku | string | id или sku | Артикул | | actual | float | Да | Фактический остаток, 0 или больше | | notes | string | Нет | Заметки к строке | Передайте строки только в одном массиве: инвентаризация считает либо материалы, либо продукты. Каждая позиция указывается один раз. Как указывать позицию по id или артикулу, описано в статье Общие правила. Как работает - Ожидаемый остаток каждой строки рассчитывается на дату инвентаризации включительно по проведенным операциям склада (см. Инвентаризации). - Корректировка. Разница между actual и ожидаемым остатком добавляется на склад (излишек) или списывается по FIFO (недостача). Строка без разницы остаток не меняет. - Статус берется из настройки Статус новой инвентаризации по умолчанию. В статусе Проведена остатки корректируются сразу, в статусе План корректировка только планируется. - Номер присваивается автоматически, задать его нельзя. - В инвентаризацию попадают только переданные позиции. Остальные позиции склада она не затрагивает. Пример запроса { "storage_id": 3998, "date": "2026-09-30", "materials": [ { "id": 2051, "actual": 3.8 }, { "sku": "M022", "actual": 0, "notes": "Не найдено на складе" } ] } Пример ответа { "success": true, "audit_id": 1699, "num": 24, "status": 1 } В ответе приходят ID, номер и код статуса новой инвентаризации. Ожидаемые остатки и разницу по строкам возвращает v1/audits/get_entry. Ошибки | Ошибка | Причина | |---|---| | No storage_id in input | Не передан storage_id | | Storage ID is not set | storage_id равен 0 или пустой | | Storage ID not found | Склад не найден или удален | | An audit counts either materials or products. Create separate audits | Переданы и materials, и products | | No products or materials in input | Не передано ни одной строки | | Materials is not an array | materials не массив (так же для products) | | Line 0 of materials must be an object | Строка не объект (вместо 0 будет номер строки) | | SKU or id not set for material 0 | В строке нет ни id, ни sku | | Material with id 2051 not found | Материал не найден или удален (для артикула: Material with SKU "M022" not found) | | Actual must be 0 or greater for material with id 2051 | actual не передан, не число или меньше 0 | | Material with id 2051 is listed twice | Позиция указана в двух строках | | Date is not a valid date in format YYYY-MM-DD | Неверный формат даты |

Редактирование инвентаризации

Изменяет строки инвентаризации. Дата, склад и тип инвентаризации не меняются. v1/audits/edit.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | audit_id | int | Да | ID инвентаризации | | materials | array | Нет | Строки инвентаризации материалов: id или sku, actual, notes | | products | array | Нет | Строки инвентаризации продуктов: id или sku, actual, notes | Строки передаются так же, как в v1/audits/add, и только в массиве того типа, который считает инвентаризация. Как работает - Строки заменяются целиком. Позиция, которой нет в запросе, удаляется из инвентаризации, а ее корректировка отменяется. Чтобы изменить одну строку, передайте все строки, например из ответа v1/audits/get_entry. - Ожидаемый остаток. У строк, которые уже были в инвентаризации, остается сохраненный ожидаемый остаток. У новых строк он рассчитывается на дату инвентаризации без учета ее собственных корректировок. - Корректировки проводятся заново по новым фактическим остаткам. Статус инвентаризации сохраняется. - Если не передан ни materials, ни products, ничего не меняется, а метод отвечает успехом. Другие поля (date, storage_id) метод не принимает и молча пропускает. Пример запроса { "audit_id": 1699, "materials": [ { "id": 2051, "actual": 4 }, { "sku": "M022", "actual": 0, "notes": "Не найдено на складе" } ] } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No audit_id in input | Не передан audit_id | | Audit not found or access denied | Инвентаризация не найдена или удалена | | This audit counts materials. Its type cannot be changed | Строки переданы в массиве другого типа (для продуктов: This audit counts products) | | An audit counts either materials or products. Create separate audits | Переданы и materials, и products | | No products or materials in input | Массивы строк переданы, но пустые | | Material with id 2051 not found | Материал не найден или удален | | Actual must be 0 or greater for material with id 2051 | actual не передан, не число или меньше 0 | | Material with id 2051 is listed twice | Позиция указана в двух строках | Остальные ошибки строк такие же, как в v1/audits/add.

Удаление инвентаризации

Удаляет инвентаризацию. v1/audits/delete.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | audit_id | int | Да | ID инвентаризации | Как работает Корректировки инвентаризации отменяются: излишки убираются со склада, недостачи возвращаются на него, остатки пересчитываются. Строки инвентаризации удаляются вместе с ней. Пример запроса { "audit_id": 1699 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No audit_id in input | Не передан audit_id | | Audit not found or access denied | Инвентаризация не найдена или уже удалена |

Смена статуса инвентаризации

Меняет статус инвентаризации. От статуса зависит, скорректированы ли остатки на складе. v1/audits/update_status.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | audit_id | int | Да | ID инвентаризации | | status | int | Да | Новый статус: 0 План, 1 Проведена | Как работает | Новый статус | Остатки | |---|---| | 0 План | Корректировки отменяются на остатке и учитываются в поле planned остатков | | 1 Проведена | Остатки корректируются: излишки добавляются, недостачи списываются | Ожидаемые остатки и суммы излишков и недостач при смене статуса не пересчитываются. Если инвентаризация уже в этом статусе, ничего не меняется, а метод отвечает успехом. Пример запроса { "audit_id": 1699, "status": 1 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No audit_id in input | Не передано обязательное поле (вместо audit_id будет имя поля) | | Invalid status value. Must be one of: 0, 1 | Неверный код статуса | | Audit not found or access denied | Инвентаризация не найдена или удалена |

Список инвентаризаций

Возвращает инвентаризации компании, от новых к старым: по дате, а внутри одной даты по номеру. v1/audits/get_list.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | storage_id | int | Нет | Только инвентаризации этого склада | | date_from | string | Нет | Инвентаризации с этой даты включительно, YYYY-MM-DD | | date_to | string | Нет | Инвентаризации по эту дату включительно, YYYY-MM-DD | | status | int | Нет | Статус: 0 План, 1 Проведена | | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Без limit возвращается весь список. Подробнее о постраничной выдаче в статье Общие правила. Ответ Массив audits с полями инвентаризации (см. Инвентаризации), без строк. Строки и тип инвентаризации возвращает v1/audits/get_entry. Поле total содержит общее число инвентаризаций, подходящих под фильтры. Пример запроса { "storage_id": 3998, "date_from": "2026-01-01", "limit": 100, "offset": 0 } Пример ответа { "success": true, "audits": [ { "id": "1699", "num": "24", "date": "2026-09-30", "status": "1", "storage_id": "3998", "storage_name": "Главный", "lines": "2", "surplus_cost": "0.00", "shortage_cost": "-57900.00", "total_cost": "-57900.00", "surplus_price": "0.00", "shortage_price": "0.00", "total_price": "0.00" } ], "total": 1 } Ошибки | Ошибка | Причина | |---|---| | Date is not a valid date in format YYYY-MM-DD | Неверный формат date_from или date_to | | Invalid limit value. Must be between 1 and 1000 | Неверный limit | | Offset requires limit | Передан offset без limit |

Данные инвентаризации

Возвращает инвентаризацию с ее строками: ожидаемым и фактическим остатком и разницей по каждой позиции. v1/audits/get_entry.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | audit_id | int | Да | ID инвентаризации | Ответ Объект audit со всеми полями инвентаризации (см. Инвентаризации) и строками в двух массивах: materials и products. Заполнен только массив того типа, который считает инвентаризация, второй приходит пустым. | Поле | Тип | Описание | |---|---|---| | id | int | ID материала или продукта | | sku | string | Артикул | | name | string | Название | | unit | string | Единица измерения | | expected | float | Ожидаемый остаток на дату инвентаризации | | actual | float | Фактический остаток | | difference | float | Разница: actual минус expected. Положительная означает излишек, отрицательная недостачу | | notes | string | Заметки к строке | | position | int | Порядковый номер строки, с 0 | Строки из ответа можно отправить в v1/audits/edit без изменений: метод возьмет из них id, actual и notes. Пример запроса { "audit_id": 1699 } Пример ответа { "success": true, "audit": { "id": "1699", "num": "24", "date": "2026-09-30", "status": "1", "storage_id": "3998", "storage_name": "Главный", "lines": "2", "surplus_cost": "0.00", "shortage_cost": "-57900.00", "total_cost": "-57900.00", "surplus_price": "0.00", "shortage_price": "0.00", "total_price": "0.00", "materials": [ { "id": "2051", "sku": "M010", "name": "Доска дубовая", "unit": "куб. м", "expected": "4.2", "actual": "3.8", "difference": "-0.4", "notes": "", "position": "0" }, { "id": "2077", "sku": "M022", "name": "Лак мебельный", "unit": "л", "expected": "6", "actual": "0", "difference": "-6", "notes": "Не найдено на складе", "position": "1" } ], "products": [] } } Ошибки | Ошибка | Причина | |---|---| | No audit_id in input | Не передан audit_id | | Audit not found or access denied | Инвентаризация не найдена или удалена |