Продукты

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

Методы для продуктов, их состава и остатков

Продукты

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

Создание продукта

Создает продукт вместе с составом. Продукт появляется на складе storage_id и на складах, которые хранят все продукты или его категории. v1/products/add.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | name | string | Да | Название | | unit | string | Да | Единица измерения, код из статьи Единицы измерения | | storage_id | int | Да | Склад, на котором создается остаток | | sku | string | Нет | Артикул | | price | float | Нет | Цена продажи за единицу. По умолчанию 0 | | batch_size | float | Нет | Размер партии: на какое количество продукта указан состав. По умолчанию 1 | | stock | float | Нет | Начальный остаток на складе storage_id. По умолчанию 0 | | minimum | float | Нет | Минимальный остаток на складе storage_id. По умолчанию 0 | | notes | string | Нет | Заметки | | categories | array | Нет | Категории: объекты с id или name (см. Категории) | | suppliers | array | Нет | ID поставщиков из v1/suppliers/get_list | | alternative_sku | array | Нет | Альтернативные SKU: объекты с полями sku и label (необязательная подпись) | | materials | array | Нет | Материалы в составе | | products | array | Нет | Заготовки в составе | | resources | array | Нет | Ресурсы в составе | Категорию можно передать по названию: если такой нет, она будет создана. ID существующих категорий возвращает v1/categories/get_list. Уникальность основного и альтернативных SKU не проверяется. Состав продукта Состав задается на одну партию (batch_size единиц) и передается массивами materials (материалы), products (заготовки) и resources (ресурсы). Строки materials и products | Поле | Тип | Обязательное | Описание | |---|---|---|---| | id | int | Да | ID материала или продукта | | amount_per_batch | float | Да | Количество на партию | | unit | string | Да | Единица строки. Из той же группы, что единица материала или продукта: для материала в «кг» подойдут «кг» или «г» | | loss_percent | float | Нет | Потери в процентах. По умолчанию 0. Принимаются, только если в настройках компании включено отображение потерь в составе | | position | int | Нет | Порядковый номер строки в составе | position задает порядок строк состава в интерфейсе Controlata, общий для materials и products. Строки без него идут последними, в порядке передачи. Controlata перенумеровывает позиции с 0, поэтому в Получении данных продукта они могут отличаться от переданных. Строки resources Каждая строка ресурса содержит id ресурса. Нужны ли amount_per_batch и unit, зависит от типа ресурса (о типах в статье Создание ресурса): | Тип ресурса | amount_per_batch | unit | |---|---|---| | Фиксированная ставка | Количество на партию, например часы работы | Нужен | | Фиксированная ставка, цена указывается в составе продукта | Сумма на партию в рублях | Не нужен | | Процент | Не передается: берется из ресурса | Не нужен | | Процент, указывается в составе продукта | Процент | Не нужен | | Амортизация | Количество на партию, например часы работы оборудования | Нужен | Пример запроса Стол: в партии 10 штук, на партию уходит 0.5 куб. м доски с потерями 5%, 400 саморезов, 40 ножек (заготовка) и 30 часов работы столяра. Накладные расходы считаются процентом, который задан в самом ресурсе, поэтому для него достаточно id. { "name": "Стол обеденный", "sku": "P100", "unit": "шт", "price": 45000, "batch_size": 10, "storage_id": 3999, "stock": 5, "minimum": 2, "categories": [{ "id": 21 }], "suppliers": [{ "id": 46 }], "alternative_sku": [ { "label": "Ozon", "sku": "OZ-P100" } ], "materials": [ { "id": 2051, "amount_per_batch": 0.5, "unit": "куб. м", "loss_percent": 5 }, { "id": 2060, "amount_per_batch": 400, "unit": "шт" } ], "products": [ { "id": 312, "amount_per_batch": 40, "unit": "шт" } ], "resources": [ { "id": 57, "amount_per_batch": 30, "unit": "ч" }, { "id": 58 } ] } Пример ответа { "success": true, "product_id": 3120 } Ошибки | Ошибка | Причина | |---|---| | No name in input | Не передано обязательное поле (вместо name будет имя поля) | | Name must not be empty | Пустое название | | Name must be a string | Название передано не строкой, например массивом | | Unit not set | Передана пустая единица измерения | | Unit not found | Неизвестная единица измерения или единица только для ресурсов | | Storage ID is not set | storage_id равен 0 или пустой | | Storage ID not found | Склад не найден или удален | | Batch size must be greater than 0 | Размер партии 0 или меньше | | Invalid price value. Must be a number | Значение не число, например "12,5" (так же для batch_size, stock и minimum) | | Category 12 not found | Категория не найдена | | Supplier not found or access denied | Поставщик не найден или удален | | Alternative_sku is not an array | alternative_sku передан не массивом | | SKU must be from 1 to 50 characters for alternative_sku 0 | Альтернативный SKU пустой или длиннее 50 символов (в конце номер строки с 0) | | Label must not exceed 100 characters for alternative_sku 0 | Подпись альтернативного SKU длиннее 100 символов | Ошибки в строках состава В тексте ошибки вместо 2051 будет ID позиции, а вместо 0 номер строки в массиве (с 0). | Ошибка | Причина | |---|---| | Materials is not an array | materials передан не массивом (так же для products и resources) | | Line 0 of materials must be an object | Строка не объект (так же для products и resources) | | No id for material 0 | Не передан id материала или он не число (так же для product) | | Material 2051 not found | Материал не найден или удален | | Product 2051 not found | Продукт не найден или удален | | Product cannot be a component of itself | Продукт добавлен в собственный состав | | Amount per batch must be greater than 0 for material 2051 | Количество не передано, не число или после округления до 3 знаков равно 0 (так же для product и resource) | | Unit not found for material 2051. Use a unit of the same group as the material unit | Единица не передана, неизвестна или из другой группы (так же для product) | | Loss percent must be from 0 to 100 for material 2051 | Потери меньше 0, не меньше 100 или не число (так же для product) | | Loss percent is disabled in company settings for material 2051 | Потери переданы, но в настройках компании выключено их отображение в составе (так же для product) | | Resource for line 0 not found | Ресурс не найден или удален | | Percent must not exceed 100 for resource 2051 | Процент в составе больше 100 | | Unit not found for resource 2051. Use a unit of the same group as the resource unit | Единица ресурса не передана, неизвестна или из другой группы |

Редактирование продукта

Изменяет продукт и его состав. Меняются только переданные поля, остальные остаются прежними. v1/products/edit.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | product_id | int | Да | ID продукта | | name | string | Нет | Название | | sku | string | Нет | Артикул | | unit | string | Нет | Единица измерения | | price | float | Нет | Цена продажи за единицу | | batch_size | float | Нет | Размер партии | | notes | string | Нет | Заметки | | minimum | float | Нет | Минимальный остаток на складе storage_id | | storage_id | int | С minimum | Склад, на котором меняется минимальный остаток | | categories | array | Нет | Категории: объекты с id или name. Заменяют текущие целиком | | suppliers | array | Нет | Поставщики: объекты с id. Заменяют текущих целиком | | alternative_sku | array | Нет | Альтернативные SKU: объекты с полями sku и label. Заменяют текущие целиком | | materials | array | Нет | Материалы в составе | | products | array | Нет | Заготовки в составе | | resources | array | Нет | Ресурсы в составе. Заменяют текущие целиком | Состав продукта Состав задается на одну партию (batch_size единиц) и передается массивами materials (материалы), products (заготовки) и resources (ресурсы). Строки materials и products | Поле | Тип | Обязательное | Описание | |---|---|---|---| | id | int | Да | ID материала или продукта | | amount_per_batch | float | Да | Количество на партию | | unit | string | Да | Единица строки. Из той же группы, что единица материала или продукта: для материала в «кг» подойдут «кг» или «г» | | loss_percent | float | Нет | Потери в процентах. По умолчанию 0. Принимаются, только если в настройках компании включено отображение потерь в составе | | position | int | Нет | Порядковый номер строки в составе | Если передан хотя бы один из массивов materials и products, материалы и заготовки заменяются целиком, а непереданный массив считается пустым. Например, если передать только materials, заготовки из состава удалятся. position задает порядок строк состава в интерфейсе Controlata, общий для materials и products. Строки без него идут последними, в порядке передачи. Controlata перенумеровывает позиции с 0, поэтому в Получении данных продукта они могут отличаться от переданных. Строки resources Каждая строка ресурса содержит id ресурса. Нужны ли amount_per_batch и unit, зависит от типа ресурса (о типах в статье Создание ресурса): | Тип ресурса | amount_per_batch | unit | |---|---|---| | Фиксированная ставка | Количество на партию, например часы работы | Нужен | | Фиксированная ставка, цена указывается в составе продукта | Сумма на партию в рублях | Не нужен | | Процент | Не передается: берется из ресурса | Не нужен | | Процент, указывается в составе продукта | Процент | Не нужен | | Амортизация | Количество на партию, например часы работы оборудования | Нужен | Пример запроса Новая цена продажи и состав материалов. Заготовки не переданы, поэтому удалятся из состава, ресурсы останутся прежними. { "product_id": 3120, "price": 47000, "materials": [ { "id": 2051, "amount_per_batch": 0.6, "unit": "куб. м", "loss_percent": 5 }, { "id": 2060, "amount_per_batch": 400, "unit": "шт" } ] } Изменить только минимальный остаток: { "product_id": 3120, "minimum": 3, "storage_id": 3999 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No product_id in input | Не передан product_id | | Product not found or access denied | Продукт не найден или удален | | Name must not be empty | Передано пустое название | | Name must be a string | Название передано не строкой, например массивом | | Unit not set | Передана пустая единица измерения | | Unit not found | Неизвестная единица измерения | | Unit cannot be changed to another unit group: the product is used in components of other products | Смена группы единицы у продукта, который входит в состав других продуктов | | Batch size must be greater than 0 | Размер партии 0 или меньше | | No storage_id in input | Передан minimum без storage_id | | Storage ID not found | Склад не найден или удален | | Product is not stored in storage location 3999, so its minimum cannot be set there | Продукт не числится на складе | | Invalid price value. Must be a number | Значение не число (так же для batch_size и minimum) | | Category 12 not found | Категория не найдена | | Supplier not found or access denied | Поставщик не найден или удален | | SKU must be from 1 to 50 characters for alternative_sku 0 | Альтернативный SKU пустой или длиннее 50 символов | | Label must not exceed 100 characters for alternative_sku 0 | Подпись альтернативного SKU длиннее 100 символов | Ошибки в строках состава В тексте ошибки вместо 2051 будет ID позиции, а вместо 0 номер строки в массиве (с 0). | Ошибка | Причина | |---|---| | Materials is not an array | materials передан не массивом (так же для products и resources) | | Line 0 of materials must be an object | Строка не объект (так же для products и resources) | | No id for material 0 | Не передан id материала или он не число (так же для product) | | Material 2051 not found | Материал не найден или удален | | Product 2051 not found | Продукт не найден или удален | | Product cannot be a component of itself | Продукт добавлен в собственный состав | | Amount per batch must be greater than 0 for material 2051 | Количество не передано, не число или после округления до 3 знаков равно 0 (так же для product и resource) | | Unit not found for material 2051. Use a unit of the same group as the material unit | Единица не передана, неизвестна или из другой группы (так же для product) | | Loss percent must be from 0 to 100 for material 2051 | Потери меньше 0, не меньше 100 или не число (так же для product) | | Loss percent is disabled in company settings for material 2051 | Потери переданы, но в настройках компании выключено их отображение в составе (так же для product) | | Resource for line 0 not found | Ресурс не найден или удален | | Percent must not exceed 100 for resource 2051 | Процент в составе больше 100 | | Unit not found for resource 2051. Use a unit of the same group as the resource unit | Единица ресурса не передана, неизвестна или из другой группы |

Удаление продукта

Удаляет продукт. v1/products/delete.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | product_id | int | Да | ID продукта | Пример запроса { "product_id": 3120 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No product_id in input | Не передан product_id | | Product not found or access denied | Продукт не найден или уже удален |

Обновление остатка продукта

Устанавливает остаток продукта на складе. Передается итоговый остаток, а не изменение: Controlata создаст корректировку на разницу между текущим и новым остатком. v1/products/update_stock.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | product_id | int | Да | ID продукта | | storage_id | int | Да | ID склада | | stock | float | Да | Новый остаток | | notes | string | Нет | Заметки к корректировке | Если в Controlata подключена синхронизация остатков с Wildberries или Ozon, новый остаток передается в маркетплейс по ее настройкам, как и при любом другом изменении остатка. Пример запроса { "product_id": 3120, "storage_id": 3999, "stock": 12, "notes": "Инвентаризация на складе" } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No stock in input | Не передано обязательное поле (вместо stock будет имя поля) | | Invalid stock value. Must be a number | Остаток не число, например "" или "4,2" | | Storage ID not found | Склад не найден или удален | | Product not found or access denied | Продукт не найден или удален |

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

Возвращает продукты, которые числятся на складе (в том числе с нулевым остатком), отсортированные по названию. Архивные продукты тоже входят в список. v1/products/get_list.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | storage_id | int | Да | ID склада | | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Без limit возвращается весь список. Подробнее о постраничной выдаче в статье Общие правила. Ответ Массив products с полями продукта и его остатком на складе storage_id, без альтернативных SKU и состава: | Поле | Тип | Описание | |---|---|---| | id | int | ID продукта | | name | string | Название | | sku | string | Артикул | | unit | string | Единица измерения, код из статьи Единицы измерения | | price | float | Цена продажи за единицу | | cost | float | Себестоимость единицы | | batch_size | float | Размер партии: на какое количество продукта указан состав | | notes | string | Заметки | | status | int | Всегда 1: удаленные продукты не возвращаются | | 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": 3999, "limit": 100, "offset": 0 } Пример ответа { "success": true, "products": [ { "id": 3120, "name": "Стол обеденный", "sku": "P100", "price": 45000, "cost": 13604.25, "batch_size": 10, "notes": "", "status": 1, "archived": 0, "stock": 12, "minimum": 3, "planned": null, "unit": "шт", "categories": [ { "id": 21, "name": "Мебель" } ], "suppliers": [ { "id": 52, "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 |

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

Возвращает данные продукта, его остаток на складе и состав. v2/products/get_entry.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | product_id | int | Да | ID продукта | | storage_id | int | Да | ID склада | Продукт возвращается, только если он числится на складе storage_id. Остатки на всех складах сразу возвращает v1/products/get_stocks. Ответ Объект product с полями продукта, остатком на складе storage_id, категориями, поставщиками, альтернативными SKU и составом. | Поле | Тип | Описание | |---|---|---| | id | int | ID продукта | | name | string | Название | | sku | string | Артикул | | unit | string | Единица измерения, код из статьи Единицы измерения | | price | float | Цена продажи за единицу | | cost | float | Себестоимость единицы | | batch_size | 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 | | alternative_sku | array | Альтернативные SKU: объекты с label и sku | Кроме перечисленных полей в объекте есть состав: | Поле | Тип | Описание | |---|---|---| | materials | array | Материалы в составе | | products | array | Заготовки в составе | | resources | array | Ресурсы в составе | Поля строк materials, products и resources: | Поле | Описание | |---|---| | id | ID материала, продукта или ресурса | | name | Название | | sku | Артикул. Только у материалов и заготовок | | type | Тип расчета ресурса. Только у ресурсов (см. Создание ресурса) | | dynamic | 1, если цена или процент указывается в составе продукта. Только у ресурсов | | base | База расчета процентного ресурса: cost или price. Только у ресурсов | | amount_per_batch | Количество на партию | | amount_per_unit | Количество на единицу продукта: amount_per_batch / batch_size | | loss_percent | Потери в процентах. Только у материалов и заготовок | | unit | Единица измерения. У процентного ресурса «%» | | cost_per_unit | Стоимость строки на единицу продукта | | cost_per_batch | Стоимость строки на партию | | position | Порядковый номер строки: общий для materials и products, отдельный для resources | У ресурса с типом фиксированная ставка и ценой в составе продукта amount_per_batch содержит сумму в рублях, а не количество. cost_per_unit и cost_per_batch учитывают потери при loss_percent > 0. Строки состава, категории и поставщиков из ответа можно передать в v1/products/edit без изменений. Пример запроса { "product_id": 3120, "storage_id": 3999 } Пример ответа { "success": true, "product": { "id": 3120, "name": "Стол обеденный", "sku": "P100", "price": 45000, "cost": 13604.25, "batch_size": 10, "notes": "", "archived": 0, "stock": 12, "minimum": 3, "planned": null, "unit": "шт", "categories": [ { "id": 21, "name": "Мебель" } ], "alternative_sku": [ { "label": "Ozon", "sku": "OZ-P100" } ], "suppliers": [ { "id": 46, "name": "ООО Мебельторг" } ], "materials": [ { "id": 2051, "name": "Доска дубовая", "sku": "M010", "amount_per_unit": 0.05, "amount_per_batch": 0.5, "loss_percent": 5, "unit": "куб. м", "cost_per_unit": 7087.5, "cost_per_batch": 70875, "position": 0 }, { "id": 2060, "name": "Саморез 4x40", "sku": "M024", "amount_per_unit": 40, "amount_per_batch": 400, "loss_percent": 0, "unit": "шт", "cost_per_unit": 80, "cost_per_batch": 800, "position": 1 } ], "products": [ { "id": 312, "name": "Ножка стола", "sku": "P012", "amount_per_unit": 4, "amount_per_batch": 40, "loss_percent": 0, "unit": "шт", "cost_per_unit": 3400, "cost_per_batch": 34000, "position": 2 } ], "resources": [ { "id": 57, "name": "Работа столяра", "type": "rate", "dynamic": 0, "base": null, "amount_per_unit": 3, "amount_per_batch": 30, "unit": "ч", "cost_per_unit": 1800, "cost_per_batch": 18000, "position": 0 }, { "id": 58, "name": "Накладные расходы", "type": "percent", "dynamic": 0, "base": "cost", "amount_per_unit": 10, "amount_per_batch": 10, "unit": "%", "cost_per_unit": 1236.75, "cost_per_batch": 12367.5, "position": 1 } ] } } Ошибки | Ошибка | Причина | |---|---| | No product_id in input | Не передано обязательное поле (вместо product_id будет имя поля) | | Storage ID not found | Склад не найден или удален | | Product not found or access denied | Продукт не найден, удален или не числится на складе | Версия v1 Метод v1/products/get_entry принимает те же параметры и возвращает те же поля продукта. Отличается только представление состава, поэтому в новых интеграциях используйте v2. | Что | v1 | v2 | |---|---|---| | Состав | Один массив components: материалы и заготовки вместе | Раздельные массивы materials, products и resources | | id в строках состава | Префиксные: «m-123» для материала, «p-45» для заготовки | Числовой id позиции | | Отправка строк обратно в add и edit | Нельзя без изменений, мешают префиксные id | Можно как есть | Кроме того, v1 возвращает служебные поля, которые v2 опускает: product.status и status строк состава (всегда 1) и product.percent (вычисляется из cost и price).

Остатки продуктов

Возвращает остатки продуктов по всем складам одним списком: строку на каждую пару «продукт, склад», где продукт числится. v1/products/get_stocks.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | product_ids | array | Нет | ID продуктов. Без них возвращаются все продукты | | storage_ids | array | Нет | Только эти склады. Без них все склады | | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Строки отсортированы по ID продукта и склада. Удаленные продукты и склады в список не входят. Поле total содержит общее число строк, подходящих под фильтры. Пример запроса { "product_ids": [3120, 312] } Пример ответа { "success": true, "stocks": [ { "product_id": 312, "storage_id": 3999, "stock": 86, "minimum": 40, "planned": -40 }, { "product_id": 3120, "storage_id": 3999, "stock": 12, "minimum": 3, "planned": null }, { "product_id": 3120, "storage_id": 4005, "stock": 0, "minimum": 0, "planned": 10 } ], "total": 3 } Ошибки | Ошибка | Причина | |---|---| | Product_ids is not an array | product_ids передан не массивом | | Storage_ids is not an array | storage_ids передан не массивом | | Storage ID not found | Склад не найден или удален | | Invalid limit value. Must be between 1 and 1000 | Неверный limit |