From 57a6b4943a70e40e6653a00f90c924cc6f7f309f Mon Sep 17 00:00:00 2001
From: BitCode <bitcode@mail.ru>
Date: Thu, 23 Apr 2026 13:47:27 +0300
Subject: [PATCH] =?UTF-8?q?=D0=9E=D1=87=D0=B8=D1=81=D1=82=D0=BA=D0=B0=20?=
 =?UTF-8?q?=D0=B8=D1=81=D1=82=D0=BE=D1=80=D0=B8=D0=B8=20Wiki?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 API.md  | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Home.md |   1 +
 2 files changed, 129 insertions(+)
 create mode 100644 API.md
 create mode 100644 Home.md

diff --git a/API.md b/API.md
new file mode 100644
index 0000000..43879ba
--- /dev/null
+++ b/API.md
@@ -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": "..."}`. |
+
+---
\ No newline at end of file
diff --git a/Home.md b/Home.md
new file mode 100644
index 0000000..0408d9f
--- /dev/null
+++ b/Home.md
@@ -0,0 +1 @@
+1 странийца
\ No newline at end of file