crm.clientright.ru/erv_ticket/API_INTEGRATIONS.md

# 🔌 API Интеграции ERV Ticket

**Создано**: 23.10.2025

---

## 📋 Список всех API

| API | URL | Назначение | Статус |
|-----|-----|------------|--------|
| OCR Analyzer | http://147.45.146.17:8001 | Распознавание документов | ✅ Работает |
| RAG Analyzer | http://147.45.146.17:8000 | ИИ анализ (в разработке?) | ⚠️ Ошибка |
| FlightAware | https://aeroapi.flightaware.com | Проверка рейсов | 📝 Не тестировали |
| AviationStack | https://api.aviationstack.com | Проверка рейсов (fallback) | 📝 Не тестировали |
| NSPK Banks | http://212.193.27.93 | Справочник банков СБП | 📝 Не тестировали |

---

## 🤖 OCR Analyzer API (порт 8001)

### **Endpoint**: `/analyze-file`

### **Формат запроса:**
```http
POST http://147.45.146.17:8001/analyze-file
Content-Type: application/json

{
  "file_url": "https://example.com/document.pdf",  // ОБЯЗАТЕЛЬНО
  "file_name": "document.pdf",                      // опционально
  "file_type": "application/pdf"                    // опционально
}
```

### **Формат ответа:**
```json
{
  "success": true,
  "text_source": "ocr_only",
  "pages": 1,
  "text": "",
  
  "pages_data": [
    {
      "page": 1,
      "ocr_text": "ПАСПОРТ\nСерия: 4510\nНомер: 123456\nИванов Иван Иванович\nДата рождения: 01.01.1990",
      "image_path": "/tmp/xxx.png",
      "image_filename": "xxx.png",
      "image_url": "/static/vision_input/xxx.png"
    }
  ],
  
  "images_data": [
    {
      "page": 1,
      "filename": "xxx.png",
      "image_path": "/app/static/vision_input/xxx.png",
      "image_url": "/static/vision_input/xxx.png",
      "ocr_text": "ПАСПОРТ\nСерия: 4510\nНомер: 123456\nИванов Иван Иванович\nДата рождения: 01.01.1990",
      
      "send_to_vision": true,         ← Флаг для Vision AI
      "vision_reason": "has_keywords", ← Почему отправить на Vision
      "nsfw": false,                   ← Проверка на NSFW контент
      "nsfw_score": 0.019
    }
  ]
}
```

### **Особенности:**

1. ✅ **Поддерживает только PDF файлы** (не JPG/PNG напрямую)
2. ✅ **Отлично распознаёт русский текст** (кириллица)
3. ✅ **Работает с удалёнными файлами** (по file_url)
4. ✅ **Timeout: 600 секунд** (10 минут)
5. ✅ **Есть флаг send_to_vision** - возможна дополнительная обработка
6. ✅ **NSFW фильтр** - проверяет контент

### **Извлечение текста:**
```php
// Берём текст из первой страницы
$ocr_text = $response['pages_data'][0]['ocr_text'];

// Или из images_data
$ocr_text = $response['images_data'][0]['ocr_text'];
```

---

## 🧠 RAG Analyzer API (порт 8000)

### **Статус**: ⚠️ Возвращает Internal Server Error

**Возможные причины**:
- Требует другой формат запроса
- Не настроен / в разработке
- Нужна дополнительная авторизация

**TODO**: Узнать у разработчика RAG формат запросов

---

## ✈️ FlightAware API

### **Endpoint**: `https://aeroapi.flightaware.com/aeroapi/flights/{flight_number}`

### **Авторизация:**
```
API Key: Puz0cdxAHzAEqMRZwtdeqBUSm9naJfwK
Header: x-apikey: YOUR_API_KEY
```

### **Пример запроса:**
```bash
curl "https://aeroapi.flightaware.com/aeroapi/flights/SU1234" \
  -H "x-apikey: Puz0cdxAHzAEqMRZwtdeqBUSm9naJfwK"
```

### **Документация**: https://www.flightaware.com/aeroapi/portal/documentation

---

## ✈️ AviationStack API (Fallback)

### **Endpoint**: `https://api.aviationstack.com/v1/flights`

### **Авторизация:**
```
Access Key: 847291a3f87179599b844e8dde4d161e
Parameter: ?access_key=YOUR_KEY
```

### **Пример запроса:**
```bash
curl "https://api.aviationstack.com/v1/flights?access_key=847291a3f87179599b844e8dde4d161e&flight_iata=SU1234"
```

### **Документация**: https://aviationstack.com/documentation

---

## 🏦 NSPK Banks API (СБП)

### **Endpoint**: `http://212.193.27.93/api/payouts/dictionaries/nspk-banks`

### **Авторизация**: Не требуется (публичный)

### **Пример запроса:**
```bash
curl "http://212.193.27.93/api/payouts/dictionaries/nspk-banks"
```

### **Формат ответа** (предположительно):
```json
[
  {
    "bank_code": "100000000001",
    "bank_name": "ПАО Сбербанк",
    "bic": "044525225"
  },
  {
    "bank_code": "100000000004",
    "bank_name": "ВТБ (ПАО)",
    "bic": "044525187"
  }
]
```

**TODO**: Протестировать и посмотреть реальный формат

---

## 🎯 Архитектура интеграции:

### **Поток обработки документа:**

```
1. Пользователь загружает файл
         ↓
2. Конвертация в PDF (если JPG/PNG)
         ↓
3. Загрузка в S3 → получаем file_url
         ↓
4. POST → OCR API (8001)
   {
     "file_url": "https://s3.timeweb.cloud/.../passport.pdf",
     "file_name": "passport.pdf"
   }
         ↓
5. OCR возвращает распознанный текст
   {
     "ocr_text": "ПАСПОРТ\nСерия: 4510\n..."
   }
         ↓
6. Извлечение структурированных данных (нужен ИИ)
   
   ВАРИАНТ A: Свой Vision API (если есть endpoint)
   ВАРИАНТ B: GPT-4 / Claude для парсинга текста
   ВАРИАНТ C: Регулярные выражения (менее надёжно)
         ↓
7. Автозаполнение формы
   {
     "surname": "Иванов",
     "name": "Иван",
     "patronymic": "Иванович",
     "birthdate": "01.01.1990",
     "passport_series": "4510",
     "passport_number": "123456"
   }
```

---

## 🔧 Технические детали:

### **Требования OCR API:**

1. ✅ **Формат файла**: PDF (обязательно!)
2. ✅ **Доступ к файлу**: По URL (не multipart upload)
3. ✅ **Timeout**: До 10 минут
4. ✅ **Content-Type**: application/json

### **Подготовка файлов для OCR:**

```php
// Если пользователь загрузил JPG/PNG
if (mime_type !== 'application/pdf') {
    // 1. Конвертируем в PDF
    convert image.jpg image.pdf
    
    // 2. Загружаем PDF в S3
    $s3_url = S3::upload('image.pdf');
    
    // 3. Отправляем на OCR
    OCR::analyze($s3_url);
}
```

---

## ❓ Вопросы для уточнения:

### 1. **Vision API (ИИ)**
- У вас есть свой Vision endpoint?
- Или нужно подключать GPT-4/Claude?
- Или RAG analyzer (8000) должен это делать?

### 2. **S3 Timeweb**
- Где креды? В `/var/www/fastuser/data/www/crm.clientright.ru/.env`?
- Или в другом месте?

### 3. **Проверка рейсов**
- Какой API использовать: FlightAware (основной) или AviationStack?
- Нужен ли fallback на второй если первый не работает?

---

## 🚀 Что делаю дальше?

**План:**

1. ✅ Тестирую NSPK Banks API
2. ✅ Тестирую Flight APIs (если дашь добро)
3. ✅ Создаю сервисы для всех API
4. ✅ Решаем вопрос с Vision/ИИ
5. ✅ Интегрирую всё в форму

**Продолжать тестировать APIs?** 🧪