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

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

## Подключение

1. Откройте **Настройки → [Интеграции](https://app.controlata.ru/settings/integrations)** и нажмите **Подключить** напротив **Общее 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».

## Что дальше

* [Общие правила](https://developers.controlata.ru/hc/api-docs/articles/rules): частичное редактирование, строки операций, постраничная выдача, точность чисел.
* [Справочники](https://developers.controlata.ru/hc/api-docs/articles/reference): склады, категории, единицы измерения. С них обычно начинают интеграцию.
* Разделы с методами: материалы, продукты, ресурсы, покупатели, заказы, поставщики, поставки, производство, списания, перемещения, инвентаризации.

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