Заказы

Заказы

Заказы: продажи продуктов, а при включенной настройке и материалов, вашим покупателям. Через API их можно создавать, редактировать и удалять, менять статус и статус оплаты, получать список заказов и данные заказа. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, строки операций, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/orders/add | Создает заказ | | v1/orders/edit | Изменяет заказ | | v1/orders/delete | Удаляет заказ | | v1/orders/update_status | Меняет статус заказа | | v1/orders/update_payment | Меняет статус оплаты | | v1/orders/get_list | Возвращает заказы компании | | v1/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. Статус «Частично отправлен» через API не ставится: он появляется, когда часть заказа отгружают в интерфейсе Controlata. Подробнее о запланированном изменении остатка в статье Материалы. Статусы оплаты | Код | Статус | |---|---| | 0 | Не оплачен | | 1 | Частично оплачен | | 2 | Оплачен | Новый заказ создается неоплаченным. Статус оплаты меняет v1/orders/update_payment. Это только отметка: на остатки и суммы она не влияет. Номер заказа Controlata добавляет к номеру префикс из настройки Префикс для номеров заказов в подключении API (см. Обзор API). Если префикс «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. Если не найдена ни одна строка, заказ не создается. Подробнее о поиске позиций в статье Общие правила. Материалы в заказах принимаются, только если в разделе Настройки → Основные включена Возможность заказа материалов. Иначе запрос с материалами отклоняется. Склады Продукты списываются со склада products_storage_id, материалы со склада materials_storage_id. Если склад не передан, берется склад из настроек Склад по умолчанию для продуктов в заказах и Склад по умолчанию для материалов в заказах (на странице Склады, кнопка Склады по умолчанию). ID складов возвращает v1/storages/get_list. Вместо products_storage_id можно передать storage_id: так поле называлось, когда склад в заказе был один. В ответах storage_id и storage_name тоже приходят как синонимы склада продуктов. Производство под заказ Если передать production со значением 1, продукты заказа не списываются со склада, а производятся. Controlata создает производство с названием «Под заказ A-1001». Склады, статус и производство заготовок в нем берутся из настроек компании. Себестоимость продуктов заказа берется из этого производства. - У такого заказа нет склада продуктов: products_storage_id не используется. - Материалы заказа по-прежнему списываются со склада материалов. - Если в v1/orders/edit передать production со значением 0, связанное производство удаляется, а продукты списываются со склада. Настройка Способ выполнения нового заказа по умолчанию на API не влияет: без production заказ выполняется со склада. Покупатель Покупатель указывается одним из двух способов: - 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_name создает нового покупателя, даже если покупатель с таким именем уже есть. Для постоянных покупателей сохраните ID на своей стороне и передавайте customer_id. Подробнее о полях в статье Покупатели. Покупатель создается только после проверки строк: запрос с ошибкой в строках не оставляет лишних покупателей.

Создание заказа

Создает заказ. Статус заказа берется из настройки Статус нового заказа по умолчанию, а от статуса зависит, списываются ли продукты и материалы сразу (см. Заказы). 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. Поля покупателя, склады и производство под заказ описаны в статье Заказы. Как работает - Номер. К 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.

Редактирование заказа

Изменяет заказ. Меняются только переданные поля, остальные остаются прежними. Подробнее о частичном редактировании в статье Общие правила. v1/orders/edit.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | order_id | int | Да | ID заказа | | 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 | Нет | Стоимость доставки | | discount | float | Нет | Скидка | | notes | string | Нет | Заметки | Статус и статус оплаты этим методом не меняются, для них есть v1/orders/update_status и v1/orders/update_payment. Как работает - Строки. Если передан products или materials, состав заменяется целиком, а непереданный массив считается пустым. Если не передан ни один, строки остаются прежними. Строки из ответа v1/orders/get_entry можно отправить обратно без изменений. - Номер. Передавайте num без префикса: Controlata добавит текущий префикс подключения. Если num не передан, номер не меняется. - Покупатель. Без customer_id и customer_name покупатель остается прежним. customer_name с тем же именем, что у текущего покупателя, не создает дубль. Другое имя создает нового покупателя. Текущего покупателя можно передать по customer_id, даже если он уже удален. - Заметки. Если переданы строки, а notes нет, сообщения о ненайденных позициях дописываются к текущим заметкам. Одно и то же сообщение повторно не дописывается. - Склады. При смене склада списание переносится на новый склад, остатки пересчитываются на обоих складах. - Производство под заказ. production со значением 1 создает связанное производство, если его еще нет, а у заказа с производством состав производства обновляется вслед за строками. Значение 0 удаляет производство, и продукты списываются со склада продуктов. Без production способ выполнения не меняется. - Статус сохраняется. Если заказ уже упакован или отправлен, новые строки сразу списываются со склада. Если заказ отправлялся частями, изменение количества сначала затрагивает неотправленную часть. - Даты. Пустой date_placed заменяется сегодняшней датой. Движения по складу датируются датой отправки, а без нее датой заказа. Пример запроса Добавить скидку и изменить заметки, не трогая строки и покупателя: { "order_id": 43727, "discount": 1500, "notes": "Скидка по промокоду" } Заменить состав заказа: { "order_id": 43727, "products": [ { "sku": "P001", "amount": 3, "total": 39000 } ] } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No order_id in input | Не передан order_id | | Order not found or access denied | Заказ не найден или удален | | Products is not an array | products не массив (так же для materials) | | No products or materials in input | Переданы пустые products и materials | | Materials in orders are disabled in company settings | Переданы материалы, а настройка Возможность заказа материалов выключена | | All products have wrong SKU or id | Не найдена ни одна строка (с материалами «All products and materials have wrong SKU or id») | | Storage ID is not set | Передан пустой склад | | Storage ID not found | Склад не найден или удален | | Date is not a valid date in format YYYY-MM-DD | Неверная дата | | Customer not found | Покупатель customer_id не найден или удален | | Customer name must not be empty | Пустое customer_name | | Invalid customer_type value. Must be one of: 1, 2, 3 | Неверный тип нового покупателя | Ошибки в отдельных строках (нет amount или total, неверное количество) те же, что в v1/orders/add.

Удаление заказа

Удаляет заказ. v1/orders/delete.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | order_id | int | Да | ID заказа | Как работает - Списания продуктов и материалов по заказу отменяются, остатки на складах пересчитываются. - Связанное производство под заказ удаляется вместе с заказом. - Файлы заказа удаляются. - Покупатель остается в Controlata, даже если это был его единственный заказ. Удаление нельзя отменить. Чтобы сохранить заказ в истории, но убрать его влияние на остатки, переведите его в статус «Отменен» методом v1/orders/update_status. Пример запроса { "order_id": 43727 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No order_id in input | Не передан order_id | | Order not found or access denied | Заказ не найден или уже удален |

Смена статуса заказа

Меняет статус заказа. От статуса зависит, списаны ли продукты и материалы заказа со склада (см. Заказы). v1/orders/update_status.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | order_id | int | Да | ID заказа | | status | int | Да | Новый статус: 0 Новый, 1 Упакован, 3 Отправлен, 4 Отменен | | date_shipped | string | Нет | Дата отправки. Учитывается при переходе в статус «Отправлен» | Статус 2 «Частично отправлен» через API не ставится: он появляется, когда часть заказа отгружают в интерфейсе Controlata. Как работает - Остатки. В статусах «Упакован» и «Отправлен» продукты и материалы списываются со склада, в статусе «Новый» попадают в запланированное изменение остатка, в статусе «Отменен» на остатки не влияют. Остатки пересчитываются сразу. - Дата отправки. При переходе в «Отправлен» переданная date_shipped записывается в заказ, и списание датируется ею. Без date_shipped дата отправки не меняется. В других статусах date_shipped игнорируется. - Частичная отправка. Если заказ был в статусе «Частично отправлен», при переходе в «Отправлен» неотправленная часть оформляется еще одной отгрузкой. - Возврат из отправленных. При переходе из «Отправлен» или «Частично отправлен» в «Новый», «Упакован» или «Отменен» отгрузки заказа удаляются. - Тот же статус. Если заказ уже в переданном статусе, ничего не меняется, и метод отвечает успехом. Пример запроса { "order_id": 43727, "status": 3, "date_shipped": "2026-10-08" } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No order_id in input | Не передано обязательное поле (вместо order_id будет имя поля) | | Invalid status value. Must be one of: 0, 1, 3, 4 | Неверный статус, в том числе 2 | | Order not found or access denied | Заказ не найден или удален | | Date is not a valid date in format YYYY-MM-DD | Неверная date_shipped |

Смена статуса оплаты заказа

Меняет статус оплаты заказа. Статус оплаты только отмечает, получены ли деньги от покупателя: на остатки, суммы и статус заказа он не влияет. v1/orders/update_payment.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | order_id | int | Да | ID заказа | | status | int | Да | Статус оплаты: 0 Не оплачен, 1 Частично оплачен, 2 Оплачен | Статус оплаты виден в списке заказов, если в разделе Настройки → Основные включено Показывать статус оплаты заказов. Через API он меняется и возвращается независимо от этой настройки. Пример запроса { "order_id": 43727, "status": 2 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No order_id in input | Не передано обязательное поле (вместо order_id будет имя поля) | | Invalid payment status value. Must be one of: 0, 1, 2 | Неверный статус оплаты | | Order not found or access denied | Заказ не найден или удален |

Список заказов

Возвращает заказы компании, от новых к старым: по дате заказа, а внутри одной даты по номеру. Строки заказов в список не входят, их возвращает v1/orders/get_entry. v1/orders/get_list.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | date_from | string | Нет | Заказы с этой даты заказа включительно | | date_to | string | Нет | Заказы по эту дату заказа включительно | | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Фильтры работают по date_placed. Без параметров возвращаются все заказы компании. Подробнее о постраничной выдаче в статье Общие правила. Ответ Массив orders с полями заказа (см. Заказы) и полями: | Поле | Тип | Описание | |---|---|---| | shipments_count | int | Число отгрузок заказа | | products_storage_name | string | Название склада продуктов | | materials_storage_name | string | Название склада материалов | | storage_id, storage_name | | Синонимы склада продуктов, оставлены для совместимости | | customer_* | | Все поля покупателя: customer_id, customer_type, customer_name, customer_email, customer_phone, customer_address_real, customer_address_legal, customer_inn, customer_kpp, customer_ogrn, customer_agreement, customer_manager_name, customer_manager_post, customer_notes | Поле total в корне ответа содержит общее число заказов, подходящих под фильтры. У заказа под производство products_storage_id равен «0», а название склада null. Пример запроса { "date_from": "2026-10-01", "date_to": "2026-10-31", "limit": 100, "offset": 0 } Пример ответа { "success": true, "orders": [ { "id": "43727", "num": "A-1001", "status": "3", "payment": "2", "date_placed": "2026-10-06", "date_shipped": "2026-10-08", "total": "30000.00", "subtotal": "30500.00", "delivery_price": "500.00", "discount": "1000.00", "cost": "17800.00", "notes": "Заказ с сайта", "amount": "3.000", "lines": "2", "shipments_count": "1", "production": "0", "production_num": null, "source": "api", "products_storage_id": "3998", "products_storage_name": "Основной склад", "storage_id": "3998", "storage_name": "Основной склад", "materials_storage_id": "3998", "materials_storage_name": "Основной склад", "customer_id": "512", "customer_type": "3", "customer_name": "Иван Петров", "customer_email": "ivan@example.com", "customer_phone": "+7 900 123-45-67", "customer_address_real": "г. Москва, ул. Лесная, д. 5, кв. 12", "customer_address_legal": "", "customer_inn": "", "customer_kpp": "", "customer_ogrn": "", "customer_agreement": "", "customer_manager_name": "", "customer_manager_post": "", "customer_notes": "" } ], "total": 1 } Ошибки | Ошибка | Причина | |---|---| | Date is not a valid date in format YYYY-MM-DD | Неверная date_from или date_to | | Invalid limit value. Must be between 1 and 1000 | Неверный limit | | Invalid offset value. Must be 0 or greater | Неверный offset | | Offset requires limit | Передан offset без limit |

Данные заказа

Возвращает данные заказа, покупателя и строки заказа. v1/orders/get_entry.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | order_id | int | Да | ID заказа | Ответ Объект order с полями заказа (см. Заказы), названиями складов, всеми полями покупателя с префиксом customer_ и двумя массивами строк: products и materials. Число отгрузок (shipments_count) возвращает только v1/orders/get_list. Поля строки: | Поле | Тип | Описание | |---|---|---| | id | int | ID продукта или материала | | sku | string | Артикул | | name | string | Название | | amount | float | Количество | | unit | string | Единица измерения | | total | float | Сумма строки | | price | float | Цена за единицу: total, деленный на amount | | cost | float | Себестоимость строки | | position | int | Номер строки в карточке заказа, от 0 | Нумерация position сквозная для обоих массивов: по ней можно восстановить порядок строк, как в карточке заказа. Если строка отправлялась частями, ее количество и суммы приходят общими. Строки из ответа можно отправить в v1/orders/edit без изменений: лишние поля игнорируются. У заказа под производство склада продуктов нет, поэтому products_storage_id, products_storage_name, storage_id и storage_name приходят как null. Пример запроса { "order_id": 43727 } Пример ответа { "success": true, "order": { "id": "43727", "num": "A-1001", "status": "3", "payment": "2", "date_placed": "2026-10-06", "date_shipped": "2026-10-08", "subtotal": "30500.00", "delivery_price": "500.00", "discount": "1000.00", "total": "30000.00", "cost": "17800.00", "notes": "Заказ с сайта", "amount": "3.000", "lines": "2", "source": "api", "production": "0", "production_num": null, "customer_id": "512", "customer_type": "3", "customer_name": "Иван Петров", "customer_email": "ivan@example.com", "customer_phone": "+7 900 123-45-67", "customer_address_real": "г. Москва, ул. Лесная, д. 5, кв. 12", "customer_address_legal": "", "customer_inn": "", "customer_kpp": "", "customer_ogrn": "", "customer_agreement": "", "customer_manager_name": "", "customer_manager_post": "", "customer_notes": "", "products_storage_id": "3998", "products_storage_name": "Основной склад", "storage_id": "3998", "storage_name": "Основной склад", "materials_storage_id": "3998", "materials_storage_name": "Основной склад", "products": [ { "id": "815", "sku": "P001", "name": "Стол дубовый", "amount": "2.000", "unit": "шт", "total": "26000", "price": "13000", "cost": "15400", "position": "0" }, { "id": "816", "sku": "P002", "name": "Табурет дубовый", "amount": "1.000", "unit": "шт", "total": "4500", "price": "4500", "cost": "2400", "position": "1" } ], "materials": [] } } Ошибки | Ошибка | Причина | |---|---| | No order_id in input | Не передан order_id | | Order not found or access denied | Заказ не найден или удален |