Документация API Controlata
Ищите здесь статьи или выберите категории, указанные ниже.
Поиск по теме
Найти руководства, уроки и ответы, организованные по категориям.
Начало работы
Подключение, авторизация и общие правила работы с API
Обзор
Материалы
Методы для материалов и их остатков
Обзор
Продукты
Методы для продуктов, их состава и остатков
Обзор
Ресурсы
Методы для ресурсов: работа, оборудование, накладные расходы
Обзор
Покупатели
Создание, редактирование и получение покупателей
Обзор
Заказы
Методы для заказов, их статусов и оплаты
Обзор
Поставщики
Создание, редактирование и получение поставщиков
Обзор
Поставки
Методы для поставок, их статусов и оплаты
Обзор
Производство
Методы для производства и его статусов
Обзор
Списания
Методы для списаний материалов и продуктов
Обзор
Перемещения
Методы для перемещений между складами
Обзор
Инвентаризации
Методы для инвентаризаций складов
Обзор
Категории
Обзор
Склады
Обзор
Единицы измерения
Обзор
Популярные статьи
Что другие люди читают прямо сейчас.
Поставки
Поставки: закупки материалов и продуктов у поставщиков. Поставка пополняет остатки на складе и обновляет цены материалов. Через API поставки можно создавать, редактировать и удалять, менять статус и статус оплаты, получать список поставок и данные поставки. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/purchases/add | Создает поставку | | v1/purchases/edit | Изменяет поставку | | v1/purchases/delete | Удаляет поставку | | v1/purchases/update_status | Меняет статус поставки | | v1/purchases/update_payment | Меняет статус оплаты | | v1/purchases/get_list | Возвращает поставки компании | | v1/purchases/get_entry | Возвращает данные поставки со строками |
Начало работыОбзор API
API Controlata позволяет внешним системам (сайту, CRM, учетной системе, маркетплейсу) работать с данными в Controlata: вести каталог материалов, продуктов и ресурсов, создавать заказы, поставки, производства, списания, перемещения и инвентаризации, получать остатки на складах. Для подключения нужен опыт программирования и работы с API. Если вы не разработчик, передайте эту документацию техническому специалисту или AI-ассистенту: каждую статью можно скопировать в формате Markdown. Подключение 1. Откройте Настройки → Интеграции и нажмите Подключить напротив Общее API. 2. Нажмите Добавить ключ, укажите название ключа и права доступа. 3. Скопируйте ключ. Он нужен для авторизации всех запросов. Важно: полностью ключ показывается только один раз, сразу после добавления. Controlata хранит не сам ключ, а его хэш, поэтому посмотреть ключ позже нельзя. Если ключ потерян, добавьте новый и отзовите старый. Управлять ключами может только администратор компании. Адрес и формат запросов Базовый адрес API: https://api.controlata.ru/connect/ В документации методы указаны относительно этого адреса. Например, метод v1/materials/add вызывается по адресу https://api.controlata.ru/connect/v1/materials/add.php. Первый сегмент пути это версия метода: новая версия появляется, только если ответ изменился несовместимо, а старая продолжает работать. - Все методы вызываются запросом POST. - Тело запроса: JSON в кодировке UTF-8, заголовок Content-Type: application/json. API рассчитано на запросы с вашего сервера. Запросы из браузера с другого домена отклоняются с кодом 401. Авторизация Передавайте ключ API в заголовке Authorization как есть, без слова Bearer: Authorization: ваш_ключ_api Пример запроса: curl -X POST https://api.controlata.ru/connect/v1/storages/get_list.php \ -H "Authorization: ваш_ключ_api" \ -H "Content-Type: application/json" \ -d '{}' Ключи и права доступа Для каждой системы, которая работает с API, добавьте отдельный ключ. Тогда ключ одной системы можно отозвать, не затрагивая остальные. У каждого ключа свои права доступа: - Только чтение: ключ может вызывать только методы получения данных, их названия начинаются с get_ (например, v1/materials/get_list). - Полный доступ: ключ может вызывать все методы. Название и права ключа можно изменить в любой момент. Ответы и ошибки Успешный ответ приходит с кодом 200 и полем success, равным true. Остальные поля зависят от метода: { "success": true, "material_id": 2051 } При ошибке success равно false, а в поле error приходит описание на английском: { "success": false, "error": "Material not found or access denied" } | Код HTTP | Когда | Тело ответа | |---|---|---| | 200 | Запрос выполнен | JSON, success: true | | 400 | Ошибка в данных запроса: нет обязательного поля, неверное значение, запись не найдена | JSON, success: false | | 401 | Ключ API не передан, неверный или отозван | Пустое | | 402 | Подписка компании не активна: отменена или закончился пробный период. Ошибка «Subscription is not active» | JSON, success: false | | 403 | Ключ с правами Только чтение вызывает метод, который изменяет данные. Ошибка «This API key is read-only» | JSON, success: false | | 429 | Исчерпан дневной лимит запросов | JSON, success: false | | 500 | Внутренняя ошибка | JSON, success: false | Если не передано обязательное поле, ошибка выглядит как «No <поле> in input», например «No material_id in input». Остальные ошибки перечислены в статье каждого метода. Лимит запросов Компания может отправить до 10 000 запросов в сутки. Лимит общий для всех ключей компании. Учитываются все принятые запросы, в том числе завершившиеся ошибкой в данных (код 400). Запросы, отклоненные с кодами 401, 402 и 403, в лимит не входят. Счетчик обнуляется раз в сутки, ночью. При превышении лимита API отвечает кодом 429 и ошибкой «Daily connections limit reached». Что дальше - Общие правила: частичное редактирование, постраничная выдача, точность чисел. - Справочники, с которых обычно начинают интеграцию: Категории, Склады, Единицы измерения. - Разделы с методами: Материалы, Продукты, Ресурсы, Покупатели, Заказы, Поставщики, Поставки, Производство, Списания, Перемещения, Инвентаризации. Controlata сохраняет журнал запросов к API. Если запрос работает не так, как ожидается, напишите в поддержку и укажите метод и время запроса.
ЗаказыРедактирование заказа
Изменяет заказ. Меняются только переданные поля, остальные остаются прежними. 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/audits/delete.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | audit_id | int | Да | ID инвентаризации | Удаление нельзя отменить. Корректировки инвентаризации отменяются: излишки убираются со склада, недостачи возвращаются на него. Пример запроса { "audit_id": 1699 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No audit_id in input | Не передан audit_id | | Audit not found or access denied | Инвентаризация не найдена или уже удалена |
ПеремещенияПеремещения
Перемещения: перенос материалов или продуктов с одного склада на другой. Через API перемещения можно создавать, редактировать и удалять, менять их статус, получать список и данные перемещения. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/transfers/add | Создает перемещение | | v1/transfers/edit | Изменяет перемещение | | v1/transfers/delete | Удаляет перемещение | | v1/transfers/update_status | Меняет статус перемещения | | v1/transfers/get_list | Возвращает список перемещений | | v1/transfers/get_entry | Возвращает перемещение со строками |
МатериалыМатериалы
Материалы: сырье и комплектующие, из которых производятся продукты. Через API их можно создавать, редактировать и удалять, получать список и данные материала, обновлять остатки на складах. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/materials/add | Создает материал | | v1/materials/edit | Изменяет материал | | v1/materials/delete | Удаляет материал | | v1/materials/update_stock | Устанавливает остаток на складе | | v1/materials/get_list | Возвращает материалы склада | | v1/materials/get_entry | Возвращает данные материала | | v1/materials/get_stocks | Возвращает остатки материалов по всем складам |