Очистка истории Wiki
BitCode
128
API.md
Normal file
128
API.md
Normal file
@@ -0,0 +1,128 @@
|
|||||||
|
# 📚 Документация API проекта: Excavators AI
|
||||||
|
|
||||||
|
> **Базовый URL:** `https://ex.neimarker.ru/api/` (или ваш рабочий домен)
|
||||||
|
> **Формат дат:** ISO 8601 (например, `2026-04-20T15:30:00Z`)
|
||||||
|
> **Аутентификация (Для интеграций):** Заголовок `Authorization: Api-Key <токен>`
|
||||||
|
> **Аутентификация (Web):** Заголовок `Authorization: Bearer <jwt_access_token>`
|
||||||
|
|
||||||
|
## 📑 Оглавление
|
||||||
|
1. [Аутентификация и интеграция](#auth)
|
||||||
|
2. [Экскаваторы (Базовый CRUD)](#devices_crud)
|
||||||
|
3. [Настройки графика и работы экскаватора](#device_settings)
|
||||||
|
4. [Аналитика и Цифровой двойник](#analytics)
|
||||||
|
5. [Видеоархив, Карты и Очистка данных](#video_archive)
|
||||||
|
---
|
||||||
|
|
||||||
|
<a name="auth"></a>
|
||||||
|
## 1. Аутентификация и интеграция
|
||||||
|
В системе предусмотрено два типа доступа: для живых пользователей (через веб-интерфейс с логином/паролем) и для сторонних систем (интеграция по статичному API-ключу).
|
||||||
|
|
||||||
|
### 🔑 Доступ для сторонних систем (Интеграция)
|
||||||
|
Для работы внешних скриптов, 1С, Telegram-ботов и других систем (M2M) капча и временные токены не используются.
|
||||||
|
|
||||||
|
> ⚠️ **Важно:** Для получения ключа интеграции (`Api-Key`) вашей организации необходимо обратиться в службу технической поддержки или к менеджеру.
|
||||||
|
|
||||||
|
### 💻 Пример на Python: Интеграция по Api-Key
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
BASE_URL = "https://ex.neimarker.ru/api/"
|
||||||
|
# Токен, выданный для вашей организации
|
||||||
|
API_KEY = "ВАШ_УНИКАЛЬНЫЙ_ТОКЕН_ИНТЕГРАЦИИ"
|
||||||
|
|
||||||
|
headers = {
|
||||||
|
"Authorization": f"Api-Key {API_KEY}"
|
||||||
|
}
|
||||||
|
|
||||||
|
# Пример 1: Запрашиваем список всех доступных экскаваторов вашей организации
|
||||||
|
devices_res = requests.get(f"{BASE_URL}/devices/", headers=headers)
|
||||||
|
print("Доступная техника:", devices_res.json())
|
||||||
|
|
||||||
|
# Пример 2: Запрашиваем аналитику по одному экскаватору
|
||||||
|
analytics_res = requests.get(
|
||||||
|
f"{BASE_URL}/analytics/?device_id=1&start_date=2026-04-20T00:00:00Z&end_date=2026-04-20T23:59:59Z",
|
||||||
|
headers=headers
|
||||||
|
)
|
||||||
|
print("Аналитика:", analytics_res.json())
|
||||||
|
```
|
||||||
|
---
|
||||||
|
<a name="devices_crud"></a>
|
||||||
|
## 2. Экскаваторы (Базовый CRUD)
|
||||||
|
Автоматически ограничивает выдачу только устройствами, принадлежащими организации, чей токен совершает запрос.
|
||||||
|
|
||||||
|
| Метод | Эндпоинт | Описание |
|
||||||
|
|---|---|---|
|
||||||
|
| `GET` | `/devices/` | Список всех устройств организации. |
|
||||||
|
| `POST` | `/devices/` | Создание устройства. Ожидает: `name`, `bucket_volume`. MAC и API-токен генерируются автоматически. |
|
||||||
|
| `GET` | `/devices/<id>/` | Данные одного устройства. |
|
||||||
|
| `PATCH`| `/devices/<id>/` | Изменение параметров (объем ковша, смены, часовой пояс `timezone_offset` и т.д.). |
|
||||||
|
| `DELETE`| `/devices/<id>/`| Удаление. (Можно удалять только устройства с MAC "OFFLINE-..."). |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<a name="device_settings"></a>
|
||||||
|
## 3. Настройки графика и работы экскаватора
|
||||||
|
Вложенные справочники для конкретного `device_id`. Поддерживают создание, чтение списка и удаление по `pk` (ID записи).
|
||||||
|
|
||||||
|
| Метод | Эндпоинт | Описание |
|
||||||
|
|---|---|---|
|
||||||
|
| `GET`, `POST` | `/devices/<device_id>/materials/` | Типы грунта (плотность, коэффициенты) на заданный период. |
|
||||||
|
| `DELETE` | `/devices/<device_id>/materials/<pk>/`| Удалить настройку материала. |
|
||||||
|
| `GET`, `POST` | `/devices/<device_id>/schedule-exceptions/` | Исключения графика: ТО, ремонты, выходные, спец-смены. |
|
||||||
|
| `DELETE` | `/devices/<device_id>/schedule-exceptions/<pk>/` | Удалить исключение. |
|
||||||
|
| `GET`, `POST` | `/devices/<device_id>/breaks/` | Ежедневные перерывы (например, Обед 12:00 - 13:00). |
|
||||||
|
| `DELETE` | `/devices/<device_id>/breaks/<pk>/` | Удалить перерыв. |
|
||||||
|
| `GET`, `POST` | `/devices/<device_id>/shifts/` | Настройка смен (при `has_multiple_shifts=True` у устройства). |
|
||||||
|
| `DELETE` | `/devices/<device_id>/shifts/<pk>/` | Удалить смену. |
|
||||||
|
|
||||||
|
### 💻 Пример на Python: Настройка расписания
|
||||||
|
```python
|
||||||
|
device_id = 1
|
||||||
|
headers = {"Authorization": f"Api-Key {API_KEY}"}
|
||||||
|
|
||||||
|
# 1. Добавляем обед
|
||||||
|
requests.post(f"{BASE_URL}/devices/{device_id}/breaks/", headers=headers, json={
|
||||||
|
"start_time": "12:00:00",
|
||||||
|
"end_time": "13:00:00",
|
||||||
|
"description": "Обеденный перерыв"
|
||||||
|
})
|
||||||
|
|
||||||
|
# 2. Добавляем исключение (выходной / праздник)
|
||||||
|
requests.post(f"{BASE_URL}/devices/{device_id}/schedule-exceptions/", headers=headers, json={
|
||||||
|
"date": "2026-05-01",
|
||||||
|
"end_date": "2026-05-01",
|
||||||
|
"is_working": False,
|
||||||
|
"is_maintenance": False,
|
||||||
|
"description": "День Труда"
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<a name="analytics"></a>
|
||||||
|
## 4. Аналитика и Цифровой двойник
|
||||||
|
Тяжелые вычислительные эндпоинты для получения отчетов и метрик.
|
||||||
|
|
||||||
|
| Метод | Эндпоинт | Описание |
|
||||||
|
|---|---|---|
|
||||||
|
| `GET` | `/analytics/` | Сводная аналитика. Требует параметры `?device_id=...&start_date=...&end_date=...`. Возвращает объемы, массу, таймлайн, циклы, телеметрию (JSON). |
|
||||||
|
| `POST` | `/analytics/recalculate/` | Полный пересчет аналитики (сборка циклов и простоев). Ожидает JSON: `device_id`, `start_date`. Запускается в фоне. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<a name="video_archive"></a>
|
||||||
|
## 5. Видеоархив, Карты и Очистка данных
|
||||||
|
Все, что связано с видео, треками и управлением сырыми данными устройства.
|
||||||
|
|
||||||
|
| Метод | Эндпоинт | Описание |
|
||||||
|
|---|---|---|
|
||||||
|
| `GET` | `/devices/<device_id>/available-dates/` | Массив дат (YYYY-MM-DD), за которые есть загруженные данные. |
|
||||||
|
| `GET` | `/devices/<device_id>/folders/` | Список папок архива (кусков видео по 1 часу). |
|
||||||
|
| `GET` | `/devices/<device_id>/folders/<folder_id>/detections/` | Координаты рамок (Bounding Boxes) для рисования поверх видеоплеера. |
|
||||||
|
| `GET` | `/devices/<device_id>/video-frame/?timestamp=...` | Поиск видеофайла и секунды для перемотки по точному времени. |
|
||||||
|
| `GET` | `/devices/<device_id>/trajectory/?start_date=...&end_date=...`| Координаты GPS для отрисовки линии маршрута на карте. |
|
||||||
|
| `POST`| `/devices/<device_id>/upload-archive/` | Ручная загрузка оффлайн `.zip` архива. Возвращает Streaming HTTP с логами распаковки. |
|
||||||
|
| `GET` | `/devices/<device_id>/alerts/` | Список последних экстренных событий (Алертов) от устройства. |
|
||||||
|
| `POST`| `/devices/<device_id>/clear-data/` | **Опасная операция.** Очистка данных устройства. JSON: `{"mode": "all"}` или `{"mode": "date", "date": "..."}`. |
|
||||||
|
|
||||||
|
---
|
||||||
1
Home.md
Normal file
1
Home.md
Normal file
@@ -0,0 +1 @@
|
|||||||
|
1 странийца
|
||||||
Reference in New Issue
Block a user