Заказы: продажи продуктов, а при включенной настройке и материалов, вашим покупателям. Через API их можно создавать, редактировать и удалять, менять статус и статус оплаты, получать список заказов и данные заказа.

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

## Методы

| Метод | Что делает |
|---|---|
| [v1/orders/add](https://developers.controlata.ru/hc/api-docs/articles/orders-add) | Создает заказ |
| [v1/orders/edit](https://developers.controlata.ru/hc/api-docs/articles/orders-edit) | Изменяет заказ |
| [v1/orders/delete](https://developers.controlata.ru/hc/api-docs/articles/orders-delete) | Удаляет заказ |
| [v1/orders/update_status](https://developers.controlata.ru/hc/api-docs/articles/orders-update-status) | Меняет статус заказа |
| [v1/orders/update_payment](https://developers.controlata.ru/hc/api-docs/articles/orders-update-payment) | Меняет статус оплаты |
| [v1/orders/get_list](https://developers.controlata.ru/hc/api-docs/articles/orders-get-list) | Возвращает заказы компании |
| [v1/orders/get_entry](https://developers.controlata.ru/hc/api-docs/articles/orders-get-entry) | Возвращает данные заказа со строками |

## Поля заказа

| Поле | Тип | Описание |
|---|---|---|
| id | int | ID заказа |
| num | string | Номер заказа вместе с префиксом |
| status | int | Статус, код из таблицы ниже |
| payment | int | Статус оплаты, код из таблицы ниже |
| date_placed | string | Дата заказа |
| date_shipped | string | Дата отправки. Пустая строка, если не задана |
| subtotal | float | Сумма строк |
| delivery_price | float | Стоимость доставки |
| discount | float | Скидка |
| total | float | Итого: subtotal плюс delivery_price минус discount |
| cost | float | Себестоимость заказа |
| amount | float | Общее количество, если у всех строк одна единица измерения, иначе null |
| lines | int | Число строк |
| production | int | 1, если заказ выполняется производством под заказ |
| production_num | string | Номер связанного производства, null без производства |
| source | string | Откуда создан заказ: «manual» (вручную), «api», «tilda», «shopify», «wildberries», «ozon» |
| notes | string | Заметки |
| products_storage_id | int | Склад продуктов |
| materials_storage_id | int | Склад материалов |
| customer_id | int | ID покупателя. Остальные поля покупателя приходят с префиксом customer_ |

Доставка и скидка в заказе не распределяются по строкам: они меняют только итоговую сумму. Себестоимость (cost) считается по списанным позициям, у заказа под производство берется из производства.

## Статусы

| Код | Статус | Влияние на остатки |
|---|---|---|
| 0 | Новый | Остаток не меняется, количество заказа попадает в запланированное изменение (planned) |
| 1 | Упакован | Продукты и материалы списываются со склада |
| 2 | Частично отправлен | Отправленная часть списана, остальное в запланированном изменении |
| 3 | Отправлен | Продукты и материалы списываются со склада |
| 4 | Отменен | Заказ не влияет на остатки |

Новый заказ получает статус из настройки **Статус нового заказа по умолчанию** в разделе **Настройки → Основные**. Дальше статус меняется методом [v1/orders/update_status](https://developers.controlata.ru/hc/api-docs/articles/orders-update-status). Статус «Частично отправлен» через API не ставится: он появляется, когда часть заказа отгружают в интерфейсе Controlata.

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

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

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

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

## Номер заказа

Controlata добавляет к номеру префикс из настройки **Префикс для номеров заказов** в подключении API (см. [Обзор API](https://developers.controlata.ru/hc/api-docs/articles/overview)). Если префикс «A-», то переданный номер «1001» сохранится как «A-1001», и в ответах get_list и get_entry вернется уже «A-1001».

Передавайте num без префикса и при создании, и при редактировании, иначе префикс повторится: «A-A-1001». Уникальность номера не проверяется.

## Строки заказа

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

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

Если позиция не найдена, строка пропускается, а в заметки заказа дописывается сообщение, например:

```
Product with SKU "P099", amount 2, total 5000 not found in Controlata, check sku.
```

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

Материалы в заказах принимаются, только если в разделе **Настройки → Основные** включена **Возможность заказа материалов**. Иначе запрос с материалами отклоняется.

## Склады

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

Вместо products_storage_id можно передать storage_id: так поле называлось, когда склад в заказе был один. В ответах storage_id и storage_name тоже приходят как синонимы склада продуктов.

## Производство под заказ

Если передать production со значением 1, продукты заказа не списываются со склада, а производятся. Controlata создает производство с названием «Под заказ A-1001». Склады, статус и производство заготовок в нем берутся из настроек компании. Себестоимость продуктов заказа берется из этого производства.

* У такого заказа нет склада продуктов: products_storage_id не используется.
* Материалы заказа по-прежнему списываются со склада материалов.
* Если в [v1/orders/edit](https://developers.controlata.ru/hc/api-docs/articles/orders-edit) передать production со значением 0, связанное производство удаляется, а продукты списываются со склада.

Настройка **Способ выполнения нового заказа по умолчанию** на API не влияет: без production заказ выполняется со склада.

## Покупатель

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

* **customer_id**: ID существующего покупателя, например из [v1/customers/add](https://developers.controlata.ru/hc/api-docs/articles/customers-add);
* **customer_name**: имя нового покупателя. Controlata создаст его вместе с заказом из полей ниже.

| Поле | Тип | Описание |
|---|---|---|
| customer_name | string | Наименование юрлица или имя ИП и физлица |
| customer_type | int | Тип: 1 юрлицо, 2 ИП, 3 физлицо. По умолчанию 3 |
| customer_email | string | Электронная почта |
| customer_phone | string | Телефон |
| customer_address_real | string | Адрес доставки |
| customer_address_legal | string | Юридический адрес |
| customer_inn | string | ИНН |
| customer_kpp | string | КПП |
| customer_ogrn | string | ОГРН |
| customer_agreement | string | Договор |
| customer_manager_name | string | Руководитель |
| customer_manager_post | string | Должность руководителя |
| customer_notes | string | Заметки о покупателе |

Если переданы оба поля, используется customer_id, а поля customer_* игнорируются. Каждый новый заказ с customer_name создает нового покупателя, даже если покупатель с таким именем уже есть. Для постоянных покупателей сохраните ID на своей стороне и передавайте customer_id. Подробнее о полях в статье [Покупатели](https://developers.controlata.ru/hc/api-docs/articles/customers).

Покупатель создается только после проверки строк: запрос с ошибкой в строках не оставляет лишних покупателей.