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

7 статьи Максим От Максим

Методы для инвентаризаций складов

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

Инвентаризации: сверка фактических остатков на складе с остатками в 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 | Возвращает инвентаризацию со строками |

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

Создает инвентаризацию материалов или продуктов на складе. Передавайте только фактические остатки: ожидаемые 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 | Нет | Заметки к строке | Строки передаются только в одном массиве: инвентаризация считает либо материалы, либо продукты. Номер присваивается автоматически. Новая инвентаризация создается в статусе из настройки Статус новой инвентаризации по умолчанию. Пример запроса { "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 | Склад не найден или удален | | Storage location 4001 does not store materials | Склад не хранит позиции типа инвентаризации (для продуктов: does not store products) | | 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, и только в массиве того типа, который считает инвентаризация. Строки заменяются целиком. Пример запроса { "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 — Проведена | Пример запроса { "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_entry. 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 с полями инвентаризации: | Поле | Тип | Описание | |---|---|---| | 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 | Поле 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, "shortage_cost": -57900, "total_cost": -57900, "surplus_price": 0, "shortage_price": 0, "total_price": 0 } ], "total": 1 } Ошибки | Ошибка | Причина | |---|---| | Date is not a valid date in format YYYY-MM-DD | Неверный формат date_from или date_to | | Invalid status value. Must be a number | status не число | | 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 с полями инвентаризации: | Поле | Тип | Описание | |---|---|---| | 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. Заполнен только массив того типа, который считает инвентаризация, второй приходит пустым. | Поле | Тип | Описание | |---|---|---| | 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, "shortage_cost": -57900, "total_cost": -57900, "surplus_price": 0, "shortage_price": 0, "total_price": 0, "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 | Инвентаризация не найдена или удалена |