Начало работы
От Максим
От Максим
Подключение, авторизация и общие правила работы с API
Обзор API
API Controlata позволяет внешним системам (сайту, CRM, учетной системе, маркетплейсу) работать с данными в Controlata: вести каталог материалов, продуктов и ресурсов, создавать заказы, поставки, производства, списания, перемещения и инвентаризации, получать остатки на складах. Для подключения нужен опыт программирования и работы с API. Если вы не разработчик, передайте эту документацию техническому специалисту. Подключение 1. Откройте Настройки → Интеграции и нажмите Подключить напротив Общее API. 2. Скопируйте Ключ API. Он нужен для авторизации всех запросов. 3. При необходимости измените Префикс для номеров заказов. По умолчанию это «A-». Адрес и формат запросов Базовый адрес 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. - Имена полей: в формате snake_case, как в примерах (material_id, date_placed). - Даты: в формате YYYY-MM-DD. API рассчитано на запросы с вашего сервера. Запросы из браузера с другого домена отклоняются с кодом 401. Версии методов Версия указана в пути каждого метода: v1/materials/add, v2/products/get_entry. Новая версия появляется только у метода, ответ которого изменился несовместимо, остальные методы остаются в v1. Старая версия метода продолжает работать. Авторизация Передавайте ключ 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 '{}' Ответы и ошибки Успешный ответ приходит с кодом 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 не передан или неверный | Пустое | | 429 | Исчерпан дневной лимит запросов | JSON, success: false | | 500 | Внутренняя ошибка | JSON, success: false | Если не передано обязательное поле, ошибка выглядит как «No <поле> in input», например «No material_id in input». Остальные ошибки перечислены в статье каждого метода. Лимит запросов Компания может отправить до 10 000 запросов в сутки. Учитываются все запросы с верным ключом, в том числе завершившиеся ошибкой. Счетчик обнуляется раз в сутки, ночью. При превышении лимита API отвечает кодом 429 и ошибкой «Daily connections limit reached». Что дальше - Общие правила: частичное редактирование, строки операций, постраничная выдача, точность чисел. - Справочники: склады, категории, единицы измерения. С них обычно начинают интеграцию. - Разделы с методами: материалы, продукты, ресурсы, покупатели, заказы, поставщики, поставки, производство, списания, перемещения, инвентаризации. Controlata сохраняет журнал запросов к API. Если запрос работает не так, как ожидается, напишите в поддержку и укажите метод и время запроса.
Общие правила
Правила, которые одинаково работают во всех методах API. Идентификаторы ID записей возвращают методы создания и получения списков. Сохраняйте их на своей стороне, чтобы обращаться к записям: материалы, продукты, заказы и другие операции изменяются и удаляются по ID. Числа в ответах Числа в ответах приходят строками («"id": "2051"», «"stock": "4.200"»), приводите типы на своей стороне. Поле, у которого нет значения, приходит как null. Точность чисел Количества хранятся с точностью до 3 знаков после запятой, суммы и цены до копеек. API округляет переданные значения так же, как поля в интерфейсе Controlata: количество 0.3333 сохранится как 0.333, сумма 10.125 как 10.13. Количество в строках операций должно быть больше нуля уже после округления: 0.0004 будет отклонено. Числа передаются числом или строкой с точкой: 12.5 или "12.5". Значения вроде "12,5" или пустая строка отклоняются с ошибкой «Invalid <поле> value. Must be a number». Редактирование Методы edit меняют только те поля, которые переданы в запросе. Обязателен только ID записи, остальные поля остаются прежними. - Чтобы очистить текстовое поле, передайте пустую строку. - Массивы (строки операции, категории, поставщики, состав продукта) при передаче заменяются целиком. Чтобы очистить массив, передайте пустой массив. - Если передан хотя бы один из массивов materials и products, строки операции заменяются целиком, а непереданный массив считается пустым. Если не передан ни один, строки не меняются. Например, чтобы изменить только заметки поставки, достаточно передать purchase_id и notes: строки, даты, склады и поставщик останутся прежними. Строки операций Заказы, поставки, производства, списания, перемещения и инвентаризации состоят из строк. Строки передаются в двух массивах: materials для материалов и products для продуктов. Тип позиции определяется массивом. Позиция в строке указывается одним из двух способов: - id: ID материала или продукта; - sku: артикул. Продукт ищется сначала по основному артикулу, затем по альтернативным. Если переданы оба поля, поиск идет по id. Если позиция не найдена, в заказах строка пропускается, а сообщение о ней дописывается в заметки заказа. В остальных операциях запрос отклоняется с ошибкой: они меняют остатки и себестоимость, и пропущенная строка исказила бы учет. Строки из ответов методов get_entry можно отправить обратно в edit без изменений. Постраничная выдача Методы get_list принимают необязательные параметры: | Поле | Тип | Описание | |---|---|---| | limit | int | Размер страницы, от 1 до 1000 | | offset | int | Сколько записей пропустить. Передается вместе с limit | Без limit возвращается весь список. В ответе всегда есть поле total с общим числом записей, подходящих под фильтры. Чтобы получить все записи постранично, увеличивайте offset на limit, пока offset меньше 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 | Удаленные записи Удаленные материалы, продукты, ресурсы, покупатели, поставщики и склады не возвращаются в списках и не принимаются в новых операциях. Операции, в которых они уже участвуют, остаются в истории.