Ресурсы

Ресурсы

Ресурсы: все, что используется в производстве, но не является материалом. Например, работа сотрудников, электроэнергия, оборудование, накладные расходы. Ресурсы входят в состав продукта и учитываются в его себестоимости, остатков на складах у них нет. Через API ресурсы можно создавать, редактировать и удалять, получать список и данные ресурса. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/resources/add | Создает ресурс | | v1/resources/edit | Изменяет ресурс | | v1/resources/delete | Удаляет ресурс | | v1/resources/get_list | Возвращает ресурсы компании | | v1/resources/get_entry | Возвращает данные ресурса | Поля ресурса | Поле | Тип | Описание | |---|---|---| | id | int | ID ресурса | | name | string | Название | | type | string | Тип расчета: «rate», «percent» или «amortized» | | dynamic | int | 1, если цена или процент указывается в составе продукта | | base | string | База расчета процентного ресурса: «cost» или «price». У других типов null | | unit | string | Единица измерения, код из статьи Единицы измерения. Есть только у фиксированной ставки и амортизации, у остальных null | | price | float | Цена за единицу | | percent | float | Процент процентного ресурса | | initial_cost | float | Первоначальная стоимость оборудования | | useful_life | float | Срок службы в единицах ресурса | | left_life | float | Остаток срока службы. Уменьшается, когда ресурс списывается в производстве | | notes | string | Заметки | | archived | int | 1, если ресурс в архиве | | categories | array | Категории ресурса: id и name | Типы ресурсов Тип расчета определяет, как считается стоимость ресурса в составе продукта и какие поля нужны при создании. | Тип | Как считается стоимость | Обязательные поля | |---|---|---| | «rate», Фиксированная ставка | Цена за единицу, умноженная на количество в составе. Подходит для оплаты труда, электроэнергии, контрактного производства | unit, price | | «rate» с dynamic 1, Цена указывается в составе продукта | Сумма задается отдельно в составе каждого продукта | Нет | | «percent», Процент | Процент от себестоимости или цены продажи продукта. Подходит для накладных расходов, комиссий | base, percent | | «percent» с dynamic 1, Процент указывается в составе продукта | Процент задается отдельно в составе каждого продукта | base | | «amortized», Амортизация | Цена за единицу равна первоначальной стоимости, деленной на срок службы. Подходит для оборудования, транспорта, инструментов | unit, initial_cost, useful_life | База расчета (base) процентного ресурса: - «cost»: себестоимость продукта без учета процентных ресурсов; - «price»: цена продажи из карточки продукта. Поля, которые не относятся к типу, в расчете не участвуют, а часть из них Controlata обнуляет при сохранении: - у фиксированной ставки base становится null, а percent равен 0; - у ставки с ценой в составе продукта price равен 1, а unit приходит как null; - у процентного ресурса price равен 0, а unit приходит как null; если процент указывается в составе продукта, percent тоже равен 0; - у амортизации price рассчитывается из initial_cost и useful_life, а dynamic всегда 0. Единицы измерения Ресурсу можно назначить любую единицу, в том числе единицы времени и энергии, которые доступны только ресурсам: «ч», «мин», «кВт-ч». Список единиц в статье Единицы измерения. Срок службы амортизируемого ресурса указывается в его единице. Указывайте время полезной работы, без простоев: если станок прослужит 2 года и за это время отработает около 2000 часов, передайте unit «ч» и useful_life 2000. Ресурсы в составе продукта Ресурсы добавляются в продукт массивом resources в методах v1/products/add и v1/products/edit. Что передавать в строке для каждого типа, описано в разделе «Состав продукта» статьи Продукты. После изменения или удаления ресурса Controlata пересчитывает себестоимость продуктов, в состав которых он входит.

Создание ресурса

Создает ресурс. Набор обязательных полей зависит от типа расчета, подробнее о типах в статье Ресурсы. v1/resources/add.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | name | string | Да | Название | | type | string | Да | Тип расчета: «rate», «percent» или «amortized» | | dynamic | int | Нет | 1: цена фиксированной ставки или процент процентного ресурса указывается в составе продукта. По умолчанию 0. У амортизации не используется | | unit | string | Для rate и amortized | Единица измерения, код из статьи Единицы измерения. У ставки с dynamic 1 не нужна | | price | float | Для rate | Цена за единицу, 0 или больше. У ставки с dynamic 1 не нужна | | base | string | Для percent | База расчета: «cost» (себестоимость) или «price» (цена продажи) | | percent | float | Для percent | Процент, больше 0 и не больше 100. При dynamic 1 не нужен | | initial_cost | float | Для amortized | Первоначальная стоимость, 0 или больше | | useful_life | float | Для amortized | Срок службы в единицах unit, больше 0 | | notes | string | Нет | Заметки | | categories | array | Нет | ID категорий из v1/categories/get_list с type «resources» | Цена амортизируемого ресурса рассчитывается автоматически: initial_cost / useful_life. Станок за 600000 рублей со сроком службы 2000 часов стоит 300 рублей за час работы. Категории через API не создаются, можно назначить только существующие. В categories можно передать числа или объекты с полем id, как их возвращает v1/resources/get_entry. Примеры запросов Фиксированная ставка: часовая ставка столяра. { "name": "Работа столяра", "type": "rate", "unit": "ч", "price": 600, "categories": [31] } Процент от себестоимости, одинаковый для всех продуктов: { "name": "Накладные расходы", "type": "percent", "base": "cost", "percent": 10 } Комиссия маркетплейса, процент которой задается в составе каждого продукта: { "name": "Комиссия маркетплейса", "type": "percent", "dynamic": 1, "base": "price" } Амортизация оборудования: { "name": "Фрезерный станок", "type": "amortized", "unit": "ч", "initial_cost": 600000, "useful_life": 2000 } Пример ответа { "success": true, "resource_id": 57 } Ошибки | Ошибка | Причина | |---|---| | No name in input | Не передано обязательное поле (вместо name будет имя поля: type или поле, обязательное для типа) | | Name must not be empty | Пустое название | | Name must be a string | Название передано не строкой, например массивом | | Invalid type value. Must be one of: rate, percent, amortized | Неверный type | | Unit not set | Передана пустая единица измерения | | Unit not found | Неизвестная единица измерения | | Invalid price value. Must be a number, 0 or greater | Цена не число или меньше 0 (так же для initial_cost) | | Invalid base value. Must be one of: cost, price | Неверная база расчета | | Percent must be greater than 0 and not exceed 100 | Процент 0, меньше 0 или больше 100 | | Useful life must be greater than 0 | Срок службы 0 или меньше | | Category 12 not found | Категория не найдена |

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

Изменяет ресурс. Меняются только переданные поля, остальные остаются прежними. Подробнее о частичном редактировании в статье Общие правила. v1/resources/edit.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | resource_id | int | Да | ID ресурса | | name | string | Нет | Название | | type | string | Нет | Тип расчета: «rate», «percent» или «amortized» | | dynamic | int | Нет | 1: цена или процент указывается в составе продукта | | unit | string | Нет | Единица измерения. Учитывается только у фиксированной ставки и амортизации | | price | float | Нет | Цена за единицу, 0 или больше | | base | string | Нет | База расчета: «cost» или «price» | | percent | float | Нет | Процент, больше 0 и не больше 100 | | initial_cost | float | Нет | Первоначальная стоимость, 0 или больше | | useful_life | float | Нет | Срок службы в единицах ресурса, больше 0 | | notes | string | Нет | Заметки | | categories | array | Нет | ID категорий. Заменяют текущие целиком | Чтобы очистить заметки, передайте пустую строку, чтобы снять все категории, передайте пустой массив. Какие поля нужны каждому типу, описано в статье Ресурсы. Как работает - Себестоимость. После изменения Controlata пересчитывает себестоимость продуктов, в состав которых входит ресурс. Уже созданные производства не пересчитываются. - Процент. Если у процентного ресурса процент задан в самом ресурсе, новый процент записывается в состав всех продуктов с этим ресурсом. - Смена типа. Передайте вместе с type поля, которых у ресурса еще нет: unit для фиксированной ставки и амортизации, base и percent для процента, initial_cost и useful_life для амортизации. Количество ресурса в составе продуктов при смене типа не пересчитывается, проверьте его после изменения. - Ставка с ценой в составе продукта. У такой ставки сохранены единица «шт» и цена 1. Если переводите ее в обычную фиксированную ставку (dynamic 0), передайте unit и price. - Единица измерения. Если новая единица из той же группы (например, «мин» вместо «ч»), Controlata пересчитывает историю использования ресурса. Цена при этом не пересчитывается: передайте цену за новую единицу. Сменить группу (например, «ч» на «кВт-ч») нельзя, если ресурс входит в состав продукта. - Ресурс уже использован в производстве. У такого ресурса нельзя менять тип расчета, первоначальную стоимость, срок службы и единицу амортизируемого ресурса. Название, заметки, цену, процент, базу расчета и категории менять можно. Пример запроса { "resource_id": 57, "price": 650 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No resource_id in input | Не передан resource_id | | Resource not found or access denied | Ресурс не найден или удален | | Name must not be empty | Передано пустое название | | Name must be a string | Название передано не строкой, например массивом | | Invalid type value. Must be one of: rate, percent, amortized | Неверный type | | No unit in input | Тип сменился на фиксированную ставку или амортизацию, а единицы у ресурса нет | | Unit not set | Передана пустая единица измерения | | Unit not found | Неизвестная единица измерения | | Unit cannot be changed to another unit group: the resource is used in components of products | Смена группы единицы у ресурса из состава продукта | | Invalid price value. Must be a number, 0 or greater | Цена не число или меньше 0 (так же для initial_cost) | | Invalid base value. Must be one of: cost, price | Неверная база расчета или она не передана при смене типа на процент | | Percent must be greater than 0 and not exceed 100 | Процент вне диапазона или не передан при смене типа на процент | | Useful life must be greater than 0 | Срок службы 0 или меньше, или не передан при смене типа на амортизацию | | The resource is already used in production, so these fields cannot be changed: type, useful_life | Ресурс уже списывался в производстве. В конце перечислены поля, которые нельзя менять: type, initial_cost, useful_life, unit | | Category 12 not found | Категория не найдена |

Удаление ресурса

Удаляет ресурс. v1/resources/delete.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | resource_id | int | Да | ID ресурса | Как работает - Ресурс убирается из состава продуктов. Себестоимость этих продуктов пересчитывается, а их производства получают отметку bom_changed. - Файлы ресурса удаляются. - Производства, в которых использовался ресурс, остаются в истории. Пример запроса { "resource_id": 57 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No resource_id in input | Не передан resource_id | | Resource not found or access denied | Ресурс не найден или уже удален |

Список ресурсов

Возвращает ресурсы компании, отсортированные по названию. Архивные ресурсы тоже входят в список. v1/resources/get_list.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Без limit возвращается весь список. Подробнее о постраничной выдаче в статье Общие правила. Ответ Массив resources со всеми полями ресурса и его категориями (см. Ресурсы). Поле total содержит общее число ресурсов. Пример запроса { "limit": 100, "offset": 0 } Пример ответа { "success": true, "resources": [ { "id": "57", "name": "Работа столяра", "type": "rate", "dynamic": "0", "base": null, "unit": "ч", "price": "600", "percent": "0.00", "initial_cost": "0", "useful_life": "0", "left_life": "0", "notes": "", "archived": "0", "categories": [ { "id": "31", "name": "Персонал" } ] }, { "id": "59", "name": "Фрезерный станок", "type": "amortized", "dynamic": "0", "base": null, "unit": "ч", "price": "300", "percent": "0.00", "initial_cost": "600000", "useful_life": "2000", "left_life": "1874.5", "notes": "", "archived": "0", "categories": [] } ], "total": 2 } Ошибки | Ошибка | Причина | |---|---| | Invalid limit value. Must be between 1 and 1000 | Неверный limit | | Invalid offset value. Must be 0 or greater | Неверный offset | | Offset requires limit | Передан offset без limit |

Данные ресурса

Возвращает данные ресурса. v1/resources/get_entry.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | resource_id | int | Да | ID ресурса | Ответ Объект resource со всеми полями ресурса и его категориями (см. Ресурсы). Категории из ответа можно передать в v1/resources/edit без изменений. Пример запроса { "resource_id": 58 } Пример ответа { "success": true, "resource": { "id": "58", "name": "Накладные расходы", "type": "percent", "dynamic": "0", "base": "cost", "unit": null, "price": "0", "percent": "10.00", "initial_cost": "0", "useful_life": "0", "left_life": "0", "notes": "", "archived": "0", "categories": [] } } Ошибки | Ошибка | Причина | |---|---| | No resource_id in input | Не передан resource_id | | Resource not found or access denied | Ресурс не найден или удален |