diff --git a/DOCUMENT_ATTACH_API.md b/DOCUMENT_ATTACH_API.md
new file mode 100644
index 0000000..c3db4f7
--- /dev/null
+++ b/DOCUMENT_ATTACH_API.md
@@ -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! 🚀
+