Trips & Bookings API
Trip management and booking operations endpoints
1. Purpose
This document defines the Trips and Bookings API endpoints for:
- B2C Web & Mobile (trip browsing, booking creation)
- Provider Portal (trip management)
- Admin Panel (booking oversight)
All endpoints follow the conventions in api-principles-and-versioning.md.
3. Trips API
3.1 List Trips (Public)
/api/v1/tripsAuth: Not required (public endpoint)
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| type | string | Filter by trip type: UMRAH / TOURISM |
| status | string | Default: ACTIVE only (B2C) |
| page | integer | Page number (default: 1) |
| per_page | integer | Items per page (default: 20, max: 100) |
| sort | string | Sort field (e.g., -created_at, price) |
3.2 Get Trip Details (Public)
/api/v1/trips/{id}Auth: Not required (public endpoint)
Returns full trip details including hotel, bus, rest stops, itinerary, and images.
3.3 Create Trip (Provider)
/api/v1/provider/tripsAuth: Bearer token required
Roles: PROVIDER_ADMIN, PROVIDER_STAFF
Validation Rules
- departure_date must be < return_date
- days_count and nights_count must be > 0
- max_capacity must be > 0
- hotel_id must reference an ACTIVE hotel owned by the same provider
- bus_id must reference an ACTIVE bus (not UNDER_MAINTENANCE) owned by the same provider
3.4 Update Trip (Provider)
/api/v1/provider/trips/{id}Auth: Bearer token required
Roles: PROVIDER_ADMIN, PROVIDER_STAFF
Restrictions
- Cannot reduce max_capacity below current bookings count
- Cannot change type if bookings exist
- Cannot assign a bus with status UNDER_MAINTENANCE
3.5 Delete Trip (Provider)
/api/v1/provider/trips/{id}Auth: Bearer token required
Roles: PROVIDER_ADMIN
Behavior
- If no bookings exist: hard delete allowed
- If bookings exist: status changes to CANCELLED, trip hidden from B2C
3.6 Activate/Deactivate Trip (Provider)
POST /api/v1/provider/trips/{id}/activatePOST /api/v1/provider/trips/{id}/deactivateAuth: Bearer token required
Roles: PROVIDER_ADMIN, PROVIDER_STAFF
Activation Requirements
- Hotel selected (ACTIVE)
- Bus selected (ACTIVE)
- At least one image
- Valid dates (future)
- Valid capacity (> 0)
4. Bookings API
4.1 Create Booking (Customer)
/api/v1/bookingsAuth: Bearer token required
Roles: CUSTOMER / END_USER
Booking status is PENDING until payment is completed. See payments-and-financials-api.md for payment flow.
4.2 Get My Bookings (Customer)
/api/v1/bookings/myAuth: Bearer token required
Roles: CUSTOMER / END_USER
| Parameter | Type | Description |
|---|---|---|
| status | string | Filter: CONFIRMED, PENDING, CANCELLED |
| upcoming | boolean | If true, return only future trips |
| completed | boolean | If true, return only past trips |
4.3 Get Booking Details (Customer)
/api/v1/bookings/{id}Auth: Bearer token required
Roles: CUSTOMER / END_USER
Additional: user_id must match booking.user_id
4.4 Cancel Booking (Customer)
/api/v1/bookings/{id}/cancelAuth: Bearer token required
Roles: CUSTOMER / END_USER
Additional: user_id must match booking.user_id
Pre-conditions
- Booking status = CONFIRMED
- Trip departure_date > today
Refund Policy
| Time Before Trip | Refund % |
|---|---|
| Before 30 days | 90% |
| Before 15 days | 70% |
| Before 7 days | 50% |
| Less than 7 days | 0% |
4.5 List Bookings (Admin)
/api/v1/admin/bookingsAuth: Bearer token required
Roles: ADMIN, SUPER_ADMIN, SUPPORT_AGENT
| Parameter | Type | Description |
|---|---|---|
| search | string | Search by booking reference, customer name, phone |
| status | string | Filter by status |
| trip_id | integer | Filter by trip |
| provider_id | integer | Filter by provider |
| from_date | date | Filter from date |
| to_date | date | Filter to date |
4.6 Get Booking Details (Admin)
/api/v1/admin/bookings/{id}Auth: Bearer token required
Roles: ADMIN, SUPER_ADMIN, SUPPORT_AGENT
Full booking details including all passengers and payment info
4.7 Update Booking Status (Admin)
/api/v1/admin/bookings/{id}/statusAuth: Bearer token required
Roles: ADMIN, SUPER_ADMIN
4.8 List Bookings (Provider)
/api/v1/provider/bookingsAuth: Bearer token required
Roles: PROVIDER_ADMIN, PROVIDER_STAFF
Results are scoped to bookings for trips owned by the authenticated provider.
5. Error Cases
5.1 Trip Errors
| Error Code | HTTP | Description |
|---|---|---|
| TRIP_NOT_FOUND | 404 | Trip does not exist |
| TRIP_NOT_AVAILABLE | 400 | Trip is INACTIVE or CANCELLED |
| TRIP_SOLD_OUT | 409 | Trip has reached max capacity |
| TRIP_DATE_PASSED | 400 | Trip departure date has passed |
5.2 Booking Errors
| Error Code | HTTP | Description |
|---|---|---|
| BOOKING_NOT_FOUND | 404 | Booking does not exist |
| BOOKING_ALREADY_CANCELLED | 400 | Booking is already cancelled |
| BOOKING_CANNOT_CANCEL | 400 | Cancellation not allowed (trip started) |
| BOOKING_ACCESS_DENIED | 403 | User does not own this booking |
| DUPLICATE_PASSENGER_ID | 422 | Same national_id repeated |
6. Status Enums
6.1 Trip Status
| Enum Value | Arabic UI | Description |
|---|---|---|
| ACTIVE | نشطة | Visible and bookable |
| INACTIVE | غير نشطة | Hidden from B2C |
| CANCELLED | ملغاه | Not bookable |
| COMPLETED | منتهية | End date passed (derived) |
6.2 Booking Status
| Enum Value | Arabic UI | Description |
|---|---|---|
| PENDING | قيد التنفيذ | Initial state, awaiting payment |
| CONFIRMED | مؤكدة | Payment completed |
| CANCELLED | ملغاه | Booking cancelled |
| COMPLETED | مكتملة | Trip finished (derived) |
| UPCOMING | قادمة | Trip in future (derived) |
7. Cross-References
Related Entities:
Trip, TripItineraryDay, Booking, BookingPassenger, User, Provider, Hotel, Bus, RestStop, PaymentTransaction
Related Screens:
الرحلات, تفاصيل الرحلة, مسار الحجز, حجوزاتي, إدارة الرحلات, إدارة الحجوزات
Related APIs:
payments-and-financials-api.md, providers-and-resources-api.md, auth-and-users-api.md
Related Business Rules:
Trip lifecycle, Booking lifecycle, Refund policy
Related Roles:
CUSTOMER, PROVIDER_ADMIN, PROVIDER_STAFF, ADMIN, SUPER_ADMIN, SUPPORT_AGENT