Заказы

Методы для работы с заказами: создание, редактирование, смена статуса и статуса оплаты, удаление и получение заказов.

Все адреса указаны относительно базового https://api.controlata.ru/connect/v1/. Формат запросов и авторизация описаны в статье Обзор API.

Номер заказа и префикс

К номеру заказа Controlata добавляет Префикс для номеров заказов из настроек интеграции. Например, при префиксе A- и "num": "1001" заказ получит номер A-1001, и в ответах методов get_list и get_entry поле num придет уже с префиксом.

Важно: в orders/edit.php передавайте номер без префикса. Если отправить "num": "A-1001", номер станет A-A-1001.

Уникальность номера не проверяется.

Состав заказа

Продукты передаются в массиве products, материалы в массиве materials. У каждой строки три поля:

Продукт ищется сначала по основному артикулу, затем по альтернативным. Если артикул не найден, строка пропускается, а в заметки заказа добавляется сообщение вида Product with SKU "A001", amount 2, total 1800 not found in Controlata, check sku.. Заказ создается из найденных строк. Если не найдена ни одна строка, вернется ошибка.

Материалы можно передавать, только если в Настройки → Основные включена Возможность заказа материалов. У материалов нет альтернативных артикулов.

Сумма заказа: сумма строк + delivery_price − discount.

Статусы

Статус 2 приходит в ответах, но установить его через API нельзя.

Статус влияет на остатки. В статусах Упакован и Отправлен продукты и материалы заказа списаны со склада. В статусе Новый списание только запланировано. В статусе Частично отправлен списаны отгруженные строки, остальные запланированы. В статусе Отменен заказ на остатки не влияет.

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

POST orders/add.php

* Нужен хотя бы один из массивов: products или materials. ** Нужно одно из полей: customer_id или customer_name.

Новый покупатель создается из полей customer_name и необязательных customer_type, 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. Значения такие же, как у полей в статье Покупатели.

Заказ создается в статусе из настройки Статус нового заказа по умолчанию (Настройки → Основные) и со статусом оплаты Не оплачен.

При "production": 1 Controlata создает производство «Под заказ <номер>» на складах по умолчанию для производства. Продукты для такого заказа выпускает производство, поэтому products_storage_id не учитывается. Материалы заказа списываются со склада как обычно.

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

{
    "num": "1001",
    "customer_name": "Петров Иван",
    "customer_email": "petrov@example.com",
    "delivery_price": 500,
    "discount": 100,
    "products": [
        {
            "sku": "A001",
            "amount": 2,
            "total": 1800
        },
        {
            "sku": "A002",
            "amount": 1,
            "total": 1000
        }
    ]
}

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

{
    "success": true,
    "order_id": 456,
    "customer_id": 789
}

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

POST orders/edit.php

Обязательные поля: order_id, num, состав (products или materials) и покупатель (customer_id или customer_name). Остальные поля такие же, как при создании.

Важно: метод перезаписывает заказ целиком. Если поле не передано:

• date_placed станет сегодняшней датой
• date_shipped, notes станут пустыми
• delivery_price, discount станут равны 0
• production станет равен 0, и связанное производство будет удалено
• склады останутся прежними

Передавайте customer_id, а не customer_name: с customer_name при каждом редактировании создается новый покупатель.

Статус и статус оплаты при редактировании не меняются.

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

{
    "success": true
}

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

POST orders/update_status.php

Как статус влияет на остатки, описано выше в разделе Статусы. Если перевести заказ из статуса Отправлен или Частично отправлен в Новый, Упакован или Отменен, отгрузки по заказу удаляются. Повторная установка того же статуса ничего не меняет.

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

{
    "success": true
}

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

POST orders/update_payment.php

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

{
    "success": true
}

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

POST orders/delete.php

Обязательное поле: order_id.

Заказ удаляется полностью. Отгруженные продукты и материалы возвращаются на склад, связанное производство удаляется.

Получение списка заказов

POST orders/get_list.php

Заказы приходят от новых к старым, без постраничной разбивки. Используйте date_from и date_to, чтобы ограничить выборку. Состав заказа в списке не передается, его возвращает orders/get_entry.php.

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

{
    "success": true,
    "orders": [
        {
            "id": "31591",
            "num": "A-103",
            "status": "0",
            "payment": "0",
            "date_placed": "2025-08-09",
            "date_shipped": "2025-08-11",
            "total": "480000.00",
            "subtotal": "480000.00",
            "delivery_price": "0.00",
            "discount": "0.00",
            "cost": "229400.00",
            "notes": "",
            "amount": "6.000",
            "lines": "3",
            "shipments_count": "0",
            "production": "0",
            "production_num": null,
            "source": "api",
            "products_storage_id": "3998",
            "products_storage_name": "Главный",
            "materials_storage_id": null,
            "materials_storage_name": null,
            "customer_id": "4877",
            "customer_name": "Михаил Петров",
            ...
        }
    ]
}

Поля покупателя в списке такие же, как в orders/get_entry.php.

Получение данных заказа

POST orders/get_entry.php

Обязательное поле: order_id.

Строки заказа приходят в двух массивах, products и materials. Поле position сквозное для обоих массивов и задает порядок строк в заказе. Поле amount у заказа равно null, если у строк разные единицы измерения.

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

{
    "success": true,
    "order": {
        "id": "31591",
        "num": "A-103",
        "status": "0",
        "payment": "0",
        "date_placed": "2025-08-09",
        "date_shipped": "2025-08-11",
        "subtotal": "480000.00",
        "delivery_price": "0.00",
        "discount": "0.00",
        "total": "480000.00",
        "cost": "229400.00",
        "notes": "",
        "amount": "6.000",
        "lines": "3",
        "source": "api",
        "production": "0",
        "production_num": null,
        "customer_id": "4877",
        "customer_type": "3",
        "customer_name": "Михаил Петров",
        "customer_email": "petrov@example.com",
        "customer_phone": "",
        "customer_address_real": "",
        "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": null,
        "materials_storage_name": null,
        "products": [
            {
                "id": "48390",
                "sku": "F003",
                "name": "Стул обеденный дубовый",
                "amount": "4",
                "unit": "шт",
                "total": "180000",
                "price": "45000",
                "cost": "99520",
                "position": "0"
            }
        ],
        "materials": []
    }
}

Поля storage_id и storage_name тоже приходят в ответе и повторяют products_storage_id и products_storage_name. Они оставлены для совместимости, в новом коде используйте products_storage_id.

Ошибки