Создает заказ. Статус заказа берется из настройки **Статус нового заказа по умолчанию**, а от статуса зависит, списываются ли продукты и материалы сразу (см. [Заказы](https://developers.controlata.ru/hc/api-docs/articles/orders)).

```
v1/orders/add.php
```

## Параметры

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| num | string | Да | Номер заказа без префикса |
| products | array | Один из двух | Строки продуктов |
| materials | array | Один из двух | Строки материалов. Принимаются при включенной настройке **Возможность заказа материалов** |
| customer_id | int | Один из двух | ID существующего покупателя |
| customer_name | string | Один из двух | Имя нового покупателя. Остальные поля покупателя передаются с префиксом customer_ |
| date_placed | string | Нет | Дата заказа. По умолчанию сегодня |
| date_shipped | string | Нет | Дата отправки |
| products_storage_id | int | Нет | Склад продуктов. По умолчанию склад из настроек. Принимается и старое имя storage_id |
| materials_storage_id | int | Нет | Склад материалов. По умолчанию склад из настроек |
| production | int | Нет | 1, чтобы выполнить заказ производством под заказ. По умолчанию 0 |
| delivery_price | float | Нет | Стоимость доставки. По умолчанию 0 |
| discount | float | Нет | Скидка. По умолчанию 0 |
| notes | string | Нет | Заметки |

Каждая строка в products и materials содержит id или sku, количество amount и сумму строки total. Поля покупателя, склады и производство под заказ описаны в статье [Заказы](https://developers.controlata.ru/hc/api-docs/articles/orders).

## Как работает

* **Номер.** К num добавляется префикс подключения: «1001» сохранится как «A-1001».
* **Ненайденные позиции.** Строка с неизвестным id или артикулом пропускается, а сообщение о ней дописывается в notes. Если не найдена ни одна строка, заказ не создается.
* **Покупатель.** С customer_name каждый запрос создает нового покупателя, даже если такое имя уже есть. ID покупателя возвращается в ответе: сохраните его и передавайте customer_id в следующих заказах.
* **Даты.** Движения по складу датируются датой отправки, а если она не задана, датой заказа.
* **Суммы.** subtotal равен сумме строк, total равен subtotal плюс delivery_price минус discount. Себестоимость заказа Controlata считает сама.
* **Производство под заказ.** С production со значением 1 Controlata создает связанное производство, продукты не списываются со склада.

## Пример запроса

```
{
    "num": "1001",
    "date_placed": "2026-10-06",
    "customer_name": "Иван Петров",
    "customer_phone": "+7 900 123-45-67",
    "customer_email": "ivan@example.com",
    "customer_address_real": "г. Москва, ул. Лесная, д. 5, кв. 12",
    "products": [
        {
            "sku": "P001",
            "amount": 2,
            "total": 26000
        },
        {
            "id": 816,
            "amount": 1,
            "total": 4500
        }
    ],
    "delivery_price": 500,
    "discount": 1000,
    "notes": "Заказ с сайта"
}
```

## Пример ответа

```
{
    "success": true,
    "order_id": 43727,
    "customer_id": 512
}
```

customer_id содержит ID покупателя заказа: найденного по customer_id или созданного по customer_name.

## Ошибки

| Ошибка | Причина |
|---|---|
| No num in input | Не передан num |
| Products is not an array | products не массив (так же для materials) |
| No products or materials in input | Не передано ни одной строки |
| Materials in orders are disabled in company settings | Переданы материалы, а настройка **Возможность заказа материалов** выключена |
| Storage ID is not set | Передан пустой склад |
| Storage ID not found | Склад не найден или удален |
| Date is not a valid date in format YYYY-MM-DD | Неверная дата заказа или отправки |
| Line 0 of products must be an object | Строка не является объектом (вместо 0 будет номер строки) |
| SKU or id not set for product 0 | В строке нет ни id, ни sku |
| Amount not set for product with SKU "P001" | В строке нет amount |
| Total not set for product with SKU "P001" | В строке нет total |
| Amount must be greater than 0 for product with SKU "P001" | Количество не число или не больше 0 после округления |
| Total must be a number for product with SKU "P001" | Сумма строки не число |
| All products have wrong SKU or id | Не найдена ни одна строка. Если переданы материалы, текст будет «All products and materials have wrong SKU or id» |
| No customer_name or customer_id in input | Не передан покупатель |
| Customer not found | Покупатель customer_id не найден или удален |
| Customer name must not be empty | Пустое customer_name |
| Customer name must be a string | customer_name не строка |
| Invalid customer_type value. Must be one of: 1, 2, 3 | Неверный тип покупателя |

В текстах ошибок строк вместо product будет material для строк материалов, а вместо SKU "P001" будет id 816, если строка передана по id.