negodiy/aiform_dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e27280e675a9bae8096d14bed995dedd270581aa
aiform_dev/DOCUMENT_ATTACH_API.md

8.1 KiB
Raw Blame History

📎 API для привязки документов к проекту/заявке

✅ Готово к использованию!

🎯 Эндпоинт

POST https://crm.clientright.ru/api/n8n/documents/attach

📋 Параметры запроса

Обязательные:

Параметр Тип Описание Пример
contact_id string ID контакта в vTiger "320096"
project_id string ID проекта (полиса) в vTiger "396874"
file_url string Полный URL файла в S3 "https://s3.twcstorage.ru/..."
file_name string Имя файла "boarding_pass.pdf"

Опциональные:

Параметр Тип Описание Пример
ticket_id string ID заявки в HelpDesk
Если указан → привязка к заявке
Если не указан → привязка к проекту		 "396935"
file_type string Описание типа документа "flight_delay_boarding_or_ticket"

🔧 Логика работы

┌─────────────────────────────────────────────┐
│  POST /api/n8n/documents/attach             │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
         ┌────────────────┐
         │ ticket_id есть?│
         └────────┬───────┘
                  │
        ┌─────────┴─────────┐
        │                   │
       ДА                  НЕТ
        │                   │
        ▼                   ▼
┌───────────────┐   ┌──────────────┐
│ Привязка к    │   │ Привязка к   │
│ HelpDesk      │   │ Project      │
│ (заявке)      │   │ (проекту)    │
└───────────────┘   └──────────────┘

📤 Примеры запросов

1️⃣ Привязка к проекту (без заявки)

Используется когда файл относится к полису в целом, но еще нет конкретной заявки.

curl -X POST "https://crm.clientright.ru/api/n8n/documents/attach" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "320096",
    "project_id": "396874",
    "file_url": "https://s3.twcstorage.ru/f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c/clientright/test/policy_scan.pdf",
    "file_name": "policy_E1000-302538529.pdf",
    "file_type": "Скан полиса ERV"
  }'

Ответ:

{
  "success": true,
  "result": {
    "document_id": "15x396940",
    "document_numeric_id": "396940",
    "attached_to": "project",        // ✅ Привязан к проекту
    "attached_to_id": "396874",
    "file_name": "policy_E1000-302538529.pdf",
    "file_type": "Скан полиса ERV",
    "s3_bucket": "f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c",
    "s3_key": "clientright/test/policy_scan.pdf",
    "file_size": 125840,
    "message": "Документ создан с правильными S3 метаданными и привязан к проекту"
  }
}

2️⃣ Привязка к заявке (HelpDesk)

Используется когда файл относится к конкретной заявке (страховому случаю).

curl -X POST "https://crm.clientright.ru/api/n8n/documents/attach" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "320096",
    "project_id": "396874",
    "ticket_id": "396935",          // ✅ Указан ticket_id
    "file_url": "https://s3.twcstorage.ru/f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c/clientright/test/boarding_pass.pdf",
    "file_name": "boarding_pass_20251102.pdf",
    "file_type": "flight_delay_boarding_or_ticket"
  }'

Ответ:

{
  "success": true,
  "result": {
    "document_id": "15x396941",
    "document_numeric_id": "396941",
    "attached_to": "ticket",         // ✅ Привязан к заявке
    "attached_to_id": "396935",
    "file_name": "boarding_pass_20251102.pdf",
    "file_type": "flight_delay_boarding_or_ticket",
    "s3_bucket": "f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c",
    "s3_key": "clientright/test/boarding_pass.pdf",
    "file_size": 85320,
    "message": "Документ создан с правильными S3 метаданными и привязан к проекту"
  }
}

🗂️ Типы файлов (file_type)

Примеры значений для file_type:

Тип Описание
flight_delay_boarding_or_ticket Посадочный талон / билет при задержке рейса
flight_delay_confirmation Подтверждение задержки рейса
flight_cancel_confirmation Подтверждение отмены рейса
medical_receipt Медицинский чек
medical_report Медицинское заключение
luggage_delay_report Акт о задержке багажа
passport_scan Скан паспорта
policy_scan Скан страхового полиса
other Прочие документы

📊 Интеграция с n8n

В workflow после загрузки файла в S3:

// HTTP Request Node: POST /api/n8n/documents/attach
{
  "contact_id": "{{ $json.contact_id }}",
  "project_id": "{{ $json.project_id }}",
  "ticket_id": "{{ $json.ticket_id }}",  // Опционально
  "file_url": "{{ $json.s3_url }}",
  "file_name": "{{ $json.original_filename }}",
  "file_type": "{{ $json.document_type }}"
}

Ответ сохранить в Redis:

// Добавить в session:
{
  ...session_data,
  documents: [
    ...session_data.documents,
    {
      document_id: $json.result.document_id,
      file_name: $json.result.file_name,
      file_type: $json.result.file_type,
      attached_to: $json.result.attached_to,
      uploaded_at: new Date().toISOString()
    }
  ]
}

🔍 Логи

Backend (FastAPI):

cd /var/www/fastuser/data/www/crm.clientright.ru/erv_platform
docker-compose logs -f backend | grep "Attaching document"

Пример вывода:

📎 Attaching document: boarding_pass.pdf (type: flight_delay_boarding_or_ticket)
   Contact: 320096, Project: 396874, Ticket: 396935
📤 Sending to CRM: {...}
✅ Document attached successfully. Response: {...}

CRM (PHP):

tail -f /var/www/fastuser/data/www/crm.clientright.ru/logs/upload_documents.log

Пример вывода:

[2025-11-02 16:30:15] 🚀 Начинаем создание документов...
[2025-11-02 16:30:15] 📄 Обрабатываем файл #0: boarding_pass.pdf
[2025-11-02 16:30:16] ✅ Документ создан: 15x396941 (numeric: 396941)
[2025-11-02 16:30:16] 📎 Привязываем к HelpDesk ticket_id: 396935
[2025-11-02 16:30:17] ✅ Документ привязан к HelpDesk #396935

⚠️ Обработка ошибок

400 Bad Request - Отсутствуют обязательные поля

{
  "detail": "Обязательные поля: contact_id, project_id, file_url, file_name"
}

500 Internal Server Error - Ошибка CRM

{
  "detail": "CRM error: Не найден Project ID 999999"
}

504 Gateway Timeout - Таймаут CRM

{
  "detail": "Таймаут загрузки в CRM"
}

✅ Готово к использованию!

Эндпоинт протестирован и готов к интеграции в n8n workflow! 🚀