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

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

В примерах curl ниже используется продовый базовый URL: https://vsta-orders-hub.ilyushko.ru.

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

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

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

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 Bearer Token.

Роли:

admin — управляет всеми пользователями, заявками и вложениями
user — управляет только своим профилем, своими заявками и вложениями своих заявок

Получение токена:

curl -X POST "https://vsta-orders-hub.ilyushko.ru/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin@example.com&password=secret123"

Ответ:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Дальше токен передается в заголовке:

-H "Authorization: Bearer <access_token>"

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

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

Пользователей создает только администратор:

curl -X POST "https://vsta-orders-hub.ilyushko.ru/api/v1/users/" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Петр",
    "last_name": "Петров",
    "email": "petrov@builder.ru",
    "phone": "+7 (495) 123-45-67",
    "password": "secret12345",
    "role": "user"
  }'

Ответ:

{
  "id": 1,
  "first_name": "Петр",
  "last_name": "Петров",
  "email": "petrov@builder.ru",
  "phone": "+7 (495) 123-45-67",
  "is_active": true,
  "role": "user",
  "created_at": "2024-01-15T10:00:00Z"
}

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

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

curl -X POST "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Протечка воды с потолка на балконе после сильного дождя. Вода капает на пол и мебель.",
    "comment": "Проблема появилась после последнего дождя 10 января. Срочно требует устранения.",
    "location_address": "г. Москва, ул. Примерная, д. 15, корп. 2, кв. 87, балкон",
    "executor_id": 1,
    "applicant": {
      "name": "Сидорова Мария Александровна",
      "phone": "+7 (916) 555-12-34",
      "email": "sidorova@example.com"
    }
  }'

Ответ:

{
  "id": 1,
  "claim_number": "WCL-2026-ABC123",
  "status": "new",
  "owner_user_id": 2,
  "description": "Протечка воды с потолка на балконе...",
  "created_at": "2024-01-15T14:30:00Z"
}

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

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

curl "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/?status=new&limit=10" \
  -H "Authorization: Bearer <user_token>"

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

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

curl -X PATCH "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/1/status" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "accepted_by_builder",
    "comment": "Заявка принята в работу. Мастер выйдет 16.01.2024 с 14:00 до 18:00"
  }'

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

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

curl -X POST "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/1/result" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Устранена протечка кровли. Заменены поврежденные участки гидроизоляции. Проведена контрольная проливка.",
    "completion_date": "2026-04-15T12:00:00Z",
    "attachments": [
      {
        "filename": "result_photo_1.jpg",
        "file_path": "attachments/result_photo_1.jpg",
        "file_size": 2048000,
        "content_type": "image/jpeg"
      }
    ]
  }'

Статус заявки при добавлении результата не меняется — перевод в «Выполнено застройщиком» отдельным запросом PATCH /warranty-claims/{id}/status.

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

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

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

curl -X DELETE "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/1"

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

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

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

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

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

# По исполнителю
curl "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/?executor_id=1"

# По номеру заявки
curl "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/?claim_number=VSTA-2024-000001"

# Комбинированный фильтр
curl "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/?status=Принято застройщиком&executor_id=1&limit=5"

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

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

# Все заявки исполнителя
curl "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/?executor_id=1"

# Выполненные заявки за период
curl "https://vsta-orders-hub.ilyushko.ru/api/v1/warranty-claims/?status=Выполнено застройщиком"

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

curl "https://vsta-orders-hub.ilyushko.ru/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 системами для автоматической синхронизации заявок и клиентских данных.