Перейти к основному содержимому
Войти

API для туроператоров

Методы API, доступные для роли "touroperator".

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

Authorization: Bearer <your-token>

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

Создать тур​

POST /tours

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

{
  "title": "Поход к Софийским озерам",
  "description": "Незабываемое путешествие к горным озерам",
  "duration_days": 3,
  "difficulty_level": "средний",
  "max_participants": 15,
  "price_per_person": 12000,
  "included_services": ["гид", "питание", "транспорт"],
  "meeting_point": "База отдыха Архыз",
  "season": ["лето", "осень"]
}

Обновить тур​

PUT /tours/{id}

Получить мои туры​

GET /tours/my

Удалить тур​

DELETE /tours/{id}

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

Просмотр бронирований​

GET /tour-bookings?status=all&from=2024-01-01&to=2024-12-31&partner_id=uuid

Параметры запроса:

  • status - статус бронирования (pending, confirmed, cancelled, completed)
  • from, to - период дат
  • partner_id - фильтр по партнеру
  • tour_id - фильтр по туру
  • payment_status - статус оплаты

Ответ:

{
  "bookings": [
    {
      "id": "uuid",
      "tour_id": 123,
      "tour_name": "Поход к Софийским озерам",
      "contact_name": "Петров Петр",
      "contact_phone": "+7-900-123-45-67",
      "contact_email": "petrov@mail.ru",
      "participants_count": 3,
      "total_price": 36000.00,
      "status": "confirmed",
      "payment_status": "paid",
      "booking_date": "2024-07-01T10:30:00Z",
      "tour_date": "2024-07-15T09:00:00Z",
      "partner": {
        "id": "uuid",
        "name": "ТурАгентство Горизонт",
        "commission": 5400.00
      }
    }
  ],
  "total_count": 156,
  "total_revenue": 1875000.00
}

Подтвердить бронирование​

PUT /tour-bookings/{id}/confirm

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

{
  "confirmation_notes": "Все документы проверены, место подтверждено",
  "send_notification": true,
  "assign_guide": "uuid"
}

Отменить бронирование​

PUT /tour-bookings/{id}/cancel

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

{
  "cancellation_reason": "Отмена по просьбе клиента",
  "refund_amount": 30000.00,
  "refund_reason": "Полный возврат согласно политике отмены"
}

Обновить статус оплаты​

PUT /tour-bookings/{id}/payment-status

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

{
  "payment_status": "paid",
  "payment_method": "bank_card",
  "payment_date": "2024-07-02T14:30:00Z",
  "payment_reference": "TXN_123456789",
  "notes": "Оплата получена через эквайринг"
}

Массовые операции с бронированиями​

POST /tour-bookings/bulk-action

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

{
  "action": "send_reminder",
  "booking_ids": ["uuid1", "uuid2", "uuid3"],
  "parameters": {
    "message_template": "tour_reminder_24h",
    "send_sms": true,
    "send_email": true
  }
}

Перенос бронирования​

PUT /tour-bookings/{id}/transfer

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

{
  "new_tour_date": "2024-07-22T09:00:00Z",
  "reason": "Перенос по погодным условиям",
  "notify_customer": true,
  "price_adjustment": 0
}

История изменений бронирования​

GET /tour-bookings/{id}/history

Ответ:

{
  "booking_id": "uuid",
  "changes": [
    {
      "timestamp": "2024-07-01T10:30:00Z",
      "action": "created",
      "user": "Система",
      "details": "Бронирование создано"
    },
    {
      "timestamp": "2024-07-01T11:15:00Z",
      "action": "confirmed",
      "user": "Иванов И.И.",
      "details": "Бронирование подтверждено менеджером"
    }
  ]
}

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

Получить расписание​

GET /tour-schedule?tour_id=123&from=2024-07-01&to=2024-07-31

Параметры:

  • tour_id - ID тура (опционально)
  • from, to - период дат
  • status - статус расписания (available, full, cancelled)
  • guide_id - фильтр по гиду

Ответ:

{
  "schedules": [
    {
      "id": "uuid",
      "tour_id": 123,
      "tour_name": "Поход к Софийским озерам",
      "date": "2024-07-15",
      "time_start": "09:00",
      "time_end": "18:00",
      "max_participants": 15,
      "available_spots": 10,
      "booked_spots": 5,
      "status": "available",
      "guide": {
        "id": "uuid",
        "name": "Петров Иван",
        "phone": "+7-900-123-45-67"
      },
      "meeting_point": "База отдыха Архыз",
      "price_override": 13000.00
    }
  ]
}

Создать расписание тура​

POST /tours/{id}/schedule

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

{
  "date": "2024-07-15",
  "time_start": "09:00",
  "time_end": "18:00",
  "max_participants": 15,
  "available_spots": 15,
  "guide_id": "uuid",
  "meeting_point": "База отдыха Архыз",
  "special_notes": "Погода благоприятная",
  "price_override": 13000.00
}

Обновить расписание​

PUT /tour-schedule/{id}

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

{
  "available_spots": 12,
  "special_notes": "Обновлено: требуется теплая одежда",
  "status": "available"
}

Копировать расписание​

POST /tour-schedule/{id}/copy

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

{
  "target_dates": ["2024-07-22", "2024-07-29", "2024-08-05"],
  "copy_guide": true,
  "copy_price": true,
  "copy_notes": false
}

Массовое создание расписания​

POST /tour-schedule/bulk-create

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

{
  "tour_id": 123,
  "date_range": {
    "start": "2024-07-01",
    "end": "2024-08-31"
  },
  "repeat_pattern": {
    "type": "weekly",
    "days": ["saturday", "sunday"],
    "exclude_dates": ["2024-07-15", "2024-08-12"]
  },
  "default_settings": {
    "time_start": "09:00",
    "time_end": "18:00",
    "max_participants": 15,
    "guide_id": "uuid"
  }
}

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

POST /tour-schedule/{id}/notifications

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

{
  "type": "weather_update",
  "recipients": ["participants", "guide", "operator"],
  "message": "Прогноз погоды изменился. Рекомендуем взять дождевики.",
  "send_sms": true,
  "send_email": true
}

Загрузка гидов​

GET /guides/workload?from=2024-07-01&to=2024-07-31

Ответ:

{
  "guides": [
    {
      "id": "uuid",
      "name": "Петров Иван",
      "total_tours": 12,
      "total_hours": 96,
      "utilization_rate": 75.5,
      "upcoming_tours": [
        {
          "date": "2024-07-15",
          "tour_name": "Поход к озерам",
          "participants": 8
        }
      ]
    }
  ]
}

Партнерские программы​

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

Получить список партнеров​

GET /tour-partners

Ответ:

[
  {
    "id": "uuid",
    "name": "ТурАгентство Горизонт",
    "contact_person": "Иванов Иван",
    "email": "ivan@horizont.ru",
    "phone": "+7-900-123-45-67",
    "commission_rate": 15.00,
    "status": "active",
    "total_bookings": 45,
    "total_commission": 67500.00
  }
]

Создать партнера​

POST /tour-partners

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

{
  "name": "ТурАгентство Горизонт",
  "contact_person": "Иванов Иван",
  "email": "ivan@horizont.ru",
  "phone": "+7-900-123-45-67",
  "commission_rate": 15.00,
  "contract_number": "ДОГ-2024-001",
  "website": "https://horizont.ru"
}

Обновить партнера​

PUT /tour-partners/{id}

Получить статистику партнера​

GET /tour-partners/{id}/stats

Ответ:

{
  "partner_id": "uuid",
  "total_clicks": 1250,
  "total_bookings": 45,
  "conversion_rate": 3.6,
  "total_commission": 67500.00,
  "last_30_days": {
    "clicks": 180,
    "bookings": 8,
    "commission": 12000.00
  }
}

Партнерские ссылки и трекинг​

Создать партнерскую ссылку​

POST /tour-partners/{id}/links

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

{
  "tour_id": 123,
  "campaign_name": "Летняя акция 2024",
  "utm_source": "partner_site",
  "utm_medium": "banner",
  "utm_campaign": "summer_tours"
}

Ответ:

{
  "link_id": "uuid",
  "partner_code": "HORIZONT_001",
  "tracking_url": "https://tours.com/tour/123?ref=HORIZONT_001&utm_source=partner_site",
  "short_url": "https://tours.com/p/abc123",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Получить код трекинга​

GET /tour-partners/{id}/tracking-code

Ответ:

{
  "partner_id": "uuid",
  "tracking_code": "<!-- Код трекинга -->...",
  "installation_guide": "https://docs.tours.com/tracking-setup"
}

Статистика переходов​

GET /tour-partners/{id}/clicks?from=2024-01-01&to=2024-12-31

Ответ:

{
  "total_clicks": 1250,
  "daily_stats": [
    {
      "date": "2024-07-01",
      "clicks": 15,
      "unique_visitors": 12,
      "conversions": 2
    }
  ],
  "top_sources": [
    {
      "source": "partner_website",
      "clicks": 800,
      "conversions": 25
    }
  ]
}

Комиссионные программы​

Настроить комиссию партнеру​

PUT /tour-partners/{id}/commission

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

{
  "type": "percentage",
  "value": 15.00,
  "min_booking_amount": 5000,
  "max_commission": 10000,
  "special_tours": {
    "tour_ids": [123, 456],
    "commission_rate": 20.00
  }
}

Расчет комиссии​

POST /tour-partners/calculate-commission

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

{
  "partner_id": "uuid",
  "booking_amount": 15000,
  "tour_id": 123,
  "participants_count": 2
}

Ответ:

{
  "base_commission": 2250.00,
  "bonus_commission": 0,
  "total_commission": 2250.00,
  "commission_rate": 15.00,
  "calculation_details": "15% от суммы бронирования 15,000 ₽"
}

Отчет по выплатам​

GET /tour-partners/{id}/payouts?period=2024-07

Ответ:

{
  "period": "2024-07",
  "total_earned": 25000.00,
  "total_paid": 20000.00,
  "pending_payout": 5000.00,
  "bookings": [
    {
      "booking_id": "uuid",
      "tour_name": "Поход к озерам",
      "booking_date": "2024-07-15",
      "amount": 15000.00,
      "commission": 2250.00,
      "status": "confirmed"
    }
  ]
}

Мультимедиа материалы для партнеров​

Получить маркетинговые материалы​

GET /tour-partners/{id}/marketing-materials

Ответ:

{
  "banners": [
    {
      "size": "300x250",
      "url": "https://cdn.tours.com/banners/summer_300x250.jpg",
      "html_code": "<a href='tracking_url'><img src='banner_url'></a>"
    }
  ],
  "product_feeds": {
    "xml": "https://api.tours.com/feeds/partner_123.xml",
    "json": "https://api.tours.com/feeds/partner_123.json"
  },
  "logos": [
    {
      "format": "svg",
      "url": "https://cdn.tours.com/logos/company_logo.svg"
    }
  ]
}

Аналитика туроператора​

Дашборд туроператора​

GET /tour-operators/dashboard

Ответ:

{
  "kpis": {
    "total_tours": 45,
    "active_tours": 38,
    "total_bookings": 1250,
    "confirmed_bookings": 1180,
    "total_revenue": 18750000.00,
    "partners_count": 25,
    "conversion_rate": 15.8,
    "avg_tour_price": 15000.00
  },
  "recent_bookings": [
    {
      "id": "uuid",
      "tour_name": "Поход к озерам",
      "customer": "Петров И.И.",
      "amount": 15000.00,
      "status": "confirmed",
      "created_at": "2024-07-14T10:30:00Z"
    }
  ],
  "revenue_chart": {
    "labels": ["Янв", "Фев", "Мар", "Апр", "Май", "Июн"],
    "data": [850000, 920000, 1200000, 1350000, 1800000, 2100000]
  }
}

Анализ рентабельности​

GET /analytics/profit-margin?period=2024-07&tour_id=123

Ответ:

{
  "period": "2024-07",
  "tours_analyzed": 12,
  "total_revenue": 450000.00,
  "total_costs": 320000.00,
  "profit_margin": 28.9,
  "cost_breakdown": {
    "guide_fees": 120000.00,
    "transport": 80000.00,
    "accommodation": 70000.00,
    "equipment": 30000.00,
    "partner_commissions": 20000.00
  },
  "most_profitable_tours": [
    {
      "tour_id": 123,
      "name": "Поход к озерам",
      "profit_margin": 35.2,
      "revenue": 180000.00
    }
  ]
}

Популярные туры​

GET /analytics/popular-tours?period=last_6_months&limit=10

Ответ:

{
  "period": "last_6_months",
  "tours": [
    {
      "tour_id": 123,
      "name": "Поход к Софийским озерам",
      "bookings_count": 85,
      "revenue": 1275000.00,
      "rating": 4.8,
      "trend": "up"
    }
  ]
}

Сезонная аналитика​

GET /analytics/seasonal?year=2024

Ответ:

{
  "year": 2024,
  "seasons": {
    "spring": {
      "bookings": 120,
      "revenue": 1800000.00,
      "popular_tours": ["Весенние походы", "Цветение рододендронов"]
    },
    "summer": {
      "bookings": 450,
      "revenue": 6750000.00,
      "popular_tours": ["Поход к озерам", "Альпинизм для начинающих"]
    }
  },
  "peak_months": ["июль", "август"],
  "low_season_recommendations": ["Зимние туры на лыжах", "Новогодние программы"]
}

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

Добавить гида​

POST /guides

Назначить гида на тур​

PUT /tours/{id}/assign-guide

Уведомления​

Получить уведомления​

GET /notifications

Отметить уведомление как прочитанное​

PUT /notifications/{id}/read

Профиль​

Получить профиль​

GET /auth/me

Обновить профиль туроператора​

PUT /touroperator-profile

Коды ответов​

  • 200 - Успешно
  • 201 - Создано
  • 400 - Неверный запрос
  • 401 - Не авторизован
  • 403 - Доступ запрещен
  • 404 - Не найдено
  • 500 - Ошибка сервера

Дополнительные методы​

Отчеты и экспорт​

Экспорт данных​

GET /export/bookings?format=excel&from=2024-01-01&to=2024-12-31

Экспорт расписания​

GET /export/schedule?format=pdf&tour_id=123&month=2024-07

Интеграции​

Webhook уведомления​

POST /webhooks/configure

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

{
  "url": "https://your-site.com/webhook",
  "events": ["booking.created", "booking.confirmed", "payment.received"],
  "secret": "your_webhook_secret"
}

Синхронизация с календарем​

GET /calendar/ical?guide_id=uuid&token=access_token

API для встраивания​

Виджет бронирования​

GET /embed/booking-widget/{tour_id}?theme=light&lang=ru

Календар доступности​

GET /embed/availability-calendar/{tour_id}?theme=dark&size=compact

Управление договорами с партнерами​

Создать договор​

POST /partners/contracts

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

{
  "partner_id": "uuid",
  "contract_number": "ДОГ-2024-015",
  "start_date": "2024-07-01",
  "end_date": "2024-12-31",
  "commission_rate": 15.00,
  "terms": {
    "payment_terms": "30 дней",
    "cancellation_policy": "За 48 часов",
    "minimum_bookings": 10
  },
  "document_url": "https://docs.com/contract_123.pdf"
}

Получить договоры​

GET /partners/contracts?status=active&partner_id=uuid

Интеграция с системами бронирования​

Подключить внешнюю систему​

POST /integrations/booking-systems

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

{
  "system_type": "booking_com",
  "api_credentials": {
    "hotel_id": "12345",
    "api_key": "encrypted_key",
    "secret": "encrypted_secret"
  },
  "sync_settings": {
    "auto_sync": true,
    "sync_interval": "hourly",
    "price_sync": true,
    "availability_sync": true
  }
}

Мобильное приложение для гидов​

Статус гидов в реальном времени​

GET /mobile-app/guides-status

Ответ:

{
  "guides": [
    {
      "guide_id": "uuid",
      "name": "Петров И.И.",
      "status": "on_tour",
      "current_location": {
        "lat": 43.5847,
        "lng": 41.2635,
        "location_name": "Софийские озера"
      },
      "tour_progress": {
        "tour_id": 123,
        "tour_name": "Поход к озерам",
        "start_time": "09:00",
        "current_checkpoint": "Озеро №2",
        "participants_count": 8,
        "next_checkpoint": "Обед у водопада"
      },
      "last_update": "2024-07-14T14:30:00Z"
    }
  ]
}