Поставки: закупки материалов и продуктов у поставщиков. Поставка пополняет остатки на складе и обновляет цены материалов. Через API поставки можно создавать, редактировать и удалять, менять статус и статус оплаты, получать список поставок и данные поставки.
Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, строки операций, постраничная выдача) описаны в статьях Обзор API и Общие правила.
Методы
| Метод | Что делает |
|---|---|
| v1/purchases/add | Создает поставку |
| v1/purchases/edit | Изменяет поставку |
| v1/purchases/delete | Удаляет поставку |
| v1/purchases/update_status | Меняет статус поставки |
| v1/purchases/update_payment | Меняет статус оплаты |
| v1/purchases/get_list | Возвращает поставки компании |
| v1/purchases/get_entry | Возвращает данные поставки со строками |
Поля поставки
| Поле | Тип | Описание |
|---|---|---|
| id | int | ID поставки |
| status | int | Статус, код из таблицы ниже |
| payment | int | Статус оплаты, код из таблицы ниже |
| date_placed | string | Дата заказа поставки |
| date_received | string | Дата получения. Пустая строка, если не задана |
| supplier_id | int | ID поставщика |
| supplier_name | string | Наименование поставщика |
| materials_storage_id | int | Склад материалов |
| materials_storage_name | string | Название склада материалов |
| products_storage_id | int | Склад продуктов |
| products_storage_name | string | Название склада продуктов |
| subtotal | float | Сумма строк |
| delivery_price | float | Стоимость доставки |
| discount | float | Скидка |
| total | float | Итого: subtotal плюс delivery_price минус discount |
| amount | float | Общее количество, если у всех строк одна единица измерения, иначе null |
| lines | int | Число строк |
| shipments_count | int | Число отгрузок, которыми получена поставка |
| notes | string | Заметки |
Статусы
| Код | Статус | Влияние на остатки |
|---|---|---|
| 0 | План | Остаток не меняется, количество попадает в запланированное изменение (planned) |
| 1 | Заказана | Как в статусе «План»: остаток не меняется, количество в запланированном изменении |
| 2 | Частично получена | Полученная часть поступила на склад, остальное в запланированном изменении |
| 3 | Получена | Материалы и продукты поступают на склад |
Новая поставка получает статус из настройки Статус новой поставки по умолчанию в разделе Настройки → Основные. Дальше статус меняется методом v1/purchases/update_status. Статус «Частично получена» через API не ставится: он появляется, когда часть поставки получают отгрузками в интерфейсе Controlata.
Подробнее о запланированном изменении остатка в статье Материалы.
Статусы оплаты
| Код | Статус |
|---|---|
| 0 | Не оплачена |
| 1 | Частично оплачена |
| 2 | Оплачена |
Новая поставка создается неоплаченной. Статус оплаты меняет v1/purchases/update_payment. Это только отметка: на остатки и суммы она не влияет.
Строки поставки
Состав поставки передается в двух массивах: materials для материалов и products для продуктов. Нужна хотя бы одна строка.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| id | int | id или sku | ID материала или продукта |
| sku | string | id или sku | Артикул. Продукт ищется и по альтернативным артикулам |
| amount | float | Да | Количество, больше 0 |
| total | float | Да | Сумма строки до доставки и скидки, 0 или больше |
В отличие от заказов, неизвестная позиция не пропускается: запрос отклоняется с ошибкой, и поставка не создается. Подробнее о поиске позиций в статье Общие правила.
Доставка, скидка и себестоимость строк
Доставка и скидка распределяются по строкам пропорционально их суммам. Себестоимость строки (cost) равна ее сумме (total), умноженной на отношение total поставки к subtotal.
Например, в поставке две строки: доска на 26000 и клей на 4000, доставка 1500. Сумма строк 30000, доставка добавляет к каждой строке 5%:
| Строка | total | cost |
|---|---|---|
| Доска дубовая, 0.2 куб. м | 26000 | 27300 |
| Клей столярный, 10 кг | 4000 | 4200 |
v1/purchases/get_entry возвращает в строке оба значения: total как его передали и cost после распределения.
Цены материалов и себестоимость продуктов
- Цена материала становится равной себестоимости единицы из поставки: cost строки, деленный на количество. В примере выше доска получит цену 136500 за куб. м. Цена обновляется сразу при создании, в любом статусе. После этого Controlata пересчитывает себестоимость продуктов, в состав которых входит материал.
- Продукт без состава (без материалов, продуктов и ресурсов в составе) получает себестоимость единицы из поставки. У продукта с составом себестоимость по-прежнему считается по составу.
- Поставщик добавляется в поставщики материалов и продуктов поставки.
- При редактировании цены обновляются только по измененным строкам. Удаление поставки цены не откатывает.
Склады
Материалы поступают на склад materials_storage_id, продукты на склад products_storage_id. Если склад не передан, берется склад из настроек Склад по умолчанию для поставок материалов и Склад по умолчанию для поставок продуктов (на странице Склады, кнопка Склады по умолчанию). ID складов возвращает v1/storages/get_list.
Поставщик
Поставщик указывается одним из двух способов:
- supplier_id: ID существующего поставщика, например из v1/suppliers/add;
- supplier_name: имя нового поставщика. Controlata создаст его вместе с поставкой из полей ниже.
| Поле | Тип | Описание |
|---|---|---|
| supplier_name | string | Наименование юрлица или имя ИП и физлица |
| supplier_type | int | Тип: 1 юрлицо, 2 ИП, 3 физлицо. По умолчанию 1 |
| supplier_email | string | Электронная почта |
| supplier_phone | string | Телефон |
| supplier_address | string | Юридический адрес |
| supplier_inn | string | ИНН |
| supplier_kpp | string | КПП |
| supplier_ogrn | string | ОГРН |
| supplier_agreement | string | Договор |
| supplier_manager_name | string | Руководитель |
| supplier_manager_post | string | Должность руководителя |
| supplier_notes | string | Заметки о поставщике |
Если переданы оба поля, используется supplier_id, а поля supplier_* игнорируются. Каждая новая поставка с supplier_name создает нового поставщика, даже если поставщик с таким именем уже есть. Для постоянных поставщиков сохраните ID на своей стороне и передавайте supplier_id. Подробнее о полях в статье Поставщики.