Начало работы
От Максим
От Максим
Подключение, авторизация и общие правила работы с API
Обзор 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. Если запрос работает не так, как ожидается, напишите в поддержку и укажите метод и время запроса.
Общие правила
Правила, которые одинаково работают во всех методах API. Точность чисел Количества хранятся с точностью до 3 знаков после запятой, суммы и цены до копеек. API округляет переданные значения так же, как интерфейс Controlata: 0.3333 сохранится как 0.333, 10.125 как 10.13. Количество в строках операций должно оставаться больше нуля после округления: 0.0004 будет отклонено. Редактирование Методы edit меняют только переданные поля. Обязателен только ID записи, остальные поля остаются прежними. - Массивы (строки операции, категории, поставщики, состав продукта) при передаче заменяются целиком. Чтобы очистить массив, передайте пустой массив. - Если передан хотя бы один из массивов materials и products, строки операции заменяются целиком, а непереданный массив считается пустым. Если не передан ни один, строки не меняются. Например, чтобы изменить только заметки поставки, достаточно передать purchase_id и notes: строки, даты, склады и поставщик останутся прежними. Постраничная выдача Методы get_list принимают необязательные параметры постраничной выдачи. Исключение: небольшие справочники (единицы измерения, категории и склады) всегда возвращаются целиком и этих параметров не принимают. | Поле | Тип | Описание | |---|---|---| | limit | int | Размер страницы, от 1 до 1000 | | offset | int | Сколько записей пропустить. Передается вместе с limit | Без limit возвращается весь список. В ответе есть поле total с общим числом записей, подходящих под фильтры. | Ошибка | Причина | |---|---| | Invalid limit value. Must be between 1 and 1000 | Неверный limit | | Invalid offset value. Must be 0 or greater | Неверный offset | | Offset requires limit | Передан offset без limit |