Обзор API

API Controlata позволяет внешним системам (сайту, CRM, учетной системе) работать с данными в Controlata: создавать заказы и покупателей, вести каталог продуктов и обновлять их остатки.

Для подключения нужен опыт программирования и работы с API. Если вы не разработчик, передайте эту документацию техническому специалисту.

Подключение

1. Откройте Настройки → Интеграции и нажмите Подключить напротив Общее API.
2. Скопируйте Ключ API. Он нужен для авторизации всех запросов.
3. При необходимости измените Префикс для номеров заказов. По умолчанию это A-. Как работает префикс, описано в статье Заказы.

Адрес и формат запросов

Все методы находятся по базовому адресу:

https://api.controlata.ru/connect/v1/

Полный адрес метода складывается из базового адреса и пути метода. Например, создание заказа: https://api.controlata.ru/connect/v1/orders/add.php.

• Метод HTTP: POST
• Тело запроса: JSON в кодировке UTF-8, заголовок Content-Type: application/json
• Имена полей: в формате snake_case, как в примерах (customer_id, date_placed)
• Даты: в формате YYYY-MM-DD

Числа в ответах приходят строками ("id": "31591", "total": "480000.00"), приводите типы на своей стороне.

API рассчитано на запросы с вашего сервера. Запросы из браузера с другого домена отклоняются с кодом 401.

Авторизация

Передавайте ключ API в заголовке Authorization как есть, без слова Bearer:

Authorization: ваш_ключ_api

Пример запроса:

curl -X POST https://api.controlata.ru/connect/v1/customers/get_list.php \
  -H "Authorization: ваш_ключ_api" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответы и ошибки

Успешный ответ приходит с кодом 200 и полем "success": true, остальные поля зависят от метода:

{
    "success": true,
    "order_id": 456,
    "customer_id": 789
}

При ошибке success равно false, а в поле error приходит описание на английском:

{
    "success": false,
    "error": "Order not found or access denied"
}

Если не передано обязательное поле, ошибка выглядит как No <поле> in input, например No customer_id in input. Остальные тексты ошибок перечислены в статье о каждом разделе.

Лимит запросов

Компания может отправить до 10 000 запросов в сутки. Учитываются все запросы с верным ключом, в том числе завершившиеся ошибкой. Счетчик обнуляется раз в сутки, ночью. При превышении лимита API отвечает кодом 500 и ошибкой Daily connections limit reached.

Идентификаторы

ID покупателей, заказов и продуктов возвращают методы создания и получения списка. Сохраняйте их на своей стороне, чтобы потом обращаться к записям.

Метода для получения списка складов пока нет. ID склада можно взять из адреса его страницы в Controlata:

1. Откройте раздел Склады.
2. Откройте нужный склад.
3. Скопируйте число из адресной строки: https://app.controlata.ru/storages/item/<ID склада>.

Разделы API

• Покупатели: создание, редактирование, удаление и получение покупателей
• Заказы: создание и редактирование заказов, смена статуса и статуса оплаты
• Продукты: каталог продуктов и их остатки на складах
• Единицы измерения: коды единиц, которые принимает API

Controlata сохраняет журнал запросов к API. Если запрос работает не так, как ожидается, напишите в поддержку и укажите метод и время запроса.