Создает заказ. Статус заказа берется из настройки Статус нового заказа по умолчанию в настройках системы, а от статуса зависит, списываются ли продукты и материалы сразу (см. Смену статуса заказа).
v1/orders/add.php
Параметры
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| num | string | Да | Номер заказа |
| products | array | products или materials | Строки продуктов |
| materials | array | products или materials | Строки материалов. Принимаются при включенной настройке Возможность заказа материалов |
| customer_id | int | customer_id или customer_name | ID существующего покупателя |
| customer_name | string | customer_id или customer_name | Имя покупателя. Если такого нет, он создается из полей с префиксом customer_ |
| date_placed | string | Нет | Дата заказа. По умолчанию сегодня |
| date_shipped | string | Нет | Дата отправки |
| products_storage_id | int | Нет | Склад продуктов. По умолчанию склад из настроек |
| materials_storage_id | int | Нет | Склад материалов. По умолчанию склад из настроек |
| production | int | Нет | 1, чтобы выполнить заказ производством под заказ. По умолчанию 0 |
| delivery_price | float | Нет | Стоимость доставки. По умолчанию 0 |
| discount | float | Нет | Скидка. По умолчанию 0 |
| notes | string | Нет | Заметки |
Настройка Способ выполнения нового заказа по умолчанию на API не влияет: без production заказ выполняется со склада.
Строки заказа
Состав заказа передается двумя массивами: products для продуктов и materials для материалов. Нужна хотя бы одна строка в одном из массивов.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| id | int | id или sku | ID продукта или материала |
| sku | string | id или sku | Артикул. Продукт ищется и по альтернативным SKU |
| amount | float | Да | Количество |
| total | float | Да | Сумма строки (не цена за единицу) |
| notes | string | Нет | Комментарий к строке |
Если позиция не найдена, строка пропускается, а в заметки заказа дописывается сообщение, например:
Product with SKU "P099", amount 2, total 5000 not found in Controlata, check sku.
Если не найдена ни одна строка, заказ не создается.
Материалы в заказах принимаются, только если в разделе Настройки → Основные включена Возможность заказа материалов. Иначе запрос с материалами отклоняется.
Покупатель
Покупатель указывается одним из двух способов:
- customer_id: ID существующего покупателя, например из v1/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_* не обновляются.
Пример запроса
{
"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,
"notes": "Гравировка: Анна"
},
{
"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 | Неверная дата заказа или отправки |
| Invalid delivery_price value. Must be a number, 0 or greater | Стоимость доставки не число или меньше 0 |
| Invalid discount value. Must be a number, 0 or greater | Скидка не число или меньше 0 |
| 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" | Сумма строки не число |
| Invalid notes value for product with SKU "P001". Must be a string | notes в строке не строка |
| Notes for product with SKU "P001" are too long: maximum 10000 characters | Комментарий строки длиннее 10 000 символов |
| 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.