Интеграция по API
Интеграция по API позволяет полноценно работать с данными Controlata: управлять заказами, покупателями и продуктами из
внешних систем.
Настройка интеграции по API требует технических знаний в области программирования и опыта работы с API-интерфейсами.
Если вы не являетесь разработчиком, вам потребуется помощь технического специалиста для реализации интеграции.
Настройка интеграции
1. Перейдите в настройки Controlata, найдите блок "Интеграции" и нажмите "Подключить" напротив "Общее API"
2. Получите ключ API для авторизации запросов
3. Настройте префикс для номеров заказов (будет добавлен в начало всех заказов через 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 существующих складов в системе. Для этого
нужно:
1. Зайти в раздел складов
2. Открыть нужный склад
3. Взять 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 - неверное значение статуса
Особенности работы
1. Сопоставление продуктов происходит по артикулу (SKU). Сначала поиск выполняется по основному SKU продукта, если не
найден - по альтернативным SKU. Если продукт не найден, он пропускается, но заказ создается с остальными
продуктами.
2. Логирование: Все запросы логируются для отладки и мониторинга.
3. Префиксы заказов: К номеру заказа автоматически добавляется префикс из настроек интеграции.
