Поставки: закупки материалов и продуктов у поставщиков. Поставка пополняет остатки на складе и обновляет цены материалов. Через API поставки можно создавать, редактировать и удалять, менять статус и статус оплаты, получать список поставок и данные поставки.

Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, строки операций, постраничная выдача) описаны в статьях [Обзор API](https://developers.controlata.ru/hc/api-docs/articles/overview) и [Общие правила](https://developers.controlata.ru/hc/api-docs/articles/rules).

## Методы

| Метод | Что делает |
|---|---|
| [v1/purchases/add](https://developers.controlata.ru/hc/api-docs/articles/purchases-add) | Создает поставку |
| [v1/purchases/edit](https://developers.controlata.ru/hc/api-docs/articles/purchases-edit) | Изменяет поставку |
| [v1/purchases/delete](https://developers.controlata.ru/hc/api-docs/articles/purchases-delete) | Удаляет поставку |
| [v1/purchases/update_status](https://developers.controlata.ru/hc/api-docs/articles/purchases-update-status) | Меняет статус поставки |
| [v1/purchases/update_payment](https://developers.controlata.ru/hc/api-docs/articles/purchases-update-payment) | Меняет статус оплаты |
| [v1/purchases/get_list](https://developers.controlata.ru/hc/api-docs/articles/purchases-get-list) | Возвращает поставки компании |
| [v1/purchases/get_entry](https://developers.controlata.ru/hc/api-docs/articles/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](https://developers.controlata.ru/hc/api-docs/articles/purchases-update-status). Статус «Частично получена» через API не ставится: он появляется, когда часть поставки получают отгрузками в интерфейсе Controlata.

Подробнее о запланированном изменении остатка в статье [Материалы](https://developers.controlata.ru/hc/api-docs/articles/materials).

## Статусы оплаты

| Код | Статус |
|---|---|
| 0 | Не оплачена |
| 1 | Частично оплачена |
| 2 | Оплачена |

Новая поставка создается неоплаченной. Статус оплаты меняет [v1/purchases/update_payment](https://developers.controlata.ru/hc/api-docs/articles/purchases-update-payment). Это только отметка: на остатки и суммы она не влияет.

## Строки поставки

Состав поставки передается в двух массивах: materials для материалов и products для продуктов. Нужна хотя бы одна строка.

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| id | int | id или sku | ID материала или продукта |
| sku | string | id или sku | Артикул. Продукт ищется и по альтернативным артикулам |
| amount | float | Да | Количество, больше 0 |
| total | float | Да | Сумма строки до доставки и скидки, 0 или больше |

В отличие от заказов, неизвестная позиция не пропускается: запрос отклоняется с ошибкой, и поставка не создается. Подробнее о поиске позиций в статье [Общие правила](https://developers.controlata.ru/hc/api-docs/articles/rules).

## Доставка, скидка и себестоимость строк

Доставка и скидка распределяются по строкам пропорционально их суммам. Себестоимость строки (cost) равна ее сумме (total), умноженной на отношение total поставки к subtotal.

Например, в поставке две строки: доска на 26000 и клей на 4000, доставка 1500. Сумма строк 30000, доставка добавляет к каждой строке 5%:

| Строка | total | cost |
|---|---|---|
| Доска дубовая, 0.2 куб. м | 26000 | 27300 |
| Клей столярный, 10 кг | 4000 | 4200 |

[v1/purchases/get_entry](https://developers.controlata.ru/hc/api-docs/articles/purchases-get-entry) возвращает в строке оба значения: total как его передали и cost после распределения.

## Цены материалов и себестоимость продуктов

* **Цена материала** становится равной себестоимости единицы из поставки: cost строки, деленный на количество. В примере выше доска получит цену 136500 за куб. м. Цена обновляется сразу при создании, в любом статусе. После этого Controlata пересчитывает себестоимость продуктов, в состав которых входит материал.
* **Продукт без состава** (без материалов, продуктов и ресурсов в составе) получает себестоимость единицы из поставки. У продукта с составом себестоимость по-прежнему считается по составу.
* **Поставщик** добавляется в поставщики материалов и продуктов поставки.
* При редактировании цены обновляются только по измененным строкам. Удаление поставки цены не откатывает.

## Склады

Материалы поступают на склад materials_storage_id, продукты на склад products_storage_id. Если склад не передан, берется склад из настроек **Склад по умолчанию для поставок материалов** и **Склад по умолчанию для поставок продуктов** (на странице **Склады**, кнопка **Склады по умолчанию**). ID складов возвращает [v1/storages/get_list](https://developers.controlata.ru/hc/api-docs/articles/storages-get-list).

## Поставщик

Поставщик указывается одним из двух способов:

* **supplier_id**: ID существующего поставщика, например из [v1/suppliers/add](https://developers.controlata.ru/hc/api-docs/articles/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. Подробнее о полях в статье [Поставщики](https://developers.controlata.ru/hc/api-docs/articles/suppliers).