{ "version": "1.0", "modules": [ { "name": "User Management", "prefix": "/users", "endpoints": [ { "method": "POST", "path": "/register", "summary": "Register New User", "description": "Creates a new user account with email validation and password hashing. Returns 409 if the email already exists. Password must be at least 8 characters with uppercase, lowercase, and number.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "phone_number", "type": "str", "required": false }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "GUEST", "CUSTOMER", "ADMIN" ] }, { "name": "password", "type": "str", "required": false } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone_number", "type": "str", "required": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "POST", "path": "/login", "summary": "User Login", "description": "Authenticates user credentials and returns a JWT access token valid for 30 minutes. Returns 400 if credentials are invalid or account is inactive.", "request_body": { "schema_name": "UserLogin", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "password", "type": "str", "required": true } ] }, "response": { "schema_name": "UserLoginResponse", "fields": [ { "name": "access_token", "type": "str", "required": true }, { "name": "token_type", "type": "str", "required": true }, { "name": "user", "type": "UserResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone_number", "type": "str", "required": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{id}/profile", "summary": "Get User Profile", "description": "Retrieves the profile information for a specific user by ID. Returns 404 if the user does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "UserProfileResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone_number", "type": "str", "required": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}/profile", "summary": "Update User Profile", "description": "Updates user profile information including email, name, phone number, and password. Returns 404 if user not found, 409 if new email already exists. Only provided fields are updated.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "UserUpdate", "fields": [ { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "phone_number", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "nullable": true, "enum_values": [ "GUEST", "CUSTOMER", "ADMIN" ] }, { "name": "is_active", "type": "bool", "required": false, "nullable": true }, { "name": "password", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone_number", "type": "str", "required": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Users", "description": "Returns a paginated list of users. Supports optional filtering by role and active status. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "role", "type": "UserRole", "required": false }, { "name": "is_active", "type": "bool", "required": false } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone_number", "type": "str", "required": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get User By ID", "description": "Retrieves detailed information for a specific user by ID. Returns 404 if the user does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone_number", "type": "str", "required": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete User", "description": "Deletes a user account and all associated data including reservations, bookings, payments, and cancellations. Returns 404 if user not found.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Routes", "prefix": "/routes", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Route", "description": "Creates a new bus route between origin and destination cities. Returns 409 if a route with the same origin and destination already exists. Validates that distance and duration are positive numbers.", "request_body": { "schema_name": "RouteCreate", "fields": [ { "name": "origin_city", "type": "str", "required": true }, { "name": "destination_city", "type": "str", "required": true }, { "name": "distance_km", "type": "float", "required": true }, { "name": "estimated_duration_minutes", "type": "int", "required": true }, { "name": "is_active", "type": "bool", "required": true } ] }, "response": { "schema_name": "RouteResponse", "fields": [ { "name": "origin_city", "type": "str", "required": true }, { "name": "destination_city", "type": "str", "required": true }, { "name": "distance_km", "type": "float", "required": true }, { "name": "estimated_duration_minutes", "type": "int", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Routes", "description": "Returns a paginated list of bus routes. Supports optional filtering by origin city, destination city, and active status. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "origin_city", "type": "str", "required": false }, { "name": "destination_city", "type": "str", "required": false }, { "name": "is_active", "type": "bool", "required": false } ], "response": { "schema_name": "RouteResponse", "fields": [ { "name": "origin_city", "type": "str", "required": true }, { "name": "destination_city", "type": "str", "required": true }, { "name": "distance_km", "type": "float", "required": true }, { "name": "estimated_duration_minutes", "type": "int", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{route_id}", "summary": "Get Route Details", "description": "Returns detailed information for a specific route by ID. Returns 404 if the route does not exist.", "path_params": [ { "name": "route_id", "type": "str" } ], "response": { "schema_name": "RouteResponse", "fields": [ { "name": "origin_city", "type": "str", "required": true }, { "name": "destination_city", "type": "str", "required": true }, { "name": "distance_km", "type": "float", "required": true }, { "name": "estimated_duration_minutes", "type": "int", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{route_id}", "summary": "Update Route", "description": "Updates an existing route. Validates that the new origin-destination combination does not conflict with another route. Returns 404 if the route does not exist, 409 if the updated cities conflict with an existing route.", "path_params": [ { "name": "route_id", "type": "str" } ], "request_body": { "schema_name": "RouteUpdate", "fields": [ { "name": "origin_city", "type": "str", "required": false, "nullable": true }, { "name": "destination_city", "type": "str", "required": false, "nullable": true }, { "name": "distance_km", "type": "float", "required": false, "nullable": true }, { "name": "estimated_duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "RouteResponse", "fields": [ { "name": "origin_city", "type": "str", "required": true }, { "name": "destination_city", "type": "str", "required": true }, { "name": "distance_km", "type": "float", "required": true }, { "name": "estimated_duration_minutes", "type": "int", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{route_id}", "summary": "Delete Route", "description": "Deletes a route by ID. Returns 404 if the route does not exist. Note that deleting a route may fail if it is referenced by existing schedules.", "path_params": [ { "name": "route_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Bus Management", "prefix": "/buses", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Bus", "description": "Creates a new bus record with seat configuration and amenities. Returns 409 if a bus with the same bus number already exists. Validates that total seats is positive and seat layout configuration is provided.", "request_body": { "schema_name": "BusCreate", "fields": [ { "name": "bus_number", "type": "str", "required": false }, { "name": "bus_type", "type": "BusType", "required": true, "enum_values": [ "STANDARD", "DELUXE", "SLEEPER", "SEMI_SLEEPER" ] }, { "name": "total_seats", "type": "int", "required": false }, { "name": "seat_layout_config", "type": "Dict[str, Any]", "required": true }, { "name": "amenities", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "BusResponse", "fields": [ { "name": "bus_number", "type": "str", "required": false }, { "name": "bus_type", "type": "BusType", "required": true, "enum_values": [ "STANDARD", "DELUXE", "SLEEPER", "SEMI_SLEEPER" ] }, { "name": "total_seats", "type": "int", "required": false }, { "name": "seat_layout_config", "type": "Dict[str, Any]", "required": true }, { "name": "amenities", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Buses", "description": "Returns a paginated list of buses. Supports optional filtering by bus type and active status. Results are ordered by creation date in descending order.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "bus_type", "type": "BusType", "required": false }, { "name": "is_active", "type": "bool", "required": false } ], "response": { "schema_name": "BusResponse", "fields": [ { "name": "bus_number", "type": "str", "required": false }, { "name": "bus_type", "type": "BusType", "required": true, "enum_values": [ "STANDARD", "DELUXE", "SLEEPER", "SEMI_SLEEPER" ] }, { "name": "total_seats", "type": "int", "required": false }, { "name": "seat_layout_config", "type": "Dict[str, Any]", "required": true }, { "name": "amenities", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get Bus Details", "description": "Returns detailed information for a specific bus by ID. Returns 404 if the bus does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "BusResponse", "fields": [ { "name": "bus_number", "type": "str", "required": false }, { "name": "bus_type", "type": "BusType", "required": true, "enum_values": [ "STANDARD", "DELUXE", "SLEEPER", "SEMI_SLEEPER" ] }, { "name": "total_seats", "type": "int", "required": false }, { "name": "seat_layout_config", "type": "Dict[str, Any]", "required": true }, { "name": "amenities", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Bus", "description": "Updates an existing bus record. All fields are optional. Returns 404 if the bus does not exist. Returns 409 if updating bus number to one that already exists for another bus.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "BusUpdate", "fields": [ { "name": "bus_number", "type": "str", "required": false, "nullable": true }, { "name": "bus_type", "type": "BusType", "required": false, "nullable": true, "enum_values": [ "STANDARD", "DELUXE", "SLEEPER", "SEMI_SLEEPER" ] }, { "name": "total_seats", "type": "int", "required": false, "nullable": true }, { "name": "seat_layout_config", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "amenities", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "BusResponse", "fields": [ { "name": "bus_number", "type": "str", "required": false }, { "name": "bus_type", "type": "BusType", "required": true, "enum_values": [ "STANDARD", "DELUXE", "SLEEPER", "SEMI_SLEEPER" ] }, { "name": "total_seats", "type": "int", "required": false }, { "name": "seat_layout_config", "type": "Dict[str, Any]", "required": true }, { "name": "amenities", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete Bus", "description": "Deletes a bus record by ID. Returns 404 if the bus does not exist. Note that this may fail if the bus is referenced by existing schedules due to foreign key constraints.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Schedule Management", "prefix": "/schedules", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Bus Schedule", "description": "Creates a new bus schedule for a specific route and bus. Validates that the bus and route exist and are active, departure time is in the future, and arrival time is after departure time. Returns 404 if bus or route not found, 400 if validation fails.", "request_body": { "schema_name": "ScheduleCreate", "fields": [ { "name": "bus_id", "type": "str", "required": true }, { "name": "route_id", "type": "str", "required": true }, { "name": "departure_datetime", "type": "datetime", "required": true }, { "name": "arrival_datetime", "type": "datetime", "required": true }, { "name": "base_price", "type": "float", "required": true }, { "name": "available_seats", "type": "int", "required": true }, { "name": "status", "type": "ScheduleStatus", "required": true, "enum_values": [ "SCHEDULED", "IN_TRANSIT", "COMPLETED", "CANCELLED" ] } ] }, "response": { "schema_name": "ScheduleResponse", "fields": [ { "name": "bus_id", "type": "str", "required": true }, { "name": "route_id", "type": "str", "required": true }, { "name": "departure_datetime", "type": "datetime", "required": true }, { "name": "arrival_datetime", "type": "datetime", "required": true }, { "name": "base_price", "type": "float", "required": true }, { "name": "available_seats", "type": "int", "required": true }, { "name": "status", "type": "ScheduleStatus", "required": true, "enum_values": [ "SCHEDULED", "IN_TRANSIT", "COMPLETED", "CANCELLED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{schedule_id}", "summary": "Get Schedule By ID", "description": "Retrieves a single schedule by its unique identifier. Returns 404 if the schedule does not exist.", "path_params": [ { "name": "schedule_id", "type": "str" } ], "response": { "schema_name": "ScheduleResponse", "fields": [ { "name": "bus_id", "type": "str", "required": true }, { "name": "route_id", "type": "str", "required": true }, { "name": "departure_datetime", "type": "datetime", "required": true }, { "name": "arrival_datetime", "type": "datetime", "required": true }, { "name": "base_price", "type": "float", "required": true }, { "name": "available_seats", "type": "int", "required": true }, { "name": "status", "type": "ScheduleStatus", "required": true, "enum_values": [ "SCHEDULED", "IN_TRANSIT", "COMPLETED", "CANCELLED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Schedules", "description": "Returns a paginated list of schedules. Supports optional filtering by route_id and status. Results are ordered by departure datetime in descending order.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "route_id", "type": "str", "required": false }, { "name": "status", "type": "ScheduleStatus", "required": false } ], "response": { "schema_name": "ScheduleResponse", "fields": [ { "name": "bus_id", "type": "str", "required": true }, { "name": "route_id", "type": "str", "required": true }, { "name": "departure_datetime", "type": "datetime", "required": true }, { "name": "arrival_datetime", "type": "datetime", "required": true }, { "name": "base_price", "type": "float", "required": true }, { "name": "available_seats", "type": "int", "required": true }, { "name": "status", "type": "ScheduleStatus", "required": true, "enum_values": [ "SCHEDULED", "IN_TRANSIT", "COMPLETED", "CANCELLED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{schedule_id}", "summary": "Update Schedule", "description": "Updates an existing schedule. Validates that any new bus or route references exist and are active, and that arrival time remains after departure time. Returns 404 if schedule, bus, or route not found, 400 if validation fails.", "path_params": [ { "name": "schedule_id", "type": "str" } ], "request_body": { "schema_name": "ScheduleUpdate", "fields": [ { "name": "bus_id", "type": "str", "required": false, "nullable": true }, { "name": "route_id", "type": "str", "required": false, "nullable": true }, { "name": "departure_datetime", "type": "datetime", "required": false, "nullable": true }, { "name": "arrival_datetime", "type": "datetime", "required": false, "nullable": true }, { "name": "base_price", "type": "float", "required": false, "nullable": true }, { "name": "available_seats", "type": "int", "required": false, "nullable": true }, { "name": "status", "type": "ScheduleStatus", "required": false, "nullable": true, "enum_values": [ "SCHEDULED", "IN_TRANSIT", "COMPLETED", "CANCELLED" ] } ] }, "response": { "schema_name": "ScheduleResponse", "fields": [ { "name": "bus_id", "type": "str", "required": true }, { "name": "route_id", "type": "str", "required": true }, { "name": "departure_datetime", "type": "datetime", "required": true }, { "name": "arrival_datetime", "type": "datetime", "required": true }, { "name": "base_price", "type": "float", "required": true }, { "name": "available_seats", "type": "int", "required": true }, { "name": "status", "type": "ScheduleStatus", "required": true, "enum_values": [ "SCHEDULED", "IN_TRANSIT", "COMPLETED", "CANCELLED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{schedule_id}", "summary": "Delete Schedule", "description": "Deletes a schedule and all associated seats. Cannot delete schedules that are in_transit or completed. Returns 404 if schedule not found, 400 if schedule status prevents deletion.", "path_params": [ { "name": "schedule_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{schedule_id}/details", "summary": "Get Schedule Details With Related Data", "description": "Retrieves a schedule with all related bus, route, and seat information eagerly loaded. Returns comprehensive details including bus amenities, route distance, and all seat statuses. Returns 404 if schedule not found.", "path_params": [ { "name": "schedule_id", "type": "str" } ], "response": { "schema_name": "ScheduleDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "departure_datetime", "type": "datetime", "required": true }, { "name": "arrival_datetime", "type": "datetime", "required": true }, { "name": "bus", "type": "BusDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "bus_number", "type": "str", "required": true } ] }, { "name": "route", "type": "RouteDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "origin_city", "type": "str", "required": true }, { "name": "destination_city", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{schedule_id}/generate-seats", "summary": "Generate Seat Inventory For Schedule", "description": "Auto-generates seat records for a schedule based on the bus seat layout configuration. Creates individual seat records with seat numbers, types, and price modifiers. Updates the schedule available_seats count. Returns 404 if schedule not found, 409 if seats already exist, 400 if bus layout configuration is invalid.", "path_params": [ { "name": "schedule_id", "type": "str" } ], "request_body": { "schema_name": "GenerateSeatsRequest", "fields": [] }, "response": { "schema_name": "GenerateSeatsResponse", "fields": [ { "name": "schedule_id", "type": "str", "required": true }, { "name": "seats_generated", "type": "int", "required": true }, { "name": "message", "type": "str", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/search/schedules", "summary": "Search Schedules By Route And Date", "description": "Searches for available schedules by origin city, destination city, and departure date. Returns only schedules with status 'scheduled'. Results are ordered by departure datetime ascending. Supports pagination.", "query_params": [ { "name": "origin_city", "type": "str", "required": false }, { "name": "destination_city", "type": "str", "required": false }, { "name": "departure_date", "type": "str", "required": false }, { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "ScheduleResponse", "fields": [ { "name": "bus_id", "type": "str", "required": true }, { "name": "route_id", "type": "str", "required": true }, { "name": "departure_datetime", "type": "datetime", "required": true }, { "name": "arrival_datetime", "type": "datetime", "required": true }, { "name": "base_price", "type": "float", "required": true }, { "name": "available_seats", "type": "int", "required": true }, { "name": "status", "type": "ScheduleStatus", "required": true, "enum_values": [ "SCHEDULED", "IN_TRANSIT", "COMPLETED", "CANCELLED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{schedule_id}/seats", "summary": "Get All Seats For Schedule", "description": "Retrieves all seat records for a specific schedule, ordered by seat number. Returns real-time seat availability status. Returns 404 if schedule not found.", "path_params": [ { "name": "schedule_id", "type": "str" } ], "response": { "schema_name": "SeatResponse", "fields": [ { "name": "schedule_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "seat_type", "type": "SeatType", "required": true, "enum_values": [ "STANDARD", "PREMIUM", "SLEEPER" ] }, { "name": "price_modifier", "type": "float", "required": true }, { "name": "status", "type": "SeatStatus", "required": true, "enum_values": [ "AVAILABLE", "RESERVED", "BOOKED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "POST", "path": "/seats", "summary": "Create Individual Seat", "description": "Creates a single seat record for a schedule. Validates that the schedule exists and the seat number is unique within the schedule. Returns 404 if schedule not found, 409 if seat number already exists.", "request_body": { "schema_name": "SeatCreate", "fields": [ { "name": "schedule_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "seat_type", "type": "SeatType", "required": true, "enum_values": [ "STANDARD", "PREMIUM", "SLEEPER" ] }, { "name": "price_modifier", "type": "float", "required": true }, { "name": "status", "type": "SeatStatus", "required": true, "enum_values": [ "AVAILABLE", "RESERVED", "BOOKED" ] } ] }, "response": { "schema_name": "SeatResponse", "fields": [ { "name": "schedule_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "seat_type", "type": "SeatType", "required": true, "enum_values": [ "STANDARD", "PREMIUM", "SLEEPER" ] }, { "name": "price_modifier", "type": "float", "required": true }, { "name": "status", "type": "SeatStatus", "required": true, "enum_values": [ "AVAILABLE", "RESERVED", "BOOKED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/seats/{seat_id}", "summary": "Get Seat By ID", "description": "Retrieves a single seat by its unique identifier. Returns 404 if the seat does not exist.", "path_params": [ { "name": "seat_id", "type": "str" } ], "response": { "schema_name": "SeatResponse", "fields": [ { "name": "schedule_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "seat_type", "type": "SeatType", "required": true, "enum_values": [ "STANDARD", "PREMIUM", "SLEEPER" ] }, { "name": "price_modifier", "type": "float", "required": true }, { "name": "status", "type": "SeatStatus", "required": true, "enum_values": [ "AVAILABLE", "RESERVED", "BOOKED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/seats/list/all", "summary": "List Seats", "description": "Returns a paginated list of seats. Supports optional filtering by schedule_id and status. Results are ordered by seat number.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "schedule_id", "type": "str", "required": false }, { "name": "status", "type": "SeatStatus", "required": false } ], "response": { "schema_name": "SeatResponse", "fields": [ { "name": "schedule_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "seat_type", "type": "SeatType", "required": true, "enum_values": [ "STANDARD", "PREMIUM", "SLEEPER" ] }, { "name": "price_modifier", "type": "float", "required": true }, { "name": "status", "type": "SeatStatus", "required": true, "enum_values": [ "AVAILABLE", "RESERVED", "BOOKED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/seats/{seat_id}", "summary": "Update Seat", "description": "Updates an existing seat record. Validates that any new schedule reference exists and seat number remains unique within the schedule. Returns 404 if seat or schedule not found, 409 if seat number conflict.", "path_params": [ { "name": "seat_id", "type": "str" } ], "request_body": { "schema_name": "SeatUpdate", "fields": [ { "name": "schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "seat_number", "type": "str", "required": false, "nullable": true }, { "name": "seat_type", "type": "SeatType", "required": false, "nullable": true, "enum_values": [ "STANDARD", "PREMIUM", "SLEEPER" ] }, { "name": "price_modifier", "type": "float", "required": false, "nullable": true }, { "name": "status", "type": "SeatStatus", "required": false, "nullable": true, "enum_values": [ "AVAILABLE", "RESERVED", "BOOKED" ] } ] }, "response": { "schema_name": "SeatResponse", "fields": [ { "name": "schedule_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "seat_type", "type": "SeatType", "required": true, "enum_values": [ "STANDARD", "PREMIUM", "SLEEPER" ] }, { "name": "price_modifier", "type": "float", "required": true }, { "name": "status", "type": "SeatStatus", "required": true, "enum_values": [ "AVAILABLE", "RESERVED", "BOOKED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/seats/{seat_id}", "summary": "Delete Seat", "description": "Deletes a seat record. Can only delete seats with status 'available'. Returns 404 if seat not found, 400 if seat is reserved or booked.", "path_params": [ { "name": "seat_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Reservations", "prefix": "/reservations", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Reservation", "description": "Creates a new reservation with temporary seat locks for 15 minutes. Validates that the user does not have an active reservation for the same schedule, all seats are available, and the schedule is in the future. Returns 409 if the user already has an active reservation or if any seat is unavailable.", "request_body": { "schema_name": "ReservationCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "reservation_datetime", "type": "datetime", "required": true }, { "name": "expiry_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "ACTIVE", "EXPIRED", "CONFIRMED", "CANCELLED" ] }, { "name": "total_amount", "type": "float", "required": true }, { "name": "seat_ids", "type": "List[str]", "required": true } ] }, "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "reservation_datetime", "type": "datetime", "required": true }, { "name": "expiry_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "ACTIVE", "EXPIRED", "CONFIRMED", "CANCELLED" ] }, { "name": "total_amount", "type": "float", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Reservations", "description": "Returns a paginated list of reservations. Supports optional filters by user_id, schedule_id, and status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "schedule_id", "type": "str", "required": false }, { "name": "status", "type": "str", "required": false } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "reservation_datetime", "type": "datetime", "required": true }, { "name": "expiry_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "ACTIVE", "EXPIRED", "CONFIRMED", "CANCELLED" ] }, { "name": "total_amount", "type": "float", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/active", "summary": "List Active Reservations", "description": "Returns a paginated list of all active reservations. Used by admin to monitor current reservation locks.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "reservation_datetime", "type": "datetime", "required": true }, { "name": "expiry_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "ACTIVE", "EXPIRED", "CONFIRMED", "CANCELLED" ] }, { "name": "total_amount", "type": "float", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{reservation_id}", "summary": "Get Reservation", "description": "Returns a single reservation by ID. Returns 404 if the reservation does not exist.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "reservation_datetime", "type": "datetime", "required": true }, { "name": "expiry_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "ACTIVE", "EXPIRED", "CONFIRMED", "CANCELLED" ] }, { "name": "total_amount", "type": "float", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{reservation_id}/details", "summary": "Get Reservation Details", "description": "Returns detailed reservation information including user details, schedule with bus and route information, and all reserved seats with their types and numbers. Returns 404 if the reservation does not exist.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "response": { "schema_name": "ReservationDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "reservation_datetime", "type": "datetime", "required": true }, { "name": "expiry_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "ACTIVE", "EXPIRED", "CONFIRMED", "CANCELLED" ] }, { "name": "total_amount", "type": "float", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "user", "type": "UserDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] }, { "name": "schedule", "type": "ScheduleDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "departure_datetime", "type": "datetime", "required": true }, { "name": "arrival_datetime", "type": "datetime", "required": true }, { "name": "bus", "type": "BusDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "bus_number", "type": "str", "required": true } ] }, { "name": "route", "type": "RouteDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "origin_city", "type": "str", "required": true }, { "name": "destination_city", "type": "str", "required": true } ] } ] }, { "name": "reservation_seats", "type": "List[ReservationSeatDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "seat", "type": "SeatDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "seat_type", "type": "str", "required": true }, { "name": "price_modifier", "type": "float", "required": true } ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{reservation_id}", "summary": "Update Reservation", "description": "Updates an existing reservation. Validates that referenced user_id and schedule_id exist if provided. Returns 404 if the reservation does not exist.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "request_body": { "schema_name": "ReservationUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "reservation_datetime", "type": "datetime", "required": false, "nullable": true }, { "name": "expiry_datetime", "type": "datetime", "required": false, "nullable": true }, { "name": "status", "type": "ReservationStatus", "required": false, "nullable": true, "enum_values": [ "ACTIVE", "EXPIRED", "CONFIRMED", "CANCELLED" ] }, { "name": "total_amount", "type": "float", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "reservation_datetime", "type": "datetime", "required": true }, { "name": "expiry_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "ACTIVE", "EXPIRED", "CONFIRMED", "CANCELLED" ] }, { "name": "total_amount", "type": "float", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{reservation_id}", "summary": "Delete Reservation", "description": "Deletes a reservation and releases all associated seats back to available status. Updates the schedule available_seats count. Returns 400 if the reservation is already confirmed. Returns 404 if the reservation does not exist.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/expire-batch", "summary": "Expire Reservations Batch", "description": "Background job endpoint that finds all expired reservations, updates their status to expired, releases all associated seats back to available, and updates schedule available_seats counts. Returns the count of expired reservations.", "status_code": 200 }, { "method": "POST", "path": "/{reservation_id}/release", "summary": "Release Reservation Manually", "description": "Admin endpoint to manually release an active reservation, updating its status to cancelled and releasing all associated seats back to available. Returns 400 if the reservation is not active. Returns 404 if the reservation does not exist.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Booking Management", "prefix": "/bookings", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Booking", "description": "Creates a new booking record after successful payment. Validates that the reservation, user, and schedule exist. Returns 409 if the booking reference already exists.", "request_body": { "schema_name": "BookingCreate", "fields": [ { "name": "reservation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "booking_datetime", "type": "datetime", "required": true }, { "name": "total_amount", "type": "Decimal", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "booking_reference", "type": "str", "required": true }, { "name": "status", "type": "BookingStatus", "required": true, "enum_values": [ "CONFIRMED", "CANCELLED", "COMPLETED" ] } ] }, "response": { "schema_name": "BookingResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reservation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "booking_datetime", "type": "datetime", "required": true }, { "name": "total_amount", "type": "Decimal", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "booking_reference", "type": "str", "required": true }, { "name": "status", "type": "BookingStatus", "required": true, "enum_values": [ "CONFIRMED", "CANCELLED", "COMPLETED" ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Bookings", "description": "Returns a paginated list of bookings. Supports optional filters for user_id, schedule_id, and status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "schedule_id", "type": "str", "required": false }, { "name": "status", "type": "BookingStatus", "required": false } ], "response": { "schema_name": "BookingResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reservation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "booking_datetime", "type": "datetime", "required": true }, { "name": "total_amount", "type": "Decimal", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "booking_reference", "type": "str", "required": true }, { "name": "status", "type": "BookingStatus", "required": true, "enum_values": [ "CONFIRMED", "CANCELLED", "COMPLETED" ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{booking_id}", "summary": "Get Booking", "description": "Returns a single booking by ID. Returns 404 if the booking does not exist.", "path_params": [ { "name": "booking_id", "type": "str" } ], "response": { "schema_name": "BookingResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reservation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "booking_datetime", "type": "datetime", "required": true }, { "name": "total_amount", "type": "Decimal", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "booking_reference", "type": "str", "required": true }, { "name": "status", "type": "BookingStatus", "required": true, "enum_values": [ "CONFIRMED", "CANCELLED", "COMPLETED" ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{booking_id}/details", "summary": "Get Booking Details", "description": "Returns comprehensive booking details including user information, schedule with bus and route details, booked seats with seat types, ticket information, and payment history. All related data is eagerly loaded to avoid N+1 queries.", "path_params": [ { "name": "booking_id", "type": "str" } ], "response": { "schema_name": "BookingDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reservation_id", "type": "str", "required": true }, { "name": "booking_datetime", "type": "datetime", "required": true }, { "name": "total_amount", "type": "Decimal", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "booking_reference", "type": "str", "required": true }, { "name": "status", "type": "BookingStatus", "required": true, "enum_values": [ "CONFIRMED", "CANCELLED", "COMPLETED" ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "user", "type": "UserSummary", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] }, { "name": "schedule", "type": "ScheduleSummary", "required": true, "fields": [ { "name": "departure_datetime", "type": "datetime", "required": true }, { "name": "arrival_datetime", "type": "datetime", "required": true }, { "name": "bus", "type": "BusSummary", "required": true, "fields": [ { "name": "bus_number", "type": "str", "required": true }, { "name": "bus_type", "type": "str", "required": true } ] }, { "name": "route", "type": "RouteSummary", "required": true, "fields": [ { "name": "origin_city", "type": "str", "required": true }, { "name": "destination_city", "type": "str", "required": true } ] } ] }, { "name": "booking_seats", "type": "List[BookingSeatDetail]", "required": true, "is_list": true, "item_fields": [ { "name": "seat_number", "type": "str", "required": true }, { "name": "seat", "type": "SeatSummary", "required": true, "fields": [ { "name": "seat_type", "type": "str", "required": true } ] } ] }, { "name": "ticket", "type": "TicketSummary", "required": false, "nullable": true, "fields": [ { "name": "ticket_number", "type": "str", "required": true }, { "name": "qr_code", "type": "str", "required": true }, { "name": "validity_status", "type": "str", "required": true } ] }, { "name": "payments", "type": "List[PaymentSummary]", "required": true, "is_list": true, "item_fields": [ { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{booking_id}", "summary": "Update Booking", "description": "Updates an existing booking. Validates foreign key references if they are being changed. Returns 404 if the booking does not exist, 409 if the new booking reference already exists.", "path_params": [ { "name": "booking_id", "type": "str" } ], "request_body": { "schema_name": "BookingUpdate", "fields": [ { "name": "reservation_id", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "booking_datetime", "type": "datetime", "required": false, "nullable": true }, { "name": "total_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "payment_status", "type": "PaymentStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "booking_reference", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "BookingStatus", "required": false, "nullable": true, "enum_values": [ "CONFIRMED", "CANCELLED", "COMPLETED" ] } ] }, "response": { "schema_name": "BookingResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reservation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "schedule_id", "type": "str", "required": true }, { "name": "booking_datetime", "type": "datetime", "required": true }, { "name": "total_amount", "type": "Decimal", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "booking_reference", "type": "str", "required": true }, { "name": "status", "type": "BookingStatus", "required": true, "enum_values": [ "CONFIRMED", "CANCELLED", "COMPLETED" ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{booking_id}", "summary": "Delete Booking", "description": "Deletes a booking and all associated records (booking seats, ticket, payments, cancellation) via cascade. Returns 404 if the booking does not exist.", "path_params": [ { "name": "booking_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/seats", "summary": "Create Booking Seat", "description": "Creates a booking seat record linking a booking to a seat. Validates that both the booking and seat exist. Returns 404 if either does not exist.", "request_body": { "schema_name": "BookingseatCreate", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "seat_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true } ] }, "response": { "schema_name": "BookingseatResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "seat_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/seats", "summary": "List Booking Seats", "description": "Returns a paginated list of booking seats. Supports optional filter for booking_id to retrieve all seats for a specific booking.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "booking_id", "type": "str", "required": false } ], "response": { "schema_name": "BookingseatResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "seat_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/seats/{bookingseat_id}", "summary": "Get Booking Seat", "description": "Returns a single booking seat by ID. Returns 404 if the booking seat does not exist.", "path_params": [ { "name": "bookingseat_id", "type": "str" } ], "response": { "schema_name": "BookingseatResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "seat_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/seats/{bookingseat_id}", "summary": "Update Booking Seat", "description": "Updates an existing booking seat. Validates foreign key references if they are being changed. Returns 404 if the booking seat, booking, or seat does not exist.", "path_params": [ { "name": "bookingseat_id", "type": "str" } ], "request_body": { "schema_name": "BookingseatUpdate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "seat_id", "type": "str", "required": false, "nullable": true }, { "name": "seat_number", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookingseatResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "seat_id", "type": "str", "required": true }, { "name": "seat_number", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/seats/{bookingseat_id}", "summary": "Delete Booking Seat", "description": "Deletes a booking seat record. Returns 404 if the booking seat does not exist.", "path_params": [ { "name": "bookingseat_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/tickets", "summary": "Create Ticket", "description": "Creates a ticket for a confirmed booking. Validates that the booking exists and does not already have a ticket. Returns 404 if the booking does not exist, 409 if a ticket already exists for the booking or if the ticket number is already in use.", "request_body": { "schema_name": "TicketCreate", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "ticket_number", "type": "str", "required": true }, { "name": "qr_code", "type": "str", "required": true }, { "name": "issue_datetime", "type": "datetime", "required": true }, { "name": "validity_status", "type": "TicketValidityStatus", "required": true, "enum_values": [ "VALID", "USED", "CANCELLED" ] } ] }, "response": { "schema_name": "TicketResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "ticket_number", "type": "str", "required": true }, { "name": "qr_code", "type": "str", "required": true }, { "name": "issue_datetime", "type": "datetime", "required": true }, { "name": "validity_status", "type": "TicketValidityStatus", "required": true, "enum_values": [ "VALID", "USED", "CANCELLED" ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/tickets", "summary": "List Tickets", "description": "Returns a paginated list of tickets. Supports optional filter for validity_status to retrieve tickets by their validity status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "validity_status", "type": "TicketValidityStatus", "required": false } ], "response": { "schema_name": "TicketResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "ticket_number", "type": "str", "required": true }, { "name": "qr_code", "type": "str", "required": true }, { "name": "issue_datetime", "type": "datetime", "required": true }, { "name": "validity_status", "type": "TicketValidityStatus", "required": true, "enum_values": [ "VALID", "USED", "CANCELLED" ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/tickets/{ticket_id}", "summary": "Get Ticket", "description": "Returns a single ticket by ID. Returns 404 if the ticket does not exist.", "path_params": [ { "name": "ticket_id", "type": "str" } ], "response": { "schema_name": "TicketResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "ticket_number", "type": "str", "required": true }, { "name": "qr_code", "type": "str", "required": true }, { "name": "issue_datetime", "type": "datetime", "required": true }, { "name": "validity_status", "type": "TicketValidityStatus", "required": true, "enum_values": [ "VALID", "USED", "CANCELLED" ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/tickets/{ticket_id}", "summary": "Update Ticket", "description": "Updates an existing ticket. Validates that the booking exists if booking_id is being changed, and ensures ticket number uniqueness. Returns 404 if the ticket or booking does not exist, 409 if the new ticket number or booking already has a ticket.", "path_params": [ { "name": "ticket_id", "type": "str" } ], "request_body": { "schema_name": "TicketUpdate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "ticket_number", "type": "str", "required": false, "nullable": true }, { "name": "qr_code", "type": "str", "required": false, "nullable": true }, { "name": "issue_datetime", "type": "datetime", "required": false, "nullable": true }, { "name": "validity_status", "type": "TicketValidityStatus", "required": false, "nullable": true, "enum_values": [ "VALID", "USED", "CANCELLED" ] } ] }, "response": { "schema_name": "TicketResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "ticket_number", "type": "str", "required": true }, { "name": "qr_code", "type": "str", "required": true }, { "name": "issue_datetime", "type": "datetime", "required": true }, { "name": "validity_status", "type": "TicketValidityStatus", "required": true, "enum_values": [ "VALID", "USED", "CANCELLED" ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/tickets/{ticket_id}", "summary": "Delete Ticket", "description": "Deletes a ticket record. Returns 404 if the ticket does not exist.", "path_params": [ { "name": "ticket_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Payments", "prefix": "/payments", "endpoints": [ { "method": "POST", "path": "/initiate", "summary": "Initiate Payment for Reservation", "description": "Initiates payment processing for an active reservation. Creates a booking record and payment record with pending status. Returns payment gateway reference for external payment processing. Validates that reservation is active and not expired. Returns 404 if reservation not found, 400 if reservation expired or not active, 409 if booking already exists for reservation.", "request_body": { "schema_name": "PaymentInitiateRequest", "fields": [ { "name": "reservation_id", "type": "str", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "UPI", "NET_BANKING", "WALLET" ] } ] }, "response": { "schema_name": "PaymentInitiateResponse", "fields": [ { "name": "payment_id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "UPI", "NET_BANKING", "WALLET" ] }, { "name": "payment_gateway_reference", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "transaction_datetime", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "POST", "path": "/webhook", "summary": "Process Payment Gateway Webhook", "description": "Processes payment gateway webhook callback to update payment status. On success, confirms booking, updates seat statuses to booked, generates ticket with QR code, and updates reservation status to confirmed. On failure, marks payment and booking as failed. Returns success status and relevant IDs.", "request_body": { "schema_name": "PaymentWebhookRequest", "fields": [ { "name": "payment_gateway_reference", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentWebhookResponse", "fields": [ { "name": "success", "type": "bool", "required": true }, { "name": "message", "type": "str", "required": true }, { "name": "payment_id", "type": "str", "required": false, "nullable": true }, { "name": "booking_id", "type": "str", "required": false, "nullable": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get Payment by ID", "description": "Retrieves a single payment record by its unique identifier. Returns 404 if payment not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "UPI", "NET_BANKING", "WALLET" ] }, { "name": "payment_gateway_reference", "type": "str", "required": false, "nullable": true }, { "name": "transaction_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Payments", "description": "Returns a paginated list of payment records. Supports optional filtering by user ID, booking ID, payment status, and payment method. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "booking_id", "type": "str", "required": false }, { "name": "payment_status", "type": "PaymentStatus", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": false } ], "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "UPI", "NET_BANKING", "WALLET" ] }, { "name": "payment_gateway_reference", "type": "str", "required": false, "nullable": true }, { "name": "transaction_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "POST", "path": "/", "summary": "Create Payment Record", "description": "Creates a new payment record manually. Validates that booking and user exist. Returns 404 if booking or user not found, 400 if amount is not positive.", "request_body": { "schema_name": "PaymentCreate", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "UPI", "NET_BANKING", "WALLET" ] }, { "name": "payment_gateway_reference", "type": "str", "required": false, "nullable": true }, { "name": "transaction_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "UPI", "NET_BANKING", "WALLET" ] }, { "name": "payment_gateway_reference", "type": "str", "required": false, "nullable": true }, { "name": "transaction_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "PUT", "path": "/{id}", "summary": "Update Payment Record", "description": "Updates an existing payment record. Validates that referenced booking and user exist if those fields are updated. Returns 404 if payment, booking, or user not found, 400 if amount is not positive.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "PaymentUpdate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "payment_method", "type": "PaymentMethod", "required": false, "nullable": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "UPI", "NET_BANKING", "WALLET" ] }, { "name": "payment_gateway_reference", "type": "str", "required": false, "nullable": true }, { "name": "transaction_datetime", "type": "datetime", "required": false, "nullable": true }, { "name": "status", "type": "PaymentStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "UPI", "NET_BANKING", "WALLET" ] }, { "name": "payment_gateway_reference", "type": "str", "required": false, "nullable": true }, { "name": "transaction_datetime", "type": "datetime", "required": true }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete Payment Record", "description": "Deletes a payment record by ID. Returns 404 if payment not found, 500 if deletion fails.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Cancellations", "prefix": "/cancellations", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Cancellation", "description": "Creates a new cancellation record for a booking. Validates that the booking exists, is not already cancelled, and that the refund amount does not exceed the booking total. Returns 404 if booking or user not found, 400 if validation fails.", "request_body": { "schema_name": "CancellationCreate", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "cancellation_datetime", "type": "datetime", "required": true }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "refund_amount", "type": "float", "required": true }, { "name": "refund_status", "type": "str", "required": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "CancellationResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "cancellation_datetime", "type": "datetime", "required": true }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "refund_amount", "type": "float", "required": true }, { "name": "refund_status", "type": "str", "required": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Cancellations", "description": "Returns a paginated list of cancellations. Supports optional filters by user_id, booking_id, and refund_status. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "booking_id", "type": "str", "required": false }, { "name": "refund_status", "type": "str", "required": false } ], "response": { "schema_name": "CancellationResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "cancellation_datetime", "type": "datetime", "required": true }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "refund_amount", "type": "float", "required": true }, { "name": "refund_status", "type": "str", "required": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get Cancellation By ID", "description": "Retrieves a single cancellation record by its unique identifier. Returns 404 if the cancellation does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "CancellationResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "cancellation_datetime", "type": "datetime", "required": true }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "refund_amount", "type": "float", "required": true }, { "name": "refund_status", "type": "str", "required": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{id}/details", "summary": "Get Cancellation Details", "description": "Retrieves comprehensive cancellation details including booking reference, schedule information, bus details, route information, and user information. Uses eager loading to prevent N+1 queries. Returns 404 if cancellation not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "CancellationDetailsResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "cancellation_datetime", "type": "datetime", "required": true }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "refund_amount", "type": "float", "required": true }, { "name": "refund_status", "type": "str", "required": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "booking_reference", "type": "str", "required": true }, { "name": "schedule_departure_datetime", "type": "datetime", "required": true }, { "name": "bus_number", "type": "str", "required": true }, { "name": "origin_city", "type": "str", "required": true }, { "name": "destination_city", "type": "str", "required": true }, { "name": "user_email", "type": "str", "required": true }, { "name": "user_first_name", "type": "str", "required": true }, { "name": "user_last_name", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Cancellation", "description": "Updates an existing cancellation record. Only provided fields are updated; unset fields remain unchanged. Validates foreign key references if booking_id or user_id are updated. Returns 404 if cancellation not found, 400 if no fields provided.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "CancellationUpdate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "cancellation_datetime", "type": "datetime", "required": false, "nullable": true }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "refund_amount", "type": "float", "required": false, "nullable": true }, { "name": "refund_status", "type": "str", "required": false, "nullable": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "CancellationResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "cancellation_datetime", "type": "datetime", "required": true }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "refund_amount", "type": "float", "required": true }, { "name": "refund_status", "type": "str", "required": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete Cancellation", "description": "Deletes a cancellation record by its unique identifier. Returns 404 if the cancellation does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Activity Logs", "prefix": "/activity-logs", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Activity Log", "description": "Creates a new activity log entry recording a system action. Validates entity_type, entity_id, action_type, and optional JSON details. Returns the created log with generated ID and timestamps.", "request_body": { "schema_name": "ActivitylogCreate", "fields": [ { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false }, { "name": "details", "type": "str", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true } ] }, "response": { "schema_name": "ActivitylogResponse", "fields": [ { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false }, { "name": "details", "type": "str", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Activity Logs", "description": "Returns a paginated list of activity logs ordered by timestamp descending. Supports optional filters for entity_type, entity_id, user_id, action_type, and date range (start_date, end_date). Useful for audit trail queries and system monitoring.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false }, { "name": "action_type", "type": "str", "required": false }, { "name": "start_date", "type": "datetime", "required": false }, { "name": "end_date", "type": "datetime", "required": false } ], "response": { "schema_name": "ActivitylogResponse", "fields": [ { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false }, { "name": "details", "type": "str", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/count", "summary": "Count Activity Logs", "description": "Returns the total count of activity logs matching the provided filters. Supports the same filter parameters as the list endpoint for entity_type, entity_id, user_id, action_type, and date range.", "query_params": [ { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false }, { "name": "action_type", "type": "str", "required": false }, { "name": "start_date", "type": "datetime", "required": false }, { "name": "end_date", "type": "datetime", "required": false } ], "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get Activity Log", "description": "Retrieves a single activity log entry by ID. Returns 404 if the log entry does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ActivitylogResponse", "fields": [ { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false }, { "name": "details", "type": "str", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{id}/details", "summary": "Get Activity Log Details", "description": "Retrieves a single activity log entry with enriched user details (email, first_name, last_name) if user_id is present. Returns 404 if the log entry does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ActivitylogDetailResponse", "fields": [ { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false }, { "name": "details", "type": "str", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "user", "type": "UserSummary", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Activity Log", "description": "Updates an existing activity log entry. All fields are optional; only provided fields are updated. Returns 404 if the log entry does not exist, 400 if no fields are provided.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "ActivitylogUpdate", "fields": [ { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "str", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ActivitylogResponse", "fields": [ { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false }, { "name": "details", "type": "str", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete Activity Log", "description": "Deletes an activity log entry by ID. Returns 404 if the log entry does not exist. Note: deletion of audit logs should be restricted in production environments.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] } ], "enums": { "UserRole": [ "GUEST", "CUSTOMER", "ADMIN" ], "BusType": [ "STANDARD", "DELUXE", "SLEEPER", "SEMI_SLEEPER" ], "ScheduleStatus": [ "SCHEDULED", "IN_TRANSIT", "COMPLETED", "CANCELLED" ], "SeatType": [ "STANDARD", "PREMIUM", "SLEEPER" ], "SeatStatus": [ "AVAILABLE", "RESERVED", "BOOKED" ], "ReservationStatus": [ "ACTIVE", "EXPIRED", "CONFIRMED", "CANCELLED" ], "BookingStatus": [ "CONFIRMED", "CANCELLED", "COMPLETED" ], "PaymentStatus": [ "PENDING", "COMPLETED", "FAILED", "REFUNDED" ], "TicketValidityStatus": [ "VALID", "USED", "CANCELLED" ], "PaymentMethod": [ "CREDIT_CARD", "DEBIT_CARD", "UPI", "NET_BANKING", "WALLET" ], "RefundStatus": [ "PENDING", "PROCESSED", "FAILED" ] } }