Перейти к содержанию

Сценарии использования API

Описание типовых сценариев работы с API системы управления гарантийными заявками.

Описание статусов

Статус Описание Действия
Новая Заявка только что создана Автоматическая передача застройщику
Передано застройщику Заявка отправлена застройщику Ожидание принятия в работу
Принято застройщиком Застройщик принял заявку Выполнение работ
Выполнено застройщиком Работы завершены Заявка закрыта
Отменено Заявка отменена Заявка закрыта

👥 Схема взаимодействия участников

sequenceDiagram participant Заявитель participant Высота as Внутр. контур
Высота participant API as VSTA_API_HUB participant Застройщик participant СистемаЗ as Система
Застройщика Note over Заявитель, СистемаЗ: Полный цикл обработки гарантийной заявки Заявитель->>+Высота: Подача заявки через
внутренние каналы Высота->>Высота: Валидация как
гарантийная заявка
для застройщика Note over Высота, API: Передача в API для застройщика Высота->>+API: POST /warranty-claims/
Создание заявки в API API->>API: Генерация номера
VSTA-2024-XXXXXX API->>API: Назначение исполнителя API->>-Высота: Статус "Новая" Высота->>-Заявитель: Уведомление о принятии Note over API, Застройщик: Получение заявок застройщиком Застройщик->>+API: GET /warranty-claims/
Получение списка заявок API->>-Застройщик: Список новых заявок Застройщик->>+СистемаЗ: Регистрация заявки
в своей системе СистемаЗ->>-Застройщик: Внутренний номер заявки Note over Застройщик, API: Принятие в работу Застройщик->>+API: PATCH /warranty-claims/{id}/status
Статус "Принято застройщиком" API->>-Застройщик: Подтверждение изменения Note over Застройщик, СистемаЗ: Выполнение работ Застройщик->>СистемаЗ: Назначение мастера
и планирование работ СистемаЗ->>СистемаЗ: Выполнение работ
мастером Note over Застройщик, API: Завершение или отмена alt Работы выполнены успешно Застройщик->>+API: PATCH /warranty-claims/{id}/status
Статус "Выполнено застройщиком" Застройщик->>+API: POST /warranty-claims/{id}/result
Комментарий + вложения API->>-Застройщик: Подтверждение else Работы отменены Застройщик->>+API: PATCH /warranty-claims/{id}/status
Статус "Отменено" API->>-Застройщик: Подтверждение end Note over API, Высота: Возврат результата API->>+Высота: Результат заявки
(статус + комментарий + файлы) Высота->>Высота: Обработка результата
во внутреннем контуре Высота->>-Заявитель: Уведомление о результате
выполнения заявки

🔐 Авторизация

В текущей версии API работает без авторизации для упрощения интеграции. В будущих версиях планируется добавление JWT токенов.

Получение доступа:

  • Токен доступа выдается пользователю через запрос к менеджеру проекта
  • Токен передается в заголовке Authorization: Bearer {token}

📋 Базовый сценарий обмена заявками

1. Создание пользователя-исполнителя

Перед созданием заявок необходимо создать пользователя-исполнителя:

curl -X POST "http://localhost:8000/api/v1/users/" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Петров Иван Сергеевич",
    "email": "petrov@builder.ru",
    "phone": "+7 (495) 123-45-67"
  }'

Ответ:

{
  "id": 1,
  "full_name": "Петров Иван Сергеевич",
  "email": "petrov@builder.ru",
  "phone": "+7 (495) 123-45-67",
  "created_at": "2024-01-15T10:00:00Z"
}

2. Подача заявки заявителем

Заявитель (житель) подает заявку через внешнюю систему или форму:

curl -X POST "http://localhost:8000/api/v1/warranty-claims/" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Протечка воды с потолка на балконе после сильного дождя. Вода капает на пол и мебель.",
    "comment": "Проблема появилась после последнего дождя 10 января. Срочно требует устранения.",
    "what_happened": "Протечка воды через потолок балкона",
    "where_happened": "г. Москва, ул. Примерная, д. 15, корп. 2, кв. 87, балкон",
    "executor_id": 1,
    "applicant_data": {
      "full_name": "Сидорова Мария Александровна",
      "phone": "+7 (916) 555-12-34",
      "email": "sidorova@example.com"
    }
  }'

Ответ:

{
  "id": 1,
  "claim_number": "VSTA-2024-000001",
  "status": "Новая",
  "description": "Протечка воды с потолка на балконе...",
  "executor": {
    "id": 1,
    "full_name": "Петров Иван Сергеевич",
    "email": "petrov@builder.ru"
  },
  "created_at": "2024-01-15T14:30:00Z"
}

3. Получение списка заявок

Застройщик получает список новых заявок:

curl "http://localhost:8000/api/v1/warranty-claims/?status=Новая&limit=10"

4. Изменение статуса заявки

Застройщик принимает заявку в работу:

curl -X PATCH "http://localhost:8000/api/v1/warranty-claims/1/status" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Принято застройщиком",
    "comment": "Заявка принята в работу. Мастер выйдет 16.01.2024 с 14:00 до 18:00"
  }'

5. Завершение работ

После выполнения работ застройщик добавляет результат:

curl -X POST "http://localhost:8000/api/v1/warranty-claims/1/result" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Устранена протечка кровли. Заменены поврежденные участки гидроизоляции. Проведена контрольная проливка.",
    "attachments": [
      {
        "filename": "result_photo_1.jpg",
        "file_path": "/uploads/results/result_photo_1.jpg",
        "file_size": 2048000,
        "mime_type": "image/jpeg"
      }
    ]
  }'

Заявка автоматически переводится в статус "Выполнено застройщиком".

🔄 Дополнительные сценарии

Отмена заявки

Если заявка подана ошибочно или проблема решена иным способом:

curl -X DELETE "http://localhost:8000/api/v1/warranty-claims/1"

Изменение данных заявки

Корректировка описания или других данных (только для заявок в статусе "Новая"):

curl -X PUT "http://localhost:8000/api/v1/warranty-claims/1" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Обновленное описание проблемы",
    "where_happened": "Уточненный адрес"
  }'

Фильтрация заявок

Получение заявок по различным критериям:

# По исполнителю
curl "http://localhost:8000/api/v1/warranty-claims/?executor_id=1"

# По номеру заявки
curl "http://localhost:8000/api/v1/warranty-claims/?claim_number=VSTA-2024-000001"

# Комбинированный фильтр
curl "http://localhost:8000/api/v1/warranty-claims/?status=Принято застройщиком&executor_id=1&limit=5"

📊 Мониторинг и отчетность

Получение статистики по заявкам

# Все заявки исполнителя
curl "http://localhost:8000/api/v1/warranty-claims/?executor_id=1"

# Выполненные заявки за период
curl "http://localhost:8000/api/v1/warranty-claims/?status=Выполнено застройщиком"

Детальная информация о заявке

curl "http://localhost:8000/api/v1/warranty-claims/1"

🚨 Обработка ошибок

Типовые ошибки и их обработка

400 Bad Request - Некорректные данные:

{
  "detail": [
    {
      "loc": ["body", "description"],
      "msg": "ensure this value has at least 10 characters",
      "type": "value_error.any_str.min_length"
    }
  ]
}

404 Not Found - Заявка не найдена:

{
  "detail": "Warranty claim not found"
}

422 Unprocessable Entity - Ошибка валидации:

{
  "detail": "Executor with id 999 not found"
}

🔗 Интеграция с внешними системами

Webhook уведомления (планируется)

В будущих версиях планируется добавление webhook'ов для уведомления о изменении статуса заявок:

{
  "event": "claim_status_changed",
  "claim_id": 1,
  "old_status": "Новая",
  "new_status": "Принято застройщиком",
  "timestamp": "2024-01-15T15:30:00Z"
}

Синхронизация с CRM

Планируется интеграция с популярными CRM системами для автоматической синхронизации заявок и клиентских данных.