Заказы

8 статьи Максим От Максим

Методы для заказов, их статусов и оплаты

Заказы

Заказы: продажи продуктов, а при включенной настройке и материалов, вашим покупателям. Через 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 | Возвращает данные заказа со строками |

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

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

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

Изменяет заказ. Меняются только переданные поля, остальные остаются прежними. 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 | Нет | Склад продуктов | | 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. Если передан хотя бы один из массивов, состав заменяется целиком, а непереданный считается пустым. Если не передан ни один, строки не меняются. | Поле | Тип | Обязательное | Описание | |---|---|---|---| | id | int | id или sku | ID продукта или материала | | sku | string | id или sku | Артикул. Продукт ищется и по альтернативным SKU | | amount | float | Да | Количество | | total | float | Да | Сумма строки (не цена за единицу) | | notes | string | Нет | Комментарий к строке | Строки из ответа v1/orders/get_entry можно отправить обратно без изменений. Пример запроса Добавить скидку и изменить заметки, не трогая строки и покупателя: { "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 | Неверная дата | | Invalid delivery_price value. Must be a number, 0 or greater | Стоимость доставки не число или меньше 0 | | Invalid discount value. Must be a number, 0 or greater | Скидка не число или меньше 0 | | 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 заказа | Удаление нельзя отменить. Чтобы сохранить заказ в истории, но убрать его влияние на остатки, переведите его в статус «Отменен» методом 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 игнорируется. Пример запроса { "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. Каждый объект содержит поля заказа: | Поле | Тип | Описание | |---|---|---| | 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», «wildberries», «ozon» | | notes | string | Заметки | | products_storage_id | int | Склад продуктов | | products_storage_name | string | Название склада продуктов | | materials_storage_id | int | Склад материалов | | materials_storage_name | string | Название склада материалов | | customer_id | int | ID покупателя | | customer_type | int | Тип покупателя: 1 юрлицо, 2 ИП, 3 физлицо | | customer_name | string | Наименование юрлица или имя ИП и физлица | | 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 | Заметки о покупателе | Поле total в корне ответа содержит общее число заказов, подходящих под фильтры. Пример запроса { "date_from": "2026-10-01", "date_to": "2026-10-31", "limit": 100, "offset": 0 } Пример ответа { "success": true, "orders": [ { "id": 43727, "num": "1001", "status": 3, "payment": 2, "date_placed": "2026-10-06", "date_shipped": "2026-10-08", "total": 30000, "subtotal": 30500, "delivery_price": 500, "discount": 1000, "cost": 17800, "notes": "Заказ с сайта", "amount": 3, "lines": 2, "production": 0, "production_num": null, "source": "api", "products_storage_id": 3998, "products_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 с полями заказа: | Поле | Тип | Описание | |---|---|---| | 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», «wildberries», «ozon» | | notes | string | Заметки | | products_storage_id | int | Склад продуктов | | products_storage_name | string | Название склада продуктов | | materials_storage_id | int | Склад материалов | | materials_storage_name | string | Название склада материалов | | customer_id | int | ID покупателя | | customer_type | int | Тип покупателя: 1 юрлицо, 2 ИП, 3 физлицо | | customer_name | string | Наименование юрлица или имя ИП и физлица | | 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 | Заметки о покупателе | А также два массива строк заказа: products и materials. Поля строки: | Поле | Тип | Описание | |---|---|---| | id | int | ID продукта или материала | | sku | string | Артикул | | name | string | Название | | amount | float | Количество | | unit | string | Единица измерения | | total | float | Сумма строки | | price | float | Цена за единицу: total, деленный на amount | | cost | float | Себестоимость строки | | position | int | Номер строки в карточке заказа, от 0 | | notes | string | Комментарий к строке. Пустая строка, если его нет | Нумерация position сквозная для обоих массивов: по ней можно восстановить порядок строк, как в карточке заказа. Строки из ответа можно отправить в v1/orders/edit без изменений: лишние поля игнорируются. Пример запроса { "order_id": 43727 } Пример ответа { "success": true, "order": { "id": 43727, "num": "1001", "status": 3, "payment": 2, "date_placed": "2026-10-06", "date_shipped": "2026-10-08", "subtotal": 30500, "delivery_price": 500, "discount": 1000, "total": 30000, "cost": 17800, "notes": "Заказ с сайта", "amount": 3, "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": "Основной склад", "materials_storage_id": 3998, "materials_storage_name": "Основной склад", "products": [ { "id": 815, "sku": "P001", "name": "Стол дубовый", "amount": 2, "unit": "шт", "total": 26000, "price": 13000, "cost": 15400, "position": 0, "notes": "Гравировка: Анна" }, { "id": 816, "sku": "P002", "name": "Табурет дубовый", "amount": 1, "unit": "шт", "total": 4500, "price": 4500, "cost": 2400, "position": 1, "notes": "" } ], "materials": [] } } Ошибки | Ошибка | Причина | |---|---| | No order_id in input | Не передан order_id | | Order not found or access denied | Заказ не найден или удален |