Подключение к Open API

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

Платформа SKIF.PRO предоставляет разработчикам и интеграторам доступ к открытому программному интерфейсу (Open API) для интеграции телематических данных с внешними ERP, CRM, TMS и 1С. Для взаимодействия с API требуется активная учетная запись в SKIF.PRO с правами интегратора или администратора компании.

## Свойства подключения

Для отправки запросов и изучения структуры данных используются следующие параметры и адреса интерфейса:

| Параметр | Описание |
| --- | --- |
| Портал документации | Интерактивная веб-документация Swagger UI: `https://api.skif.pro` |
| Базовый URL API | Точка входа для запросов данных: `https://app1.skif.pro/api_v1` |
| Спецификация OpenAPI | Машиночитаемая схема OpenAPI 3.0: `https://api.skif.pro/openapi.json` |
| Формат данных | Тело запросов и ответов передается в формате JSON (`Content-Type: application/json`) |
| Способы авторизации | Заголовок `Authorization: Bearer <токен>` или постоянный ключ `user_company_api_key: <ключ>` |

## Авторизация в Open API

Взаимодействие с Open API требует подтверждения прав доступа. SKIF.PRO поддерживает два способа авторизации: по временному JWT-токену или по постоянному API-ключу компании.

### Авторизация по временному токену

1. Отправьте HTTP-запрос методом POST на адрес `https://app1.skif.pro/api_v1/login` с логином и паролем учетной записи в формате JSON.
2. Извлеките значение токена из заголовка `Authorization` ответа сервера.
3. Передавайте полученный токен в заголовке `Authorization: Bearer <токен>` во всех последующих запросах к SKIF.PRO.

> Временный JWT-токен имеет ограниченный срок действия. Для серверных интеграций и скриптов фоновой синхронизации рекомендуется использовать постоянный API-ключ компании.

### Авторизация по постоянному API-ключу компании

1. Откройте **Админ-панель** SKIF.PRO и перейдите в карточку компании.
2. Выпустите постоянный ключ доступа в настройках параметров API.
3. Передавайте выпущенный ключ в HTTP-заголовке `user_company_api_key` в каждом запросе без выполнения предварительного логина.

## Работа с Open API

После авторизации отправьте запрос к эндпоинтам SKIF.PRO для получения первого списка объектов мониторинга:

1. Сформируйте POST-запрос к эндпоинту `https://app1.skif.pro/api_v1/units/list`.
2. Укажите в теле запроса JSON параметры пагинации `{"from": 0, "count": 10}`.
3. Добавьте авторизационный заголовок с Bearer-токеном или API-ключом компании.
4. Отправьте подготовленный запрос через curl или HTTP-клиент вашей среды разработки.

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

```bash
curl -X POST "https://app1.skif.pro/api_v1/units/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <токен>" \
  -d '{"from": 0, "count": 10}'
```

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

```python
import requests

url = "https://app1.skif.pro/api_v1/units/list"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <токен>",
}
payload = {"from": 0, "count": 10}

response = requests.post(url, json=payload, headers=headers, timeout=10)
data = response.json()
print(data)
```

## Ограничения запросов

Для обеспечения отказоустойчивости инфраструктуры и равного доступа к ресурсам действуют следующие лимиты:

- Частота вызовов ограничена лимитом 40 запросов в минуту на один токен или компанию. При превышении лимита сервер возвращает HTTP-код `429 Too Many Requests`.
- Таймаут обработки запросов на генерацию сложных отчетов и больших массивов телеметрии составляет 30 секунд.
- Максимальное количество объектов в ответе метода получения списка составляет 100 записей за один вызов.

## Смотрите также

- [Вход в систему мониторинга](/%D0%B1%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9%20%D1%81%D1%82%D0%B0%D1%80%D1%82/%D0%B2%D1%85%D0%BE%D0%B4%20%D0%B2%20%D1%81%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D1%83%20%D0%BC%D0%BE%D0%BD%D0%B8%D1%82%D0%BE%D1%80%D0%B8%D0%BD%D0%B3%D0%B0)
- [Подключение оборудования](/%D0%B1%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9%20%D1%81%D1%82%D0%B0%D1%80%D1%82/%D0%BF%D0%BE%D0%B4%D0%BA%D0%BB%D1%8E%D1%87%D0%B5%D0%BD%D0%B8%D0%B5%20%D0%BE%D0%B1%D0%BE%D1%80%D1%83%D0%B4%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F)
- [Создание объектов](/%D0%B1%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9%20%D1%81%D1%82%D0%B0%D1%80%D1%82/%D1%81%D0%BE%D0%B7%D0%B4%D0%B0%D0%BD%D0%B8%D0%B5%20%D0%BE%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D0%BE%D0%B2)