Материалы

Материалы

Материалы: сырье и комплектующие, из которых производятся продукты. Через API их можно создавать, редактировать и удалять, получать список и данные материала, обновлять остатки на складах. Общие для всех методов правила (авторизация, формат запросов, частичное редактирование, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | materials/add | Создает материал | | materials/edit | Изменяет материал | | materials/delete | Удаляет материал | | materials/update_stock | Устанавливает остаток на складе | | materials/get_list | Возвращает материалы склада | | materials/get_entry | Возвращает данные материала | | materials/get_stocks | Возвращает остатки материалов по всем складам | Поля материала | Поле | Тип | Описание | |---|---|---| | id | int | ID материала | | name | string | Название | | sku | string | Артикул | | unit | string | Единица измерения, код из статьи Справочники | | price | float | Цена за единицу. Используется для расчета себестоимости продуктов | | notes | string | Заметки | | archived | int | 1, если материал в архиве | | categories | array | Категории материала: id и name | | suppliers | array | Поставщики материала: id и name | Остатки на складах Остаток, минимальный остаток и запланированное изменение хранятся отдельно для каждого склада. Поэтому методы, которые их возвращают или меняют, принимают storage_id. | Поле | Тип | Описание | |---|---|---| | stock | float | Остаток на складе | | minimum | float | Минимальный остаток на складе | | planned | float | Изменение остатка по операциям в статусе План (поставки, производства, заказы). null, если таких операций нет | Материал числится на складе, если у него там есть строка остатка, в том числе с нулевым остатком. Такая строка появляется: - на складе, указанном при создании материала; - на складах, где в настройках материалов выбрано Все, и на складах, чьи категории совпадают с категориями материала; - на любом другом складе, когда туда приходит остаток (поставка, перемещение, обновление остатка). Если остаток на таком складе снова становится нулевым, строка удаляется. Методы get_list и get_entry видят материал только на тех складах, где у него есть строка остатка. Цена и себестоимость Цена материала (price) определяет себестоимость продуктов, в состав которых он входит. При изменении цены Controlata пересчитывает себестоимость таких продуктов. Поставка материала обновляет его цену по сумме поставки.

Создание материала

Создает материал. Материал появляется на складе storage_id и на складах, которые хранят все материалы или его категории. POST https://api.controlata.ru/connect/v1/materials/add.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | name | string | Да | Название | | unit | string | Да | Единица измерения, код из статьи Справочники | | storage_id | int | Да | Склад, на котором создается остаток | | sku | string | Нет | Артикул | | price | float | Нет | Цена за единицу. По умолчанию 0 | | stock | float | Нет | Начальный остаток на складе storage_id. По умолчанию 0 | | minimum | float | Нет | Минимальный остаток на складе storage_id. По умолчанию 0 | | notes | string | Нет | Заметки | | categories | array | Нет | ID категорий из categories/get_list | | suppliers | array | Нет | ID поставщиков | Начальный остаток оценивается по цене материала. Категории через API не создаются, можно назначить только существующие. В categories и suppliers можно передать числа или объекты с полем id, как их возвращает materials/get_entry. Уникальность артикула не проверяется. Пример запроса { "name": "Доска дубовая", "sku": "M010", "unit": "куб. м", "price": 130000, "storage_id": 3998, "stock": 2.5, "minimum": 0.5, "categories": [12], "suppliers": [45] } Пример ответа { "success": true, "material_id": 2051 } Ошибки | Ошибка | Причина | |---|---| | No name in input | Не передано обязательное поле (вместо name будет имя поля) | | Name must not be empty | Пустое название | | Unit not found | Неизвестная единица измерения или единица только для ресурсов | | Storage ID not found | Склад не найден или удален | | Invalid price value. Must be a number | Значение не число, например "12,5" (так же для stock и minimum) | | Category 12 not found | Категория не найдена | | Supplier not found or access denied | Поставщик не найден или удален |

Редактирование материала

Изменяет материал. Меняются только переданные поля, остальные остаются прежними. Подробнее о частичном редактировании в статье Общие правила. POST https://api.controlata.ru/connect/v1/materials/edit.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | material_id | int | Да | ID материала | | name | string | Нет | Название | | sku | string | Нет | Артикул | | unit | string | Нет | Единица измерения | | price | float | Нет | Цена за единицу | | notes | string | Нет | Заметки | | minimum | float | Нет | Минимальный остаток на складе storage_id | | storage_id | int | С minimum | Склад, на котором меняется минимальный остаток | | categories | array | Нет | ID категорий. Заменяют текущие целиком | | suppliers | array | Нет | ID поставщиков. Заменяют текущих целиком | Чтобы очистить поле, передайте пустую строку, чтобы снять все категории или поставщиков, передайте пустой массив. Как работает - Цена. После изменения цены Controlata пересчитывает себестоимость продуктов, в состав которых входит материал. Если поставок этого материала еще не было, по новой цене переоцениваются и начальный остаток, и корректировки остатка. - Единица измерения. Если новая единица из той же группы (например, г вместо кг), Controlata пересчитывает остатки, историю движений и минимальный остаток. Если цена не передана, она тоже пересчитывается: 500 за кг станет 0.5 за г. Сменить группу (например, шт на кг) нельзя, если материал входит в состав продукта. - Минимальный остаток задается на конкретном складе, поэтому вместе с ним нужен storage_id. Материал должен числиться на этом складе (см. Материалы). - Категории определяют, на каких складах числится материал. После их изменения материал появится на складах с новыми категориями. Пример запроса { "material_id": 2051, "price": 135000, "minimum": 1, "storage_id": 3998 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No material_id in input | Не передан material_id | | Material not found or access denied | Материал не найден или удален | | Name must not be empty | Передано пустое название | | Unit not found | Неизвестная единица измерения | | Unit cannot be changed to another unit group: the material is used in components of products | Смена группы единицы у материала из состава продукта | | No storage_id in input | Передан minimum без storage_id | | Material is not stored in storage location 3998, so its minimum cannot be set there | Материал не числится на складе | | Invalid price value. Must be a number | Значение не число (так же для minimum) | | Category 12 not found | Категория не найдена | | Supplier not found or access denied | Поставщик не найден или удален |

Удаление материала

Удаляет материал. POST https://api.controlata.ru/connect/v1/materials/delete.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | material_id | int | Да | ID материала | Как работает - Остатки материала на всех складах обнуляются корректировкой. - Материал убирается из состава продуктов, себестоимость этих продуктов пересчитывается. - Файлы материала удаляются. - Поставки, производства и другие операции с материалом остаются в истории. Пример запроса { "material_id": 2051 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No material_id in input | Не передан material_id | | Material not found or access denied | Материал не найден или уже удален |

Обновление остатка материала

Устанавливает остаток материала на складе. Передается итоговый остаток, а не изменение: Controlata создаст корректировку на разницу между текущим и новым остатком. POST https://api.controlata.ru/connect/v1/materials/update_stock.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | material_id | int | Да | ID материала | | storage_id | int | Да | ID склада | | stock | float | Да | Новый остаток | | notes | string | Нет | Заметки к корректировке | Как работает - Увеличение остатка оценивается по цене материала, уменьшение списывает партии по FIFO. - Остаток можно установить на любом складе, даже если материал там раньше не числился. На таком складе материал будет числиться, пока остаток не станет нулевым (см. Материалы). Пример запроса { "material_id": 2051, "storage_id": 3998, "stock": 4.2, "notes": "Инвентаризация на складе" } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No stock in input | Не передано обязательное поле (вместо stock будет имя поля) | | Material not found or access denied | Материал не найден или удален | | Storage ID not found | Склад не найден или удален | | Invalid stock value. Must be a number | Остаток не число, например "" или "4,2" |

Список материалов

Возвращает материалы, которые числятся на складе (в том числе с нулевым остатком), отсортированные по названию. Архивные материалы тоже входят в список. POST https://api.controlata.ru/connect/v1/materials/get_list.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | storage_id | int | Да | ID склада | | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Без limit возвращается весь список. Подробнее о постраничной выдаче в статье Общие правила. Ответ Массив materials с полями материала и его остатка на складе storage_id (см. Материалы), без поставщиков. Поле total содержит общее число материалов на складе. Пример запроса { "storage_id": 3998, "limit": 100, "offset": 0 } Пример ответа { "success": true, "materials": [ { "id": "2051", "name": "Доска дубовая", "sku": "M010", "price": "135000", "notes": "", "archived": "0", "stock": "4.200", "minimum": "1.000", "planned": null, "unit": "куб. м", "categories": [ { "id": "12", "name": "Древесина" } ] } ], "total": 1 } Ошибки | Ошибка | Причина | |---|---| | No storage_id in input | Не передан storage_id | | Storage ID not found | Склад не найден или удален | | Invalid limit value. Must be between 1 and 1000 | Неверный limit | | Offset requires limit | Передан offset без limit |

Данные материала

Возвращает данные материала и его остаток на складе. POST https://api.controlata.ru/connect/v1/materials/get_entry.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | material_id | int | Да | ID материала | | storage_id | int | Да | ID склада | Материал возвращается, только если он числится на складе storage_id. Остатки на всех складах сразу возвращает materials/get_stocks. Ответ Объект material со всеми полями материала, его остатком на складе storage_id, категориями и поставщиками (см. Материалы). Категории и поставщиков из ответа можно передать в materials/edit без изменений. Пример запроса { "material_id": 2051, "storage_id": 3998 } Пример ответа { "success": true, "material": { "id": "2051", "name": "Доска дубовая", "sku": "M010", "price": "135000", "notes": "", "archived": "0", "stock": "4.200", "minimum": "1.000", "planned": null, "unit": "куб. м", "categories": [ { "id": "12", "name": "Древесина" } ], "suppliers": [ { "id": "45", "name": "ООО Лесторг" } ] } } Ошибки | Ошибка | Причина | |---|---| | No material_id in input | Не передано обязательное поле (вместо material_id будет имя поля) | | Storage ID not found | Склад не найден или удален | | Material not found or access denied | Материал не найден, удален или не числится на складе |

Остатки материалов по складам

Возвращает остатки материалов по всем складам одним списком: строку на каждую пару «материал, склад», где материал числится. POST https://api.controlata.ru/connect/v1/materials/get_stocks.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | ids | array | Нет | ID материалов. Без них возвращаются все материалы | | storage_id | int | Нет | Только этот склад | | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Строки отсортированы по ID материала и склада. Удаленные материалы и склады в список не входят. Пример запроса { "ids": [2051, 2052] } Пример ответа { "success": true, "stocks": [ { "material_id": "2051", "storage_id": "3998", "stock": "4.200", "minimum": "1.000", "planned": null }, { "material_id": "2051", "storage_id": "4002", "stock": "0.000", "minimum": "0.000", "planned": "1.500" } ], "total": 2 } Ошибки | Ошибка | Причина | |---|---| | Ids is not an array | ids передан не массивом | | Storage ID not found | Склад не найден или удален | | Invalid limit value. Must be between 1 and 1000 | Неверный limit |