API интеграция в Controlata: руководство для разработчиков

Интеграция по API позволяет полноценно работать с данными Controlata: управлять заказами, покупателями и продуктами из внешних систем.

Настройка интеграции по API требует технических знаний в области программирования и опыта работы с API-интерфейсами. Если вы не являетесь разработчиком, вам потребуется помощь технического специалиста для реализации интеграции.

Настройка интеграции

Перейдите в настройки Controlata, найдите блок "Интеграции" и нажмите "Подключить" напротив "Общее API"
Получите ключ API для авторизации запросов
Настройте префикс для номеров заказов (будет добавлен в начало всех заказов через API)

Авторизация

Все запросы должны содержать ключ API в заголовке Authorization:

Authorization: ваш_ключ_api

Базовые URL

Все эндпоинты располагаются по адресу:

Покупатели: https://api.controlata.ru/connect/v1/customers/
Заказы: https://api.controlata.ru/connect/v1/orders/
Продукты: https://api.controlata.ru/connect/v1/products/

Формат запросов и ответов

Метод: POST
Формат данных: JSON
Кодировка: UTF-8

Все ответы содержат поле success (true/false) и в случае ошибки - поле error с описанием.

Работа с покупателями

Создание покупателя

URL: customers/add.php

Обязательные параметры:

name (string) - название покупателя

Опциональные параметры:

type (int) - тип покупателя (1 = юридическое лицо, 2 = индивидуальный предприниматель, 3 - физическое лицо, по умолчанию 3)
email (string) - электронная почта
phone (string) - телефон
address_legal (string) - юридический адрес
address_real (string) - фактический адрес
inn (string) - ИНН
kpp (string) - КПП
ogrn (string) - ОГРН
agreement (string) - номер договора
manager_name (string) - имя менеджера
manager_post (string) - должность менеджера
notes (string) - заметки

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

{
    "name": "ООО Ромашка",
    "email": "[email protected]",
    "phone": "+7 (495) 123-45-67",
    "inn": "1234567890"
}

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

{
    "success": true,
    "customer_id": 123
}

Редактирование покупателя

URL: customers/edit.php

Обязательные параметры:

customer_id (int) - ID покупателя
name (string) - название покупателя

Опциональные параметры аналогичны созданию покупателя.

Важно: Если опциональный параметр не передан в запросе, существующее значение будет заменено на пустое.

Удаление покупателя

URL: customers/delete.php

Обязательные параметры:

customer_id (int) - ID покупателя

Получение списка покупателей

URL: customers/get_list.php

Параметры не требуются.

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

{
    "success": true,
    "customers": [
        {
            "id": 123,
            "name": "ООО Ромашка",
            "email": "[email protected]",
            "phone": "+7 (495) 123-45-67",
            "inn": "1234567890",
            "notes": ""
        }
    ]
}

Получение данных покупателя

URL: customers/get_entry.php

Обязательные параметры:

customer_id (int) - ID покупателя

Работа с заказами

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

URL: orders/add.php

Обязательные параметры:

num (string) - номер заказа
products (array) - массив продуктов:
- sku (string) - артикул продукта
- amount (float) - количество
- total (float) - сумма (цена × количество)
Покупатель (один из вариантов):
- customer_id (int) - ID существующего покупателя
- customer_name (string) - имя нового покупателя

Опциональные параметры:

customer_email, customer_phone, customer_address_real и другие поля покупателя
storage_id (int) - ID склада (если не указан, используется склад по умолчанию для заказов)
date_placed (string) - дата заказа в формате YYYY-MM-DD (если не указана, будет использована текущая дата)
date_shipped (string) - дата отправки в формате YYYY-MM-DD
delivery_price (float) - стоимость доставки
discount (float) - скидка
production (int) - 1 для создания производства, 0 для списания со склада
notes (string) - заметки

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

{
    "num": "1001",
    "customer_name": "Петров Иван",
    "customer_email": "[email protected]",
    "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
}

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

URL: orders/edit.php

Обязательные параметры:

order_id (int) - ID заказа
num (string) - номер заказа
products (array) - массив продуктов

Опциональные параметры аналогичны созданию заказа.

Важно: Если опциональный параметр не передан в запросе, существующее значение будет заменено на пустое.

Обновление статуса заказа

URL: orders/update_status.php

Обязательные параметры:

order_id (int) - ID заказа
status (int) - новый статус (0 = новый, 1 = упакован, 3 = отправлен, 4 = отменен)

Опциональные параметры:

date_shipped (string) - дата отгрузки в формате YYYY-MM-DD, ее можно указать при переходе заказа в статус отправлен

Обновление статуса оплаты

URL: orders/update_payment.php

Обязательные параметры:

order_id (int) - ID заказа
status (int) - статус оплаты (0 = не оплачен, 1 = частично оплачен, 2 = оплачен)

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

URL: orders/delete.php

Обязательные параметры:

order_id (int) - ID заказа

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

URL: orders/get_list.php

Опциональные параметры:

date_from (string) - дата от в формате YYYY-MM-DD
date_to (string) - дата до в формате YYYY-MM-DD

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

URL: orders/get_entry.php

Обязательные параметры:

order_id (int) - ID заказа

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

{
    "success": true,
    "order": {
        "id": "31591",
        "num": "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": "[email protected]",
        "customer_phone": "",
        "customer_address_real": "",
        "customer_address_legal": "",
        "customer_inn": "",
        "customer_kpp": "",
        "customer_ogrn": "",
        "customer_agreement": "",
        "customer_manager_name": "",
        "customer_manager_post": "",
        "customer_notes": "",
        "storage_id": "3998",
        "storage_name": "Главный",
        "products": [
            {
                "id": "48390",
                "sku": "F003",
                "name": "Стул обеденный дубовый",
                "amount": "4",
                "unit": "шт",
                "total": "180000",
                "price": "45000",
                "cost": "99520",
                "position": "0"
            },
        ]
    }
}

Работа с продуктами

Создание продукта

URL: products/add.php

Обязательные параметры:

name (string) - название продукта
unit (string) - единица измерения (см. список выше)
storage_id (int) - ID склада

Опциональные параметры:

sku (string) - артикул
price (float) - цена продажи
batch_size (float) - размер партии (по умолчанию: 1)
stock (float) - начальные остатки
minimum (float) - минимальный остаток
notes (string) - заметки

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

{
    "name": "Товар 1",
    "sku": "TOV001",
    "unit": "шт",
    "price": 900,
    "storage_id": 1,
    "stock": 10,
    "minimum": 5
}

Редактирование продукта

URL: products/edit.php

Обязательные параметры:

product_id (int) - ID продукта
name (string) - название продукта
unit (string) - единица измерения (см. список единиц выше)
storage_id (int) - ID склада

Опциональные параметры:

Остальные параметры аналогичны созданию продукта.

Важно: Если опциональный параметр не передан в запросе, существующее значение будет заменено на пустое.

Обновление остатков

URL: products/update_stock.php

Обязательные параметры:

product_id (int) - ID продукта
storage_id (int) - ID склада
stock (float) - новое количество остатков

Опциональные параметры:

notes (string) - заметки к корректировке

Удаление продукта

URL: products/delete.php

Обязательные параметры:

product_id (int) - ID продукта

Получение списка продуктов

URL: products/get_list.php

Обязательные параметры:

storage_id (int) - ID склада

Получение данных продукта

URL: products/get_entry.php

Обязательные параметры:

product_id (int) - ID продукта
storage_id (int) - ID склада

Доступные единицы измерения

При работе с продуктами вы можете использовать следующие единицы измерения:

Количество и вес:

шт - штуки
кг - килограммы
г - граммы
мг - миллиграммы
ц - центнеры
т - тонны
кар - караты
упак - упаковки
компл - комплекты

Объем:

л - литры
мл - миллилитры
дал - декалитры
гл - гектолитры
дцл - децилитры

Длина и площадь:

м - метры
см - сантиметры
мм - миллиметры
км - километры
дм - дециметры
пог. м - погонные метры
кв. м - квадратные метры
кв. см - квадратные сантиметры
кв. дм - квадратные дециметры
куб. м - кубические метры
куб. см - кубические сантиметры
куб. дм - кубические дециметры

Где найти storage_id

При создании продуктов или заказов вам может потребоваться идентификатор склада storage_id. На данный момент у нас нет эндпоинтов для получения списка складов, но вы можете посмотреть storage_id существующих складов в системе. Для этого нужно:

Зайти в раздел складов
Открыть нужный склад
Взять storage_id из адресной строки браузера: https://app.controlata.ru/storages/item/[storage_id]

Обработка ошибок

В случае ошибки API возвращает JSON с полями:

success: false
error: описание ошибки

Примеры ошибок:

{
    "success": false,
    "error": "Product not found or access denied"
}

Типичные ошибки:

401 Unauthorized - неверный API ключ
Customer not found - покупатель не найден
All products have wrong SKU - все продукты имеют неверный артикул
Invalid status value - неверное значение статуса

Особенности работы

Сопоставление продуктов происходит по артикулу (SKU). Сначала поиск выполняется по основному SKU продукта, если не найден - по альтернативным SKU. Если продукт не найден, он пропускается, но заказ создается с остальными продуктами.
Логирование: Все запросы логируются для отладки и мониторинга.
Префиксы заказов: К номеру заказа автоматически добавляется префикс из настроек интеграции.