docs: Добавлена полная документация API привязки документов
This commit is contained in:
AI Assistant
251
DOCUMENT_ATTACH_API.md
Normal file
251
DOCUMENT_ATTACH_API.md
Normal file
@@ -0,0 +1,251 @@
|
|||||||
|
# 📎 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<br/>**Если указан → привязка к заявке**<br/>**Если не указан → привязка к проекту** | `"396935"` |
|
||||||
|
| `file_type` | string | Описание типа документа | `"flight_delay_boarding_or_ticket"` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 Логика работы
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ POST /api/n8n/documents/attach │
|
||||||
|
└─────────────────┬───────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────┐
|
||||||
|
│ ticket_id есть?│
|
||||||
|
└────────┬───────┘
|
||||||
|
│
|
||||||
|
┌─────────┴─────────┐
|
||||||
|
│ │
|
||||||
|
ДА НЕТ
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌───────────────┐ ┌──────────────┐
|
||||||
|
│ Привязка к │ │ Привязка к │
|
||||||
|
│ HelpDesk │ │ Project │
|
||||||
|
│ (заявке) │ │ (проекту) │
|
||||||
|
└───────────────┘ └──────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📤 Примеры запросов
|
||||||
|
|
||||||
|
### 1️⃣ Привязка к проекту (без заявки)
|
||||||
|
|
||||||
|
Используется когда файл относится к полису в целом, но еще нет конкретной заявки.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Ответ:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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)
|
||||||
|
|
||||||
|
Используется когда файл относится к конкретной заявке (страховому случаю).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Ответ:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// 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:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Добавить в 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):
|
||||||
|
```bash
|
||||||
|
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):
|
||||||
|
```bash
|
||||||
|
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 - Отсутствуют обязательные поля
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"detail": "Обязательные поля: contact_id, project_id, file_url, file_name"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 500 Internal Server Error - Ошибка CRM
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"detail": "CRM error: Не найден Project ID 999999"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 504 Gateway Timeout - Таймаут CRM
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"detail": "Таймаут загрузки в CRM"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Готово к использованию!
|
||||||
|
|
||||||
|
Эндпоинт протестирован и готов к интеграции в n8n workflow! 🚀
|
||||||
|
|
||||||
Reference in New Issue
Block a user