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

Формат запроса:

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"                    // опционально
}

Формат ответа:

{
  "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 фильтр - проверяет контент

Извлечение текста:

// Берём текст из первой страницы
$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

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

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

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

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

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

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

curl "http://212.193.27.93/api/payouts/dictionaries/nspk-banks"

Формат ответа (предположительно):

[
  {
    "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:

// Если пользователь загрузил 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? 🧪