Документация 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 | Возвращает остатки материалов по всем складам |