Руководство по трансферам

Обзор системы трансферов

Система трансферов представляет собой полноценную платформу для управления услугами трансфера между различными локациями. Система поддерживает различные роли пользователей и предоставляет API для публичного использования и административного управления.

Основные компоненты

Маршруты трансферов (transfer_routes) - основные направления поездок
Расписание (transfer_schedules) - конкретные рейсы с датами и временем
Бронирования (transfer_bookings) - заказы клиентов
Провайдеры (transfer_provider_profiles) - компании, предоставляющие услуги
Транспорт (vehicles) - автопарк провайдеров
Водители (drivers) - персонал провайдеров

Роли пользователей

Туристы - поиск и бронирование трансферов
Провайдеры трансферов - управление маршрутами, расписанием и автопарком
Администраторы - модерация и управление всей системой

Для туристов (поиск и бронирование)

Поиск доступных трансферов

Поиск трансферов - Открыть в Swagger

Параметры поиска:

from - место отправления
to - место назначения
date - дата поездки
passengers - количество пассажиров

Пример запроса:

GET /transfers?from=Москва&to=Архыз&date=2024-01-15&passengers=2

Пример ответа:

{
  "data": [
    {
      "id": "uuid",
      "departure_location": "Москва",
      "arrival_location": "Архыз", 
      "duration_minutes": 480,
      "distance_km": 620,
      "vehicle_type": "Минивэн"
    }
  ]
}

Требуемые данные для бронирования:

{
  "schedule_id": "uuid",
  "passengers_count": 2,
  "contact_name": "Иван Иванов",
  "contact_email": "ivan@example.com",
  "contact_phone": "+7-999-123-4567",
  "pickup_location": "Адрес посадки",
  "special_requests": "Особые пожелания"
}

Для провайдеров трансферов

Управление маршрутами

Провайдеры могут создавать и управлять своими маршрутами через административный API:

Мои маршруты - Открыть в Swagger

Создать маршрут - Открыть в Swagger

Создание нового маршрута:

{
  "from_location": "Москва",
  "to_location": "Архыз",
  "vehicle_type": "Минивэн",
  "duration_minutes": 480,
  "base_price": 5000.00,
  "max_passengers": 8,
  "description": "Комфортный трансфер до курорта"
}

Управление расписанием

Мое расписание - Открыть в Swagger

Создать рейс - Открыть в Swagger

Создание рейса:

{
  "route_id": "uuid",
  "date": "2024-01-15",
  "departure_time": "09:00",
  "arrival_time": "17:00",
  "available_seats": 8,
  "price": 5000.00,
  "driver_id": "uuid",
  "vehicle_id": "uuid"
}

Автоматические уведомления

Уведомления для трансферов

При каждом бронировании трансфера система автоматически создает уведомления:

При создании бронирования

Тип: transfer_booking_created
Получатель: Турист
Содержание: Подтверждение создания бронирования трансфера

Мета-данные:

{
  "pickup_location": "Адрес посадки",
  "dropoff_location": "Адрес высадки", 
  "pickup_time": "2024-03-15T09:00:00Z",
  "passengers_count": 2,
  "total_price": 5000
}

Получение уведомлений о трансферах

GET /notifications?object_type=transfer_booking

Автоматические действия при бронировании

Создание бронирования в базе данных
Автоматическая отправка уведомления туристу
Отправка уведомления провайдеру трансфера
Обновление доступности мест в расписании

Управление бронированиями

Мои бронирования - Открыть в Swagger

Создать бронирование - Открыть в Swagger

Отменить бронирование - Открыть в Swagger

Управление личными данными

Мои бронирования

Мои бронирования трансферов - Открыть в Swagger

Поиск трансферов

Поиск трансферов - Открыть в Swagger

Схема процесса бронирования

sequenceDiagram
    participant T as Турист
    participant API as OTA API
    participant DB as База данных
    participant P as Провайдер

    T->>API: Поиск трансферов (GET /transfers)
    API->>DB: Запрос доступных маршрутов
    DB-->>API: Список трансферов
    API-->>T: Результаты поиска

    T->>API: Детали трансфера (GET /transfers/{id})
    API->>DB: Запрос деталей
    DB-->>API: Подробная информация
    API-->>T: Детали трансфера

    T->>API: Создание бронирования (POST /transfer-bookings)
    API->>DB: Проверка доступности мест
    DB-->>API: Подтверждение доступности
    API->>DB: Создание бронирования
    DB-->>API: ID бронирования
    API->>+N: Автоматическое создание уведомления
    N-->>T: Уведомление "transfer_booking_created"
    N-->>P: Уведомление о новом заказе
    API-->>T: Подтверждение бронирования

    Note over T,P: Уведомления отправлены автоматически

Структура данных

TransferRoute (Маршрут)

{
  id: string;
  provider_id: string;
  from_location: string;
  to_location: string;
  vehicle_type: string;
  duration_minutes: number;
  base_price: number;
  max_passengers: number;
  description?: string;
  status: string;
  created_at: datetime;
  updated_at: datetime;
}

TransferSchedule (Расписание)

{
  id: string;
  route_id: string;
  date: date;
  departure_time: time;
  arrival_time: time;
  available_seats: number;
  price: number;
  driver_id?: string;
  vehicle_id?: string;
  created_at: datetime;
  updated_at: datetime;
}

TransferBooking (Бронирование)

{
  id: string;
  schedule_id: string;
  user_id: string;
  passengers_count: number;
  passenger_names: string[];
  contact_phone: string;
  contact_email?: string;
  pickup_location?: string;
  dropoff_location?: string;
  special_requests?: string;
  booking_date: datetime;
  total_price: number;
  status: 'pending' | 'confirmed' | 'cancelled' | 'completed';
  payment_status: 'pending' | 'paid' | 'refunded';
  created_at: datetime;
  updated_at: datetime;
  cancelled_at?: datetime;
}

Связи между таблицами

erDiagram
    transfer_provider_profiles ||--o{ transfer_routes : "предоставляет"
    transfer_routes ||--o{ transfer_schedules : "имеет расписание"
    transfer_schedules ||--o{ transfer_bookings : "может быть забронирован"
    drivers ||--o{ transfer_schedules : "водит"
    vehicles ||--o{ transfer_schedules : "используется в"
    transfer_provider_profiles ||--o{ drivers : "нанимает"
    transfer_provider_profiles ||--o{ vehicles : "владеет"

    transfer_provider_profiles {
        uuid id PK
        string company_name
        string contact_phone
        string contact_email
        string status
    }
    
    transfer_routes {
        uuid id PK
        uuid provider_id FK
        string from_location
        string to_location
        string vehicle_type
        int duration_minutes
        decimal base_price
        int max_passengers
    }
    
    transfer_schedules {
        uuid id PK
        uuid route_id FK
        date date
        time departure_time
        time arrival_time
        int available_seats
        decimal price
        uuid driver_id FK
        uuid vehicle_id FK
    }
    
    transfer_bookings {
        uuid id PK
        uuid schedule_id FK
        uuid user_id
        int passengers_count
        string contact_phone
        decimal total_price
        string status
        string payment_status
    }
    
    drivers {
        uuid id PK
        uuid provider_id FK
        string name
        string phone
        string license_number
        int experience_years
        decimal rating
    }
    
    vehicles {
        uuid id PK
        uuid provider_id FK
        string brand
        string model
        string license_plate
        int seats_count
        string vehicle_type
    }

Аутентификация и авторизация

Публичный API (OTA API)

Требует API ключ для всех запросов
Регистрация пользователей через JWT токены
Создание бронирований только для авторизованных пользователей

Административный API (Hotel API)

JWT аутентификация
Доступ только к собственным данным провайдера
Административные функции для модераторов

Статусы и состояния

Статусы бронирований

pending - Ожидает подтверждения
confirmed - Подтверждено
cancelled - Отменено
completed - Выполнено

Статусы оплаты

pending - Ожидает оплаты
paid - Оплачено
refunded - Возвращено

Статусы маршрутов

active - Активный
inactive - Неактивный
suspended - Приостановлен

Технические детали

Публичный API (Python/FastAPI)

Базовый URL: https://api.arkhyz-club.ru
Документация: https://api.arkhyz-club.ru/docs#/
Назначение: Публичное API для сайтов партнеров и виджетов

Административный API (Python/FastAPI)

Базовый URL: https://stage.arkhyz-club.ru
Документация: https://stage.arkhyz-club.ru/docs#/
Назначение: Управление бронированиями и административные функции

Параметры пагинации

{
  page: number = 1;        // Номер страницы
  limit: number = 10;      // Количество элементов на странице (max: 100)
  total: number;           // Общее количество элементов
  per_page: number;        // Элементов на текущей странице
}

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

{
  "error": {
    "code": "TRANSFER_NOT_FOUND",
    "message": "Трансфер не найден",
    "details": "Transfer with ID xyz not found"
  }
}

Быстрый старт

Получите API ключ в административной панели
Изучите доступные маршруты с помощью GET /transfers/routes
Найдите подходящий трансфер через GET /transfers
Создайте бронирование через POST /transfer-bookings

Поддержка

Email: support@arkhyz-club.ru
Telegram: @ariswebru
Сайт: arkhyz-club.ru

Все методы API доступны в интерактивной документации Swagger. Используйте кнопки выше для быстрого доступа к конкретным операциям.

Обзор системы трансферов​

Основные компоненты​

Роли пользователей​

Для туристов (поиск и бронирование)​

Поиск доступных трансферов​

Просмотр деталей маршрута​

Получение доступных маршрутов​

Создание бронирования​

Для провайдеров трансферов​

Управление маршрутами​

Управление расписанием​

Автоматические уведомления​

Уведомления для трансферов​

При создании бронирования​

Получение уведомлений о трансферах​

Автоматические действия при бронировании​

Управление бронированиями​

Управление личными данными​

Мои бронирования​

Поиск трансферов​

Схема процесса бронирования​

Структура данных​

TransferRoute (Маршрут)​

TransferSchedule (Расписание)​

TransferBooking (Бронирование)​

Связи между таблицами​

Аутентификация и авторизация​

Публичный API (OTA API)​

Административный API (Hotel API)​

Статусы и состояния​

Статусы бронирований​

Статусы оплаты​

Статусы маршрутов​

Технические детали​

Публичный API (Python/FastAPI)​

Административный API (Python/FastAPI)​

Параметры пагинации​

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

Быстрый старт​

Поддержка​