Максим

Максим

Обновлено Oct 21, 2026

Создает заказ. Статус заказа берется из настройки Статус нового заказа по умолчанию в настройках системы, а от статуса зависит, списываются ли продукты и материалы сразу (см. Смену статуса заказа).

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.