crm.clientright.ru/crm_extensions/file_storage/NEXTCLOUD_API_OVERVIEW.md

# 🌐 Nextcloud API - Обзор и возможности

## 📋 Доступные API

### 1. **WebDAV API** ✅ (РАБОТАЕТ)
**Базовый URL:** `https://office.clientright.ru:8443/remote.php/webdav/`

**Аутентификация:** Basic Auth (admin + app password)

**Возможности:**
- ✅ Список файлов и папок (PROPFIND)
- ✅ Загрузка файлов (PUT)
- ✅ Скачивание файлов (GET)
- ✅ Удаление файлов (DELETE)
- ✅ Создание папок (MKCOL)
- ✅ Перемещение/копирование (MOVE/COPY)
- ✅ Получение метаданных (PROPFIND)

**Пример - список файлов:**
```bash
curl -u "admin:APP_PASSWORD" \
  -X PROPFIND \
  "https://office.clientright.ru:8443/remote.php/webdav/" \
  -H "Depth: 1"
```

**Пример - загрузка файла:**
```bash
curl -u "admin:APP_PASSWORD" \
  -T /path/to/local/file.txt \
  "https://office.clientright.ru:8443/remote.php/webdav/file.txt"
```

**Пример - скачивание файла:**
```bash
curl -u "admin:APP_PASSWORD" \
  "https://office.clientright.ru:8443/remote.php/webdav/file.txt" \
  -o downloaded.txt
```

---

### 2. **OCS API (Open Collaboration Services)** ✅

**Базовый URL:** `https://office.clientright.ru:8443/ocs/v2.php/`

**Заголовки:** `OCS-APIRequest: true`

**Формат ответа:** JSON (`?format=json`)

#### 2.1 **Capabilities API** (информация о сервере)
```bash
curl -u "admin:APP_PASSWORD" \
  "https://office.clientright.ru:8443/ocs/v1.php/cloud/capabilities?format=json" \
  -H "OCS-APIRequest: true"
```

**Ответ включает:**
- Версию Nextcloud (31.0.9)
- Доступные возможности
- Лимиты загрузки
- Настройки шаринга

---

#### 2.2 **Activity API** ✅ (СОБЫТИЯ ФАЙЛОВ!)

**URL:** `https://office.clientright.ru:8443/ocs/v2.php/apps/activity/api/v2/activity`

**Параметры:**
- `format=json` - формат ответа
- `limit=N` - количество событий
- `since=TIMESTAMP` - события после определённой даты

**Пример:**
```bash
curl -u "admin:APP_PASSWORD" \
  "https://office.clientright.ru:8443/ocs/v2.php/apps/activity/api/v2/activity?format=json&limit=10" \
  -H "OCS-APIRequest: true"
```

**Типы событий:**
- `file_created` - файл создан
- `file_changed` - файл изменён
- `file_deleted` - файл удалён
- `file_restored` - файл восстановлен
- `file_shared` - файл расшарен

**Структура события:**
```json
{
  "activity_id": 195,
  "type": "file_created",
  "subject": "Вы создали «experimental_report.xlsx»",
  "message": "",
  "object_type": "files",
  "object_id": 73460,
  "object_name": "/experimental_report.xlsx",
  "datetime": "2025-10-30T12:53:40+00:00",
  "user": "admin"
}
```

**⚠️ Ограничения:**
- Нет real-time уведомлений (только polling)
- События агрегируются (несколько файлов в одном событии)
- Может быть задержка до минуты

---

#### 2.3 **Users API**

**Список пользователей:**
```bash
curl -u "admin:APP_PASSWORD" \
  "https://office.clientright.ru:8443/ocs/v1.php/cloud/users?format=json" \
  -H "OCS-APIRequest: true"
```

**Информация о пользователе:**
```bash
curl -u "admin:APP_PASSWORD" \
  "https://office.clientright.ru:8443/ocs/v1.php/cloud/users/admin?format=json" \
  -H "OCS-APIRequest: true"
```

---

#### 2.4 **Sharing API**

**Список расшаренных файлов:**
```bash
curl -u "admin:APP_PASSWORD" \
  "https://office.clientright.ru:8443/ocs/v2.php/apps/files_sharing/api/v1/shares?format=json" \
  -H "OCS-APIRequest: true"
```

**Создать публичную ссылку:**
```bash
curl -u "admin:APP_PASSWORD" \
  -X POST \
  -d "path=/file.txt&shareType=3" \
  "https://office.clientright.ru:8443/ocs/v2.php/apps/files_sharing/api/v1/shares?format=json" \
  -H "OCS-APIRequest: true"
```

---

### 3. **Direct Download URL**

Для файлов можно получить прямую ссылку скачивания:

**Формат:**
```
https://office.clientright.ru:8443/index.php/apps/files/ajax/download.php?dir=/&files=filename.txt
```

Или через WebDAV:
```
https://office.clientright.ru:8443/remote.php/webdav/filename.txt
```

---

## 🎯 Использование для мониторинга файлов

### Вариант 1: Activity API Polling (РЕКОМЕНДУЮ для Nextcloud)

**Создай n8n workflow:**

```
┌─────────────────────────────────────────────┐
│  Schedule (каждые 30 сек)                   │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│  HTTP Request                               │
│  GET /ocs/v2.php/apps/activity/api/v2/      │
│      activity?format=json&limit=100         │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│  Code (JS)                                  │
│  - Фильтруем file_created/changed/deleted  │
│  - Сохраняем последний activity_id          │
│  - Возвращаем только новые события          │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│  Redis Publish                              │
│  Channel: crm:file:events                   │
└─────────────────────────────────────────────┘
```

**Преимущества:**
- ✅ Официальный API
- ✅ Надёжный
- ✅ Детальная информация о событиях
- ✅ Не требует доступа к Redis Nextcloud

**Недостатки:**
- ⚠️ Задержка 30-60 сек (polling)
- ⚠️ События агрегируются

---

### Вариант 2: Redis Bridge (УЖЕ РАБОТАЕТ!)

```
Nextcloud Redis (notify_storage_update) → 
→ redis_bridge.js → 
→ CRM Redis (crm:file:events)
```

**Преимущества:**
- ✅ Real-time (~1-2 сек)
- ✅ Не нагружает Nextcloud API

**Недостатки:**
- ⚠️ Требует доступ к внутреннему Redis
- ⚠️ Меньше метаданных

---

## 📊 Сравнение подходов

| Метод | Задержка | Детали | Сложность | Надёжность |
|-------|----------|--------|-----------|------------|
| **Activity API** | 30-60с | ⭐⭐⭐ | Низкая | ⭐⭐⭐ |
| **Redis Bridge** | 1-2с | ⭐⭐ | Средняя | ⭐⭐⭐ |
| **S3 Monitor** | 0-30с | ⭐⭐ | Низкая | ⭐⭐⭐ |
| **WebDAV Poll** | 60с+ | ⭐ | Низкая | ⭐⭐ |

---

## 🛠️ Примеры кода

### PHP - Получение последних событий

```php
<?php
$username = 'admin';
$password = 'APP_PASSWORD';
$url = 'https://office.clientright.ru:8443/ocs/v2.php/apps/activity/api/v2/activity?format=json&limit=10';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['OCS-APIRequest: true']);

$response = curl_exec($ch);
$data = json_decode($response, true);

foreach ($data['ocs']['data'] as $activity) {
    if (in_array($activity['type'], ['file_created', 'file_changed', 'file_deleted'])) {
        echo "Event: {$activity['type']}\n";
        echo "File: {$activity['object_name']}\n";
        echo "Time: {$activity['datetime']}\n";
        echo "---\n";
    }
}
?>
```

### Node.js - Activity API Monitor

```javascript
const axios = require('axios');
const Redis = require('ioredis');

const CONFIG = {
    nextcloud: {
        url: 'https://office.clientright.ru:8443',
        username: 'admin',
        password: 'APP_PASSWORD'
    },
    redis: {
        host: '147.45.146.17',
        port: 6379,
        password: 'CRM_Redis_Pass_2025_Secure!'
    },
    pollInterval: 30000 // 30 секунд
};

const redis = new Redis(CONFIG.redis);
let lastActivityId = 0;

async function checkActivities() {
    try {
        const response = await axios.get(
            `${CONFIG.nextcloud.url}/ocs/v2.php/apps/activity/api/v2/activity`,
            {
                params: { format: 'json', limit: 100 },
                headers: { 'OCS-APIRequest': 'true' },
                auth: {
                    username: CONFIG.nextcloud.username,
                    password: CONFIG.nextcloud.password
                }
            }
        );

        const activities = response.data.ocs.data;
        const fileEvents = activities.filter(a => 
            ['file_created', 'file_changed', 'file_deleted'].includes(a.type) &&
            a.activity_id > lastActivityId
        );

        for (const event of fileEvents.reverse()) {
            const payload = {
                type: event.type,
                source: 'nextcloud_activity',
                timestamp: event.datetime,
                file_id: event.object_id,
                path: event.object_name,
                filename: event.object_name.split('/').pop(),
                user: event.user
            };

            await redis.publish('crm:file:events', JSON.stringify(payload));
            console.log(`📤 Published: ${event.type} - ${event.object_name}`);
            
            lastActivityId = Math.max(lastActivityId, event.activity_id);
        }

    } catch (error) {
        console.error('❌ Error:', error.message);
    }
}

// Запуск
console.log('🚀 Nextcloud Activity Monitor');
setInterval(checkActivities, CONFIG.pollInterval);
checkActivities();
```

---

## 🎯 Рекомендации

### Для твоего use case:

**Комбинируй несколько подходов:**

1. **Nextcloud файлы (WebUI)** → **Redis Bridge** (real-time, 1-2с)
2. **S3 прямые загрузки** → **n8n S3 Monitor** (polling, 0-30с)
3. **CRM загрузки** → **Прямая публикация в Redis** (instant)

**Все события в одном канале:** `crm:file:events`

**Альтернатива (если нужна простота):**
- Используй **только Activity API** через n8n для Nextcloud событий
- Плюс **S3 Monitor** для прямых загрузок в S3

---

## 📚 Полезные ссылки

- [Nextcloud WebDAV Documentation](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/)
- [Nextcloud OCS API](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/)
- [Activity API](https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md)

---

## 🔐 Безопасность

**App Password:** `tGHKS-3cC9m-7Hggb-65Awk-zxWQE`  
**Пользователь:** `admin`

⚠️ **Важно:** Используй App Passwords, а не основной пароль!

---

**Готово! Теперь ты знаешь все доступные API Nextcloud! 🎉**