Материалы

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

Методы для материалов и их остатков

Материалы

Материалы: сырье и комплектующие, из которых производятся продукты. Через API их можно создавать, редактировать и удалять, получать список и данные материала, обновлять остатки на складах. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/materials/add | Создает материал | | v1/materials/edit | Изменяет материал | | v1/materials/delete | Удаляет материал | | v1/materials/update_stock | Устанавливает остаток на складе | | v1/materials/get_list | Возвращает материалы склада | | v1/materials/get_entry | Возвращает данные материала | | v1/materials/get_stocks | Возвращает остатки материалов по всем складам |

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

Создает материал. Материал появляется на складе storage_id и на складах, которые хранят все материалы или его категории. 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 или name | | suppliers | array | Нет | Поставщики: объекты с id | Категорию можно передать по названию: если такой нет, она будет создана. ID существующих категорий и поставщиков возвращают v1/categories/get_list и v1/suppliers/get_list. Уникальность артикула не проверяется. Пример запроса { "name": "Доска дубовая", "sku": "M010", "unit": "куб. м", "price": 130000, "storage_id": 3998, "stock": 2.5, "minimum": 0.5, "categories": [{ "id": 12 }, { "name": "Фурнитура" }], "suppliers": [{ "id": 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 | Поставщик не найден или удален |

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

Изменяет материал. Меняются только переданные поля, остальные остаются прежними. 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 или name. Заменяют текущие целиком | | suppliers | array | Нет | Поставщики: объекты с 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 | Поставщик не найден или удален |

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

Удаляет материал. 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 создаст корректировку на разницу между текущим и новым остатком. v1/materials/update_stock.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | material_id | int | Да | ID материала | | storage_id | int | Да | ID склада | | stock | float | Да | Новый остаток | | notes | string | Нет | Заметки к корректировке | Пример запроса { "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" |

Получение списка материалов

Возвращает материалы, которые числятся на складе (в том числе с нулевым остатком), отсортированные по названию. Архивные материалы тоже входят в список. v1/materials/get_list.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | storage_id | int | Да | ID склада | | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Без limit возвращается весь список. Подробнее о постраничной выдаче в статье Общие правила. Ответ Массив materials с полями материала и его остатком на складе storage_id: | Поле | Тип | Описание | |---|---|---| | id | int | ID материала | | name | string | Название | | sku | string | Артикул | | unit | string | Единица измерения, код из статьи Единицы измерения | | price | float | Цена за единицу | | notes | string | Заметки | | archived | int | 1, если материал в архиве | | stock | float | Остаток на складе storage_id | | minimum | float | Минимальный остаток на складе storage_id | | planned | float | Изменение остатка по операциям в статусе План. null, если таких операций нет | | categories | array | Категории материала: объекты с id и name | | suppliers | array | Поставщики материала: объекты с id и name | Поле total содержит общее число материалов на складе. Пример запроса { "storage_id": 3998, "limit": 100, "offset": 0 } Пример ответа { "success": true, "materials": [ { "id": 2051, "name": "Доска дубовая", "sku": "M010", "price": 135000, "notes": "", "archived": 0, "stock": 4.2, "minimum": 1, "planned": null, "unit": "куб. м", "categories": [ { "id": 12, "name": "Древесина" } ], "suppliers": [ { "id": 45, "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 |

Получение данных материала

Возвращает данные материала и его остаток на складе. v1/materials/get_entry.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | material_id | int | Да | ID материала | | storage_id | int | Да | ID склада | Материал возвращается, только если он числится на складе storage_id. Остатки на всех складах сразу возвращает v1/materials/get_stocks. Ответ Объект material с полями материала, его остатком на складе storage_id, категориями и поставщиками. Категории и поставщиков из ответа можно передать в v1/materials/edit без изменений. | Поле | Тип | Описание | |---|---|---| | id | int | ID материала | | name | string | Название | | sku | string | Артикул | | unit | string | Единица измерения, код из статьи Единицы измерения | | price | float | Цена за единицу | | notes | string | Заметки | | archived | int | 1, если материал в архиве | | stock | float | Остаток на складе storage_id | | minimum | float | Минимальный остаток на складе storage_id | | planned | float | Изменение остатка по операциям в статусе План. null, если таких операций нет | | categories | array | Категории материала: объекты с id и name | | suppliers | array | Поставщики материала: объекты с id и name | Пример запроса { "material_id": 2051, "storage_id": 3998 } Пример ответа { "success": true, "material": { "id": 2051, "name": "Доска дубовая", "sku": "M010", "price": 135000, "notes": "", "archived": 0, "stock": 4.2, "minimum": 1, "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 | Материал не найден, удален или не числится на складе |

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

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