WellShe/docs/api_specification.md

# Описание API и способы взаимодействия с ним

## Промпт для ИИ

Ты — технический документатор API для микросервисной архитектуры приложения женской безопасности. Твоя задача — предоставить четкое, точное и полное описание API для разработчиков клиентского приложения. Основывайся на представленной ниже спецификации API и отвечай на запросы разработчиков по интеграции с бэкендом.

## Общая информация об API

Бэкенд приложения построен на микросервисной архитектуре с использованием FastAPI, что обеспечивает высокую производительность и масштабируемость. Все запросы к API проходят через API Gateway (шлюз), который направляет их в соответствующие микросервисы.

### Базовый URL

```
https://api.womensafety.app/api/v1/
```

В среде разработки:
```
http://localhost:8001/api/v1/
```

### Формат данных

API принимает и отправляет данные в формате JSON. При отправке запроса необходимо указать заголовок:

```
Content-Type: application/json
```

### Аутентификация

API использует JWT (JSON Web Tokens) для аутентификации. После успешной авторизации вы получаете два токена:
- `access_token` — для авторизации запросов (срок действия: 30 минут)
- `refresh_token` — для обновления access_token (срок действия: 7 дней)

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

```
Authorization: Bearer {access_token}
```

## Сервис авторизации (User Service)

### Регистрация нового пользователя

**Эндпоинт:** `POST /auth/register`

**Тело запроса:**
```json
{
  "email": "user@example.com",
  "username": "username",
  "password": "SecurePassword123!",
  "first_name": "Имя",
  "last_name": "Фамилия",
  "phone": "+79991234567"
}
```

**Ответ при успехе (201 Created):**
```json
{
  "status": "success",
  "message": "User registered successfully",
  "data": {
    "user_id": "uuid-string",
    "username": "username",
    "email": "user@example.com"
  }
}
```

**Возможные ошибки:**
- 400 Bad Request: Некорректные данные
- 409 Conflict: Пользователь с таким email или username уже существует

### Авторизация пользователя

**Эндпоинт:** `POST /auth/login`

**Тело запроса (вариант 1):**
```json
{
  "username": "username",
  "password": "SecurePassword123!"
}
```

**Тело запроса (вариант 2):**
```json
{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}
```

**Ответ при успехе (200 OK):**
```json
{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 1800
  }
}
```

**Возможные ошибки:**
- 401 Unauthorized: Неверный логин или пароль
- 403 Forbidden: Аккаунт заблокирован

### Обновление токена

**Эндпоинт:** `POST /auth/refresh`

**Тело запроса:**
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Ответ при успехе (200 OK):**
```json
{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 1800
  }
}
```

**Возможные ошибки:**
- 401 Unauthorized: Недействительный refresh_token

### Выход из системы

**Эндпоинт:** `POST /auth/logout`

**Заголовки:**
```
Authorization: Bearer {access_token}
```

**Ответ при успехе (200 OK):**
```json
{
  "status": "success",
  "message": "Successfully logged out"
}
```

**Возможные ошибки:**
- 401 Unauthorized: Недействительный токен

### Получение профиля пользователя

**Эндпоинт:** `GET /users/me`

**Заголовки:**
```
Authorization: Bearer {access_token}
```

**Ответ при успехе (200 OK):**
```json
{
  "status": "success",
  "data": {
    "user_id": "uuid-string",
    "username": "username",
    "email": "user@example.com",
    "first_name": "Имя",
    "last_name": "Фамилия",
    "phone": "+79991234567",
    "created_at": "2025-10-16T10:30:00Z",
    "is_verified": true
  }
}
```

**Возможные ошибки:**
- 401 Unauthorized: Недействительный токен

## Сервис экстренных оповещений (Emergency Service)

### Создание экстренного оповещения

**Эндпоинт:** `POST /emergency/alert`

**Заголовки:**
```
Authorization: Bearer {access_token}
```

**Тело запроса:**
```json
{
  "location": {
    "latitude": 55.7558,
    "longitude": 37.6173
  },
  "message": "Нуждаюсь в помощи. Преследование.",
  "battery_level": 42,
  "contact_ids": ["uuid1", "uuid2"]
}
```

**Ответ при успехе (201 Created):**
```json
{
  "status": "success",
  "data": {
    "alert_id": "alert-uuid-string",
    "created_at": "2025-10-16T15:30:00Z",
    "status": "active",
    "message": "Экстренное оповещение активировано"
  }
}
```

**Возможные ошибки:**
- 401 Unauthorized: Недействительный токен
- 400 Bad Request: Неверные координаты или другие данные

### Получение статуса экстренного оповещения

**Эндпоинт:** `GET /emergency/alert/{alert_id}`

**Заголовки:**
```
Authorization: Bearer {access_token}
```

**Ответ при успехе (200 OK):**
```json
{
  "status": "success",
  "data": {
    "alert_id": "alert-uuid-string",
    "created_at": "2025-10-16T15:30:00Z",
    "status": "active",
    "location": {
      "latitude": 55.7558,
      "longitude": 37.6173,
      "updated_at": "2025-10-16T15:35:00Z"
    },
    "notified_contacts": [
      {
        "contact_id": "uuid1",
        "status": "notified",
        "notified_at": "2025-10-16T15:31:00Z"
      },
      {
        "contact_id": "uuid2",
        "status": "pending",
        "notified_at": null
      }
    ],
    "emergency_services_notified": true,
    "emergency_services_notified_at": "2025-10-16T15:32:00Z"
  }
}
```

**Возможные ошибки:**
- 401 Unauthorized: Недействительный токен
- 403 Forbidden: Нет доступа к данному оповещению
- 404 Not Found: Оповещение не найдено

### Обновление местоположения при активном оповещении

**Эндпоинт:** `PUT /emergency/alert/{alert_id}/location`

**Заголовки:**
```
Authorization: Bearer {access_token}
```

**Тело запроса:**
```json
{
  "latitude": 55.7560,
  "longitude": 37.6175,
  "accuracy": 10.5,
  "battery_level": 38
}
```

**Ответ при успехе (200 OK):**
```json
{
  "status": "success",
  "message": "Location updated successfully",
  "data": {
    "updated_at": "2025-10-16T15:40:00Z"
  }
}
```

**Возможные ошибки:**
- 401 Unauthorized: Недействительный токен
- 403 Forbidden: Нет доступа к данному оповещению
- 404 Not Found: Оповещение не найдено или не активно

### Отмена экстренного оповещения

**Эндпоинт:** `POST /emergency/alert/{alert_id}/cancel`

**Заголовки:**
```
Authorization: Bearer {access_token}
```

**Тело запроса:**
```json
{
  "reason": "Ложная тревога",
  "details": "Случайно нажала кнопку"
}
```

**Ответ при успехе (200 OK):**
```json
{
  "status": "success",
  "message": "Alert cancelled successfully",
  "data": {
    "alert_id": "alert-uuid-string",
    "cancelled_at": "2025-10-16T15:45:00Z",
    "status": "cancelled"
  }
}
```

**Возможные ошибки:**
- 401 Unauthorized: Недействительный токен
- 403 Forbidden: Нет доступа к данному оповещению
- 404 Not Found: Оповещение не найдено
- 409 Conflict: Оповещение уже отменено

## Рекомендации по работе с API

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

Все ошибки API возвращаются в едином формате:

```json
{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Описание ошибки",
  "details": {
    "field": ["Детальное описание ошибки для конкретного поля"]
  }
}
```

### Управление токенами

1. После получения `access_token` и `refresh_token` сохраните их в безопасном хранилище.
2. Для каждого запроса, требующего авторизацию, добавляйте `access_token` в заголовок.
3. Если API возвращает ошибку 401, попробуйте обновить токен через эндпоинт `/auth/refresh`.
4. Если и это не помогает, перенаправьте пользователя на страницу входа.

### Оптимизация работы с сетью

1. Используйте кэширование для уменьшения количества запросов.
2. Реализуйте механизм повторных попыток для нестабильных соединений.
3. При отправке экстренных оповещений учитывайте возможную нестабильность сети — сохраняйте данные локально до получения подтверждения от сервера.

### Работа с геолокацией

1. Запрашивайте у пользователя разрешение на постоянный доступ к геолокации.
2. Оптимизируйте частоту обновления координат для экономии батареи.
3. При активном экстренном оповещении увеличивайте частоту обновления координат.

## Тестирование API

Для облегчения интеграции с API доступна песочница:

```
https://api-sandbox.womensafety.app/api/v1/
```

Тестовые учетные записи:
- Пользователь: `test_user/Test123!`
- Администратор: `test_admin/Admin123!`

## Работа с реальными устройствами

Для корректной работы с API на реальных устройствах учитывайте:

1. Ограничения режима энергосбережения на некоторых устройствах.
2. Различную точность GPS на разных моделях телефонов.
3. Возможность потери соединения в некоторых зонах.

Реализуйте механизм, который будет накапливать данные локально при отсутствии сети и отправлять их, когда соединение восстановится.

## Безопасность

1. Никогда не храните пароли в открытом виде.
2. Не сохраняйте токены в незащищенном хранилище.
3. Всегда проверяйте SSL-сертификаты при подключении к API.
4. Реализуйте защиту от подбора пароля, ограничивая количество попыток входа.

## Поддержка

При возникновении проблем с интеграцией можно обратиться:
- Email: api-support@womensafety.app
- Документация: https://docs.womensafety.app
- Статус сервисов: https://status.womensafety.app