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