{ "version": "1.0", "modules": [ { "name": "User Management", "prefix": "/users", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create User", "description": "Creates a new user account with authentication credentials and role assignment. Validates email uniqueness and password strength requirements (minimum 8 characters with uppercase, lowercase, number, and special character). Returns 409 if email already exists.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "SUPER_ADMIN", "TOUR_MANAGER", "BOOKING_AGENT", "TOUR_GUIDE", "SERVICE_PROVIDER", "CUSTOMER", "FINANCE_MANAGER" ] }, { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "password", "type": "str", "required": false } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "role", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": 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 Users", "description": "Returns a paginated list of users. Supports optional filters for role, active status, and search by name or email. 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": "str", "required": false }, { "name": "is_active", "type": "bool", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "role", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{user_id}", "summary": "Get User By ID", "description": "Retrieves a single user by ID. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "role", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{user_id}", "summary": "Update User", "description": "Updates user information. All fields are optional. Validates email uniqueness if changed and password strength if provided. Returns 404 if user not found, 409 if email conflict.", "path_params": [ { "name": "user_id", "type": "str" } ], "request_body": { "schema_name": "UserUpdate", "fields": [ { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "nullable": true, "enum_values": [ "SUPER_ADMIN", "TOUR_MANAGER", "BOOKING_AGENT", "TOUR_GUIDE", "SERVICE_PROVIDER", "CUSTOMER", "FINANCE_MANAGER" ] }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "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": "role", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{user_id}", "summary": "Delete User", "description": "Deletes a user account. Cascades to related customer, tour guide, or service provider profiles. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/customers", "summary": "Create Customer Profile", "description": "Creates an extended customer profile linked to a user account. Validates that the user exists and does not already have a customer profile. Returns 404 if user not found, 409 if profile already exists.", "request_body": { "schema_name": "CustomerCreate", "fields": [ { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "passport_number", "type": "str", "required": false, "nullable": true }, { "name": "passport_expiry", "type": "date", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_status", "type": "LoyaltyStatus", "required": false, "nullable": true, "enum_values": [ "BRONZE", "SILVER", "GOLD", "PLATINUM" ] }, { "name": "loyalty_points", "type": "int", "required": false, "default": 0 }, { "name": "preferences", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": true } ] }, "response": { "schema_name": "CustomerResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "passport_number", "type": "str", "required": false, "nullable": true }, { "name": "passport_expiry", "type": "date", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_status", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_points", "type": "int", "required": true }, { "name": "preferences", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/customers", "summary": "List Customers", "description": "Returns a paginated list of customer profiles. Supports optional filters for loyalty status and country. 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": "loyalty_status", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false } ], "response": { "schema_name": "CustomerResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "passport_number", "type": "str", "required": false, "nullable": true }, { "name": "passport_expiry", "type": "date", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_status", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_points", "type": "int", "required": true }, { "name": "preferences", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/customers/{customer_id}", "summary": "Get Customer By ID", "description": "Retrieves a single customer profile by ID. Returns 404 if customer not found.", "path_params": [ { "name": "customer_id", "type": "str" } ], "response": { "schema_name": "CustomerResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "passport_number", "type": "str", "required": false, "nullable": true }, { "name": "passport_expiry", "type": "date", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_status", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_points", "type": "int", "required": true }, { "name": "preferences", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/customers/{customer_id}", "summary": "Update Customer Profile", "description": "Updates customer profile information. All fields are optional. Returns 404 if customer not found.", "path_params": [ { "name": "customer_id", "type": "str" } ], "request_body": { "schema_name": "CustomerUpdate", "fields": [ { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "passport_number", "type": "str", "required": false, "nullable": true }, { "name": "passport_expiry", "type": "date", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_status", "type": "LoyaltyStatus", "required": false, "nullable": true, "enum_values": [ "BRONZE", "SILVER", "GOLD", "PLATINUM" ] }, { "name": "loyalty_points", "type": "int", "required": false, "nullable": true }, { "name": "preferences", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CustomerResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "passport_number", "type": "str", "required": false, "nullable": true }, { "name": "passport_expiry", "type": "date", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_status", "type": "str", "required": false, "nullable": true }, { "name": "loyalty_points", "type": "int", "required": true }, { "name": "preferences", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/customers/{customer_id}", "summary": "Delete Customer Profile", "description": "Deletes a customer profile. Returns 404 if customer not found.", "path_params": [ { "name": "customer_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/tour-guides", "summary": "Create Tour Guide Profile", "description": "Creates an extended tour guide profile linked to a user account. Validates that the user exists and does not already have a tour guide profile. Returns 404 if user not found, 409 if profile already exists.", "request_body": { "schema_name": "TourguideCreate", "fields": [ { "name": "languages_spoken", "type": "List[str]", "required": true }, { "name": "specializations", "type": "List[str]", "required": false, "nullable": true }, { "name": "certifications", "type": "str", "required": false, "nullable": true }, { "name": "license_number", "type": "str", "required": false, "nullable": true }, { "name": "license_expiry", "type": "date", "required": false, "nullable": true }, { "name": "years_of_experience", "type": "int", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_tours_conducted", "type": "int", "required": false, "default": 0 }, { "name": "is_available", "type": "bool", "required": false, "default": true }, { "name": "user_id", "type": "str", "required": true } ] }, "response": { "schema_name": "TourguideResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "languages_spoken", "type": "List[str]", "required": true }, { "name": "specializations", "type": "List[str]", "required": false, "nullable": true }, { "name": "certifications", "type": "str", "required": false, "nullable": true }, { "name": "license_number", "type": "str", "required": false, "nullable": true }, { "name": "license_expiry", "type": "date", "required": false, "nullable": true }, { "name": "years_of_experience", "type": "int", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_tours_conducted", "type": "int", "required": true }, { "name": "is_available", "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": "GET", "path": "/tour-guides", "summary": "List Tour Guides", "description": "Returns a paginated list of tour guide profiles. Supports optional filters for availability status and language spoken. 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": "is_available", "type": "bool", "required": false }, { "name": "language", "type": "str", "required": false } ], "response": { "schema_name": "TourguideResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "languages_spoken", "type": "List[str]", "required": true }, { "name": "specializations", "type": "List[str]", "required": false, "nullable": true }, { "name": "certifications", "type": "str", "required": false, "nullable": true }, { "name": "license_number", "type": "str", "required": false, "nullable": true }, { "name": "license_expiry", "type": "date", "required": false, "nullable": true }, { "name": "years_of_experience", "type": "int", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_tours_conducted", "type": "int", "required": true }, { "name": "is_available", "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": "/tour-guides/{tourguide_id}", "summary": "Get Tour Guide By ID", "description": "Retrieves a single tour guide profile by ID. Returns 404 if tour guide not found.", "path_params": [ { "name": "tourguide_id", "type": "str" } ], "response": { "schema_name": "TourguideResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "languages_spoken", "type": "List[str]", "required": true }, { "name": "specializations", "type": "List[str]", "required": false, "nullable": true }, { "name": "certifications", "type": "str", "required": false, "nullable": true }, { "name": "license_number", "type": "str", "required": false, "nullable": true }, { "name": "license_expiry", "type": "date", "required": false, "nullable": true }, { "name": "years_of_experience", "type": "int", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_tours_conducted", "type": "int", "required": true }, { "name": "is_available", "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": "/tour-guides/{tourguide_id}", "summary": "Update Tour Guide Profile", "description": "Updates tour guide profile information. All fields are optional. Returns 404 if tour guide not found.", "path_params": [ { "name": "tourguide_id", "type": "str" } ], "request_body": { "schema_name": "TourguideUpdate", "fields": [ { "name": "languages_spoken", "type": "List[str]", "required": false, "nullable": true }, { "name": "specializations", "type": "List[str]", "required": false, "nullable": true }, { "name": "certifications", "type": "str", "required": false, "nullable": true }, { "name": "license_number", "type": "str", "required": false, "nullable": true }, { "name": "license_expiry", "type": "date", "required": false, "nullable": true }, { "name": "years_of_experience", "type": "int", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_tours_conducted", "type": "int", "required": false, "nullable": true }, { "name": "is_available", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "TourguideResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "languages_spoken", "type": "List[str]", "required": true }, { "name": "specializations", "type": "List[str]", "required": false, "nullable": true }, { "name": "certifications", "type": "str", "required": false, "nullable": true }, { "name": "license_number", "type": "str", "required": false, "nullable": true }, { "name": "license_expiry", "type": "date", "required": false, "nullable": true }, { "name": "years_of_experience", "type": "int", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_tours_conducted", "type": "int", "required": true }, { "name": "is_available", "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": "/tour-guides/{tourguide_id}", "summary": "Delete Tour Guide Profile", "description": "Deletes a tour guide profile. Returns 404 if tour guide not found.", "path_params": [ { "name": "tourguide_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/service-providers", "summary": "Create Service Provider Profile", "description": "Creates an extended service provider profile linked to a user account. Validates that the user exists and does not already have a service provider profile. Returns 404 if user not found, 409 if profile already exists.", "request_body": { "schema_name": "ServiceproviderCreate", "fields": [ { "name": "company_name", "type": "str", "required": false }, { "name": "service_type", "type": "ServiceType", "required": true, "enum_values": [ "HOTEL", "TRANSPORTATION", "RESTAURANT", "ACTIVITY", "INSURANCE", "OTHER" ] }, { "name": "registration_number", "type": "str", "required": false, "nullable": true }, { "name": "tax_id", "type": "str", "required": false, "nullable": true }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "contact_email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "contract_start_date", "type": "date", "required": false, "nullable": true }, { "name": "contract_end_date", "type": "date", "required": false, "nullable": true }, { "name": "payment_terms", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "default": false }, { "name": "user_id", "type": "str", "required": true } ] }, "response": { "schema_name": "ServiceproviderResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "service_type", "type": "str", "required": true }, { "name": "registration_number", "type": "str", "required": false, "nullable": true }, { "name": "tax_id", "type": "str", "required": false, "nullable": true }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "contact_email", "type": "str", "required": false, "nullable": true }, { "name": "contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "contract_start_date", "type": "date", "required": false, "nullable": true }, { "name": "contract_end_date", "type": "date", "required": false, "nullable": true }, { "name": "payment_terms", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "is_verified", "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": "GET", "path": "/service-providers", "summary": "List Service Providers", "description": "Returns a paginated list of service provider profiles. Supports optional filters for service type, verification status, and country. 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": "service_type", "type": "str", "required": false }, { "name": "is_verified", "type": "bool", "required": false }, { "name": "country", "type": "str", "required": false } ], "response": { "schema_name": "ServiceproviderResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "service_type", "type": "str", "required": true }, { "name": "registration_number", "type": "str", "required": false, "nullable": true }, { "name": "tax_id", "type": "str", "required": false, "nullable": true }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "contact_email", "type": "str", "required": false, "nullable": true }, { "name": "contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "contract_start_date", "type": "date", "required": false, "nullable": true }, { "name": "contract_end_date", "type": "date", "required": false, "nullable": true }, { "name": "payment_terms", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "is_verified", "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": "/service-providers/{serviceprovider_id}", "summary": "Get Service Provider By ID", "description": "Retrieves a single service provider profile by ID. Returns 404 if service provider not found.", "path_params": [ { "name": "serviceprovider_id", "type": "str" } ], "response": { "schema_name": "ServiceproviderResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "service_type", "type": "str", "required": true }, { "name": "registration_number", "type": "str", "required": false, "nullable": true }, { "name": "tax_id", "type": "str", "required": false, "nullable": true }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "contact_email", "type": "str", "required": false, "nullable": true }, { "name": "contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "contract_start_date", "type": "date", "required": false, "nullable": true }, { "name": "contract_end_date", "type": "date", "required": false, "nullable": true }, { "name": "payment_terms", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "is_verified", "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": "/service-providers/{serviceprovider_id}", "summary": "Update Service Provider Profile", "description": "Updates service provider profile information. All fields are optional. Returns 404 if service provider not found.", "path_params": [ { "name": "serviceprovider_id", "type": "str" } ], "request_body": { "schema_name": "ServiceproviderUpdate", "fields": [ { "name": "company_name", "type": "str", "required": false, "nullable": true }, { "name": "service_type", "type": "ServiceType", "required": false, "nullable": true, "enum_values": [ "HOTEL", "TRANSPORTATION", "RESTAURANT", "ACTIVITY", "INSURANCE", "OTHER" ] }, { "name": "registration_number", "type": "str", "required": false, "nullable": true }, { "name": "tax_id", "type": "str", "required": false, "nullable": true }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "contact_email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "contract_start_date", "type": "date", "required": false, "nullable": true }, { "name": "contract_end_date", "type": "date", "required": false, "nullable": true }, { "name": "payment_terms", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "ServiceproviderResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "service_type", "type": "str", "required": true }, { "name": "registration_number", "type": "str", "required": false, "nullable": true }, { "name": "tax_id", "type": "str", "required": false, "nullable": true }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "contact_email", "type": "str", "required": false, "nullable": true }, { "name": "contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "contract_start_date", "type": "date", "required": false, "nullable": true }, { "name": "contract_end_date", "type": "date", "required": false, "nullable": true }, { "name": "payment_terms", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "is_verified", "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": "/service-providers/{serviceprovider_id}", "summary": "Delete Service Provider Profile", "description": "Deletes a service provider profile. Returns 404 if service provider not found.", "path_params": [ { "name": "serviceprovider_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Tour Catalog", "prefix": "/tour-catalog", "endpoints": [ { "method": "POST", "path": "/categories", "summary": "Create Category", "description": "Creates a new tour package category. Returns 409 if a category with the same slug already exists.", "request_body": { "schema_name": "CategoryCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "display_order", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/categories", "summary": "List Categories", "description": "Returns a paginated list of tour package categories. Supports optional filters for active status and search by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/categories/{category_id}", "summary": "Get Category", "description": "Returns a single category by ID. Returns 404 if the category does not exist.", "path_params": [ { "name": "category_id", "type": "str" } ], "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/categories/{category_id}", "summary": "Update Category", "description": "Updates an existing category. Returns 404 if the category does not exist, 409 if the new slug conflicts with another category.", "path_params": [ { "name": "category_id", "type": "str" } ], "request_body": { "schema_name": "CategoryUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "slug", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/categories/{category_id}", "summary": "Delete Category", "description": "Deletes a category by ID. Returns 404 if the category does not exist.", "path_params": [ { "name": "category_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/destinations", "summary": "Create Destination", "description": "Creates a new destination. Returns 409 if a destination with the same slug already exists.", "request_body": { "schema_name": "DestinationCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "attractions", "type": "str", "required": false, "nullable": true }, { "name": "best_time_to_visit", "type": "str", "required": false, "nullable": true }, { "name": "climate_info", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "DestinationResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "attractions", "type": "str", "required": false, "nullable": true }, { "name": "best_time_to_visit", "type": "str", "required": false, "nullable": true }, { "name": "climate_info", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "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": "/destinations", "summary": "List Destinations", "description": "Returns a paginated list of destinations. Supports optional filters for active status, country, and search by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "DestinationResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "attractions", "type": "str", "required": false, "nullable": true }, { "name": "best_time_to_visit", "type": "str", "required": false, "nullable": true }, { "name": "climate_info", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "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": "/destinations/{destination_id}", "summary": "Get Destination", "description": "Returns a single destination by ID. Returns 404 if the destination does not exist.", "path_params": [ { "name": "destination_id", "type": "str" } ], "response": { "schema_name": "DestinationResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "attractions", "type": "str", "required": false, "nullable": true }, { "name": "best_time_to_visit", "type": "str", "required": false, "nullable": true }, { "name": "climate_info", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "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": "/destinations/{destination_id}", "summary": "Update Destination", "description": "Updates an existing destination. Returns 404 if the destination does not exist, 409 if the new slug conflicts with another destination.", "path_params": [ { "name": "destination_id", "type": "str" } ], "request_body": { "schema_name": "DestinationUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "slug", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "attractions", "type": "str", "required": false, "nullable": true }, { "name": "best_time_to_visit", "type": "str", "required": false, "nullable": true }, { "name": "climate_info", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "DestinationResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "attractions", "type": "str", "required": false, "nullable": true }, { "name": "best_time_to_visit", "type": "str", "required": false, "nullable": true }, { "name": "climate_info", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "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": "/destinations/{destination_id}", "summary": "Delete Destination", "description": "Deletes a destination by ID. Returns 404 if the destination does not exist.", "path_params": [ { "name": "destination_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/seasons", "summary": "Create Season", "description": "Creates a new seasonal pricing period. Validates that end date is after start date.", "request_body": { "schema_name": "SeasonCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "season_type", "type": "SeasonType", "required": true, "enum_values": [ "PEAK", "OFF_PEAK", "SHOULDER" ] }, { "name": "start_date", "type": "date", "required": true }, { "name": "end_date", "type": "date", "required": true }, { "name": "price_multiplier", "type": "float", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "SeasonResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "season_type", "type": "SeasonType", "required": true, "enum_values": [ "PEAK", "OFF_PEAK", "SHOULDER" ] }, { "name": "start_date", "type": "date", "required": true }, { "name": "end_date", "type": "date", "required": true }, { "name": "price_multiplier", "type": "float", "required": false }, { "name": "description", "type": "str", "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": "/seasons", "summary": "List Seasons", "description": "Returns a paginated list of seasons ordered by start date. Supports optional filter by season type.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "season_type", "type": "str", "required": false } ], "response": { "schema_name": "SeasonResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "season_type", "type": "SeasonType", "required": true, "enum_values": [ "PEAK", "OFF_PEAK", "SHOULDER" ] }, { "name": "start_date", "type": "date", "required": true }, { "name": "end_date", "type": "date", "required": true }, { "name": "price_multiplier", "type": "float", "required": false }, { "name": "description", "type": "str", "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": "/seasons/{season_id}", "summary": "Get Season", "description": "Returns a single season by ID. Returns 404 if the season does not exist.", "path_params": [ { "name": "season_id", "type": "str" } ], "response": { "schema_name": "SeasonResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "season_type", "type": "SeasonType", "required": true, "enum_values": [ "PEAK", "OFF_PEAK", "SHOULDER" ] }, { "name": "start_date", "type": "date", "required": true }, { "name": "end_date", "type": "date", "required": true }, { "name": "price_multiplier", "type": "float", "required": false }, { "name": "description", "type": "str", "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": "PUT", "path": "/seasons/{season_id}", "summary": "Update Season", "description": "Updates an existing season. Returns 404 if the season does not exist.", "path_params": [ { "name": "season_id", "type": "str" } ], "request_body": { "schema_name": "SeasonUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "season_type", "type": "SeasonType", "required": false, "nullable": true, "enum_values": [ "PEAK", "OFF_PEAK", "SHOULDER" ] }, { "name": "start_date", "type": "date", "required": false, "nullable": true }, { "name": "end_date", "type": "date", "required": false, "nullable": true }, { "name": "price_multiplier", "type": "float", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "SeasonResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "season_type", "type": "SeasonType", "required": true, "enum_values": [ "PEAK", "OFF_PEAK", "SHOULDER" ] }, { "name": "start_date", "type": "date", "required": true }, { "name": "end_date", "type": "date", "required": true }, { "name": "price_multiplier", "type": "float", "required": false }, { "name": "description", "type": "str", "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": "/seasons/{season_id}", "summary": "Delete Season", "description": "Deletes a season by ID. Returns 404 if the season does not exist.", "path_params": [ { "name": "season_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/amenities", "summary": "Create Amenity", "description": "Creates a new amenity that can be associated with tour packages or hotels.", "request_body": { "schema_name": "AmenityCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "amenity_type", "type": "AmenityType", "required": true, "enum_values": [ "ACCOMMODATION", "TRANSPORT", "TOUR", "GENERAL" ] } ] }, "response": { "schema_name": "AmenityResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "amenity_type", "type": "str", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/amenities", "summary": "List Amenities", "description": "Returns a paginated list of amenities. Supports optional filters for amenity type and search by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "amenity_type", "type": "str", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "AmenityResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "amenity_type", "type": "str", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/amenities/{amenity_id}", "summary": "Get Amenity", "description": "Returns a single amenity by ID. Returns 404 if the amenity does not exist.", "path_params": [ { "name": "amenity_id", "type": "str" } ], "response": { "schema_name": "AmenityResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "amenity_type", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/amenities/{amenity_id}", "summary": "Update Amenity", "description": "Updates an existing amenity. Returns 404 if the amenity does not exist.", "path_params": [ { "name": "amenity_id", "type": "str" } ], "request_body": { "schema_name": "AmenityUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "amenity_type", "type": "AmenityType", "required": false, "nullable": true, "enum_values": [ "ACCOMMODATION", "TRANSPORT", "TOUR", "GENERAL" ] } ] }, "response": { "schema_name": "AmenityResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "amenity_type", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/amenities/{amenity_id}", "summary": "Delete Amenity", "description": "Deletes an amenity by ID. Returns 404 if the amenity does not exist.", "path_params": [ { "name": "amenity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/tour-packages", "summary": "Create Tour Package", "description": "Creates a new tour package. Validates that the category exists and the slug is unique. Returns 404 if category not found, 409 if slug already exists.", "request_body": { "schema_name": "TourpackageCreate", "fields": [ { "name": "category_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "duration_days", "type": "int", "required": false }, { "name": "duration_nights", "type": "int", "required": false }, { "name": "difficulty_level", "type": "DifficultyLevel", "required": false, "nullable": true, "enum_values": [ "EASY", "MODERATE", "CHALLENGING", "DIFFICULT" ] }, { "name": "min_age", "type": "int", "required": false, "nullable": true }, { "name": "max_age", "type": "int", "required": false, "nullable": true }, { "name": "min_group_size", "type": "int", "required": false }, { "name": "max_group_size", "type": "int", "required": false }, { "name": "base_price", "type": "float", "required": false }, { "name": "child_price", "type": "float", "required": false, "nullable": true }, { "name": "single_supplement", "type": "float", "required": false, "nullable": true }, { "name": "inclusions", "type": "str", "required": false, "nullable": true }, { "name": "exclusions", "type": "str", "required": false, "nullable": true }, { "name": "terms_and_conditions", "type": "str", "required": false, "nullable": true }, { "name": "cancellation_policy", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "is_featured", "type": "bool", "required": false, "default": false }, { "name": "image_url", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TourpackageResponse", "fields": [ { "name": "category_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "duration_days", "type": "int", "required": false }, { "name": "duration_nights", "type": "int", "required": false }, { "name": "difficulty_level", "type": "DifficultyLevel", "required": false, "nullable": true, "enum_values": [ "EASY", "MODERATE", "CHALLENGING", "DIFFICULT" ] }, { "name": "min_age", "type": "int", "required": false, "nullable": true }, { "name": "max_age", "type": "int", "required": false, "nullable": true }, { "name": "min_group_size", "type": "int", "required": false }, { "name": "max_group_size", "type": "int", "required": false }, { "name": "base_price", "type": "float", "required": false }, { "name": "child_price", "type": "float", "required": false, "nullable": true }, { "name": "single_supplement", "type": "float", "required": false, "nullable": true }, { "name": "inclusions", "type": "str", "required": false, "nullable": true }, { "name": "exclusions", "type": "str", "required": false, "nullable": true }, { "name": "terms_and_conditions", "type": "str", "required": false, "nullable": true }, { "name": "cancellation_policy", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "is_featured", "type": "bool", "required": false, "default": false }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_reviews", "type": "int", "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": "/tour-packages", "summary": "List Tour Packages", "description": "Returns a paginated list of tour packages. Supports optional filters for active status, featured status, category, difficulty level, and search by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false }, { "name": "is_featured", "type": "bool", "required": false }, { "name": "category_id", "type": "str", "required": false }, { "name": "difficulty_level", "type": "str", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "TourpackageResponse", "fields": [ { "name": "category_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "duration_days", "type": "int", "required": false }, { "name": "duration_nights", "type": "int", "required": false }, { "name": "difficulty_level", "type": "DifficultyLevel", "required": false, "nullable": true, "enum_values": [ "EASY", "MODERATE", "CHALLENGING", "DIFFICULT" ] }, { "name": "min_age", "type": "int", "required": false, "nullable": true }, { "name": "max_age", "type": "int", "required": false, "nullable": true }, { "name": "min_group_size", "type": "int", "required": false }, { "name": "max_group_size", "type": "int", "required": false }, { "name": "base_price", "type": "float", "required": false }, { "name": "child_price", "type": "float", "required": false, "nullable": true }, { "name": "single_supplement", "type": "float", "required": false, "nullable": true }, { "name": "inclusions", "type": "str", "required": false, "nullable": true }, { "name": "exclusions", "type": "str", "required": false, "nullable": true }, { "name": "terms_and_conditions", "type": "str", "required": false, "nullable": true }, { "name": "cancellation_policy", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "is_featured", "type": "bool", "required": false, "default": false }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_reviews", "type": "int", "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": "/tour-packages/{tourpackage_id}", "summary": "Get Tour Package", "description": "Returns a single tour package by ID. Returns 404 if the tour package does not exist.", "path_params": [ { "name": "tourpackage_id", "type": "str" } ], "response": { "schema_name": "TourpackageResponse", "fields": [ { "name": "category_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "duration_days", "type": "int", "required": false }, { "name": "duration_nights", "type": "int", "required": false }, { "name": "difficulty_level", "type": "DifficultyLevel", "required": false, "nullable": true, "enum_values": [ "EASY", "MODERATE", "CHALLENGING", "DIFFICULT" ] }, { "name": "min_age", "type": "int", "required": false, "nullable": true }, { "name": "max_age", "type": "int", "required": false, "nullable": true }, { "name": "min_group_size", "type": "int", "required": false }, { "name": "max_group_size", "type": "int", "required": false }, { "name": "base_price", "type": "float", "required": false }, { "name": "child_price", "type": "float", "required": false, "nullable": true }, { "name": "single_supplement", "type": "float", "required": false, "nullable": true }, { "name": "inclusions", "type": "str", "required": false, "nullable": true }, { "name": "exclusions", "type": "str", "required": false, "nullable": true }, { "name": "terms_and_conditions", "type": "str", "required": false, "nullable": true }, { "name": "cancellation_policy", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "is_featured", "type": "bool", "required": false, "default": false }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_reviews", "type": "int", "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": "/tour-packages/{tourpackage_id}/details", "summary": "Get Tour Package Details", "description": "Returns a tour package with all related data including category, itineraries, destinations, and amenities. Uses eager loading to prevent N+1 queries. Returns 404 if the tour package does not exist.", "path_params": [ { "name": "tourpackage_id", "type": "str" } ], "response": { "schema_name": "TourpackageDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "category_name", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "slug", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "duration_days", "type": "int", "required": true }, { "name": "duration_nights", "type": "int", "required": true }, { "name": "difficulty_level", "type": "str", "required": false, "nullable": true }, { "name": "min_age", "type": "int", "required": false, "nullable": true }, { "name": "max_age", "type": "int", "required": false, "nullable": true }, { "name": "min_group_size", "type": "int", "required": true }, { "name": "max_group_size", "type": "int", "required": true }, { "name": "base_price", "type": "float", "required": true }, { "name": "child_price", "type": "float", "required": false, "nullable": true }, { "name": "single_supplement", "type": "float", "required": false, "nullable": true }, { "name": "inclusions", "type": "str", "required": false, "nullable": true }, { "name": "exclusions", "type": "str", "required": false, "nullable": true }, { "name": "terms_and_conditions", "type": "str", "required": false, "nullable": true }, { "name": "cancellation_policy", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "is_featured", "type": "bool", "required": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_reviews", "type": "int", "required": true }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "itineraries", "type": "List[ItineraryResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "day_number", "type": "int", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "activities", "type": "str", "required": false, "nullable": true }, { "name": "meals_included", "type": "str", "required": false, "nullable": true }, { "name": "accommodation_type", "type": "str", "required": false, "nullable": true }, { "name": "start_time", "type": "time", "required": false, "nullable": true }, { "name": "end_time", "type": "time", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "destinations", "type": "List[DestinationInPackageResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "country", "type": "str", "required": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "visit_order", "type": "int", "required": true }, { "name": "duration_hours", "type": "int", "required": false, "nullable": true } ] }, { "name": "amenities", "type": "List[AmenityInPackageResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "amenity_type", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/tour-packages/{tourpackage_id}", "summary": "Update Tour Package", "description": "Updates an existing tour package. Validates that the category exists if changed and the slug is unique if changed. Returns 404 if tour package or category not found, 409 if new slug conflicts.", "path_params": [ { "name": "tourpackage_id", "type": "str" } ], "request_body": { "schema_name": "TourpackageUpdate", "fields": [ { "name": "category_id", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "slug", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "duration_days", "type": "int", "required": false, "nullable": true }, { "name": "duration_nights", "type": "int", "required": false, "nullable": true }, { "name": "difficulty_level", "type": "DifficultyLevel", "required": false, "nullable": true, "enum_values": [ "EASY", "MODERATE", "CHALLENGING", "DIFFICULT" ] }, { "name": "min_age", "type": "int", "required": false, "nullable": true }, { "name": "max_age", "type": "int", "required": false, "nullable": true }, { "name": "min_group_size", "type": "int", "required": false, "nullable": true }, { "name": "max_group_size", "type": "int", "required": false, "nullable": true }, { "name": "base_price", "type": "float", "required": false, "nullable": true }, { "name": "child_price", "type": "float", "required": false, "nullable": true }, { "name": "single_supplement", "type": "float", "required": false, "nullable": true }, { "name": "inclusions", "type": "str", "required": false, "nullable": true }, { "name": "exclusions", "type": "str", "required": false, "nullable": true }, { "name": "terms_and_conditions", "type": "str", "required": false, "nullable": true }, { "name": "cancellation_policy", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true }, { "name": "is_featured", "type": "bool", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TourpackageResponse", "fields": [ { "name": "category_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "duration_days", "type": "int", "required": false }, { "name": "duration_nights", "type": "int", "required": false }, { "name": "difficulty_level", "type": "DifficultyLevel", "required": false, "nullable": true, "enum_values": [ "EASY", "MODERATE", "CHALLENGING", "DIFFICULT" ] }, { "name": "min_age", "type": "int", "required": false, "nullable": true }, { "name": "max_age", "type": "int", "required": false, "nullable": true }, { "name": "min_group_size", "type": "int", "required": false }, { "name": "max_group_size", "type": "int", "required": false }, { "name": "base_price", "type": "float", "required": false }, { "name": "child_price", "type": "float", "required": false, "nullable": true }, { "name": "single_supplement", "type": "float", "required": false, "nullable": true }, { "name": "inclusions", "type": "str", "required": false, "nullable": true }, { "name": "exclusions", "type": "str", "required": false, "nullable": true }, { "name": "terms_and_conditions", "type": "str", "required": false, "nullable": true }, { "name": "cancellation_policy", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "is_featured", "type": "bool", "required": false, "default": false }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "rating", "type": "float", "required": false, "nullable": true }, { "name": "total_reviews", "type": "int", "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": "/tour-packages/{tourpackage_id}", "summary": "Delete Tour Package", "description": "Deletes a tour package by ID. Cascades to related itineraries, destinations, and amenities. Returns 404 if the tour package does not exist.", "path_params": [ { "name": "tourpackage_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/tour-package-destinations", "summary": "Create Tour Package Destination", "description": "Associates a destination with a tour package. Validates that both tour package and destination exist. Returns 404 if either not found.", "request_body": { "schema_name": "TourpackagedestinationCreate", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "destination_id", "type": "str", "required": true }, { "name": "visit_order", "type": "int", "required": false }, { "name": "duration_hours", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "TourpackagedestinationResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "destination_id", "type": "str", "required": true }, { "name": "visit_order", "type": "int", "required": false }, { "name": "duration_hours", "type": "int", "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": "/tour-package-destinations", "summary": "List Tour Package Destinations", "description": "Returns a paginated list of tour package destination associations. Supports optional filters for tour package ID and destination ID.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "destination_id", "type": "str", "required": false } ], "response": { "schema_name": "TourpackagedestinationResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "destination_id", "type": "str", "required": true }, { "name": "visit_order", "type": "int", "required": false }, { "name": "duration_hours", "type": "int", "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": "/tour-package-destinations/{tpd_id}", "summary": "Get Tour Package Destination", "description": "Returns a single tour package destination association by ID. Returns 404 if not found.", "path_params": [ { "name": "tpd_id", "type": "str" } ], "response": { "schema_name": "TourpackagedestinationResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "destination_id", "type": "str", "required": true }, { "name": "visit_order", "type": "int", "required": false }, { "name": "duration_hours", "type": "int", "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": "PUT", "path": "/tour-package-destinations/{tpd_id}", "summary": "Update Tour Package Destination", "description": "Updates an existing tour package destination association. Validates that tour package and destination exist if changed. Returns 404 if not found.", "path_params": [ { "name": "tpd_id", "type": "str" } ], "request_body": { "schema_name": "TourpackagedestinationUpdate", "fields": [ { "name": "tour_package_id", "type": "str", "required": false, "nullable": true }, { "name": "destination_id", "type": "str", "required": false, "nullable": true }, { "name": "visit_order", "type": "int", "required": false, "nullable": true }, { "name": "duration_hours", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "TourpackagedestinationResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "destination_id", "type": "str", "required": true }, { "name": "visit_order", "type": "int", "required": false }, { "name": "duration_hours", "type": "int", "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": "/tour-package-destinations/{tpd_id}", "summary": "Delete Tour Package Destination", "description": "Deletes a tour package destination association by ID. Returns 404 if not found.", "path_params": [ { "name": "tpd_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/tour-package-amenities", "summary": "Create Tour Package Amenity", "description": "Associates an amenity with a tour package. Validates that both tour package and amenity exist. Returns 404 if either not found.", "request_body": { "schema_name": "TourpackageamenityCreate", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "amenity_id", "type": "str", "required": true } ] }, "response": { "schema_name": "TourpackageamenityResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "amenity_id", "type": "str", "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": "/tour-package-amenities", "summary": "List Tour Package Amenities", "description": "Returns a paginated list of tour package amenity associations. Supports optional filters for tour package ID and amenity ID.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "amenity_id", "type": "str", "required": false } ], "response": { "schema_name": "TourpackageamenityResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "amenity_id", "type": "str", "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": "/tour-package-amenities/{tpa_id}", "summary": "Get Tour Package Amenity", "description": "Returns a single tour package amenity association by ID. Returns 404 if not found.", "path_params": [ { "name": "tpa_id", "type": "str" } ], "response": { "schema_name": "TourpackageamenityResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "amenity_id", "type": "str", "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": "/tour-package-amenities/{tpa_id}", "summary": "Update Tour Package Amenity", "description": "Updates an existing tour package amenity association. Validates that tour package and amenity exist if changed. Returns 404 if not found.", "path_params": [ { "name": "tpa_id", "type": "str" } ], "request_body": { "schema_name": "TourpackageamenityUpdate", "fields": [ { "name": "tour_package_id", "type": "str", "required": false, "nullable": true }, { "name": "amenity_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TourpackageamenityResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "amenity_id", "type": "str", "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": "/tour-package-amenities/{tpa_id}", "summary": "Delete Tour Package Amenity", "description": "Deletes a tour package amenity association by ID. Returns 404 if not found.", "path_params": [ { "name": "tpa_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/itineraries", "summary": "Create Itinerary", "description": "Creates a new itinerary day for a tour package. Validates that the tour package exists. Returns 404 if tour package not found.", "request_body": { "schema_name": "ItineraryCreate", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "day_number", "type": "int", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "activities", "type": "str", "required": false, "nullable": true }, { "name": "meals_included", "type": "str", "required": false, "nullable": true }, { "name": "accommodation_type", "type": "str", "required": false, "nullable": true }, { "name": "start_time", "type": "time", "required": false, "nullable": true }, { "name": "end_time", "type": "time", "required": false, "nullable": true } ] }, "response": { "schema_name": "ItineraryResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "day_number", "type": "int", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "activities", "type": "str", "required": false, "nullable": true }, { "name": "meals_included", "type": "str", "required": false, "nullable": true }, { "name": "accommodation_type", "type": "str", "required": false, "nullable": true }, { "name": "start_time", "type": "time", "required": false, "nullable": true }, { "name": "end_time", "type": "time", "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": "/itineraries", "summary": "List Itineraries", "description": "Returns a paginated list of itineraries ordered by day number. Supports optional filter for tour package ID.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "tour_package_id", "type": "str", "required": false } ], "response": { "schema_name": "ItineraryResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "day_number", "type": "int", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "activities", "type": "str", "required": false, "nullable": true }, { "name": "meals_included", "type": "str", "required": false, "nullable": true }, { "name": "accommodation_type", "type": "str", "required": false, "nullable": true }, { "name": "start_time", "type": "time", "required": false, "nullable": true }, { "name": "end_time", "type": "time", "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": "/itineraries/{itinerary_id}", "summary": "Get Itinerary", "description": "Returns a single itinerary by ID. Returns 404 if the itinerary does not exist.", "path_params": [ { "name": "itinerary_id", "type": "str" } ], "response": { "schema_name": "ItineraryResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "day_number", "type": "int", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "activities", "type": "str", "required": false, "nullable": true }, { "name": "meals_included", "type": "str", "required": false, "nullable": true }, { "name": "accommodation_type", "type": "str", "required": false, "nullable": true }, { "name": "start_time", "type": "time", "required": false, "nullable": true }, { "name": "end_time", "type": "time", "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": "PUT", "path": "/itineraries/{itinerary_id}", "summary": "Update Itinerary", "description": "Updates an existing itinerary. Validates that the tour package exists if changed. Returns 404 if itinerary or tour package not found.", "path_params": [ { "name": "itinerary_id", "type": "str" } ], "request_body": { "schema_name": "ItineraryUpdate", "fields": [ { "name": "tour_package_id", "type": "str", "required": false, "nullable": true }, { "name": "day_number", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "activities", "type": "str", "required": false, "nullable": true }, { "name": "meals_included", "type": "str", "required": false, "nullable": true }, { "name": "accommodation_type", "type": "str", "required": false, "nullable": true }, { "name": "start_time", "type": "time", "required": false, "nullable": true }, { "name": "end_time", "type": "time", "required": false, "nullable": true } ] }, "response": { "schema_name": "ItineraryResponse", "fields": [ { "name": "tour_package_id", "type": "str", "required": true }, { "name": "day_number", "type": "int", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "activities", "type": "str", "required": false, "nullable": true }, { "name": "meals_included", "type": "str", "required": false, "nullable": true }, { "name": "accommodation_type", "type": "str", "required": false, "nullable": true }, { "name": "start_time", "type": "time", "required": false, "nullable": true }, { "name": "end_time", "type": "time", "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": "/itineraries/{itinerary_id}", "summary": "Delete Itinerary", "description": "Deletes an itinerary by ID. Returns 404 if the itinerary does not exist.", "path_params": [ { "name": "itinerary_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Bookings", "prefix": "/bookings", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Booking", "description": "Creates a new booking for a tour schedule. Validates minimum lead time (48 hours), available slots, and customer/tour schedule existence. Returns 409 if booking number already exists, 400 if validation fails.", "request_body": { "schema_name": "BookingCreate", "fields": [ { "name": "customer_id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": false, "nullable": true }, { "name": "discount_id", "type": "str", "required": false, "nullable": true }, { "name": "number_of_adults", "type": "int", "required": false, "default": 0 }, { "name": "number_of_children", "type": "int", "required": false, "default": 0 }, { "name": "number_of_infants", "type": "int", "required": false, "default": 0 }, { "name": "subtotal", "type": "float", "required": false, "default": 0.0 }, { "name": "discount_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "tax_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "total_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_paid", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_due", "type": "float", "required": false, "default": 0.0 }, { "name": "booking_status", "type": "str", "required": false, "default": "pending" }, { "name": "payment_status", "type": "str", "required": false, "default": "unpaid" }, { "name": "special_requests", "type": "str", "required": false, "nullable": true }, { "name": "booking_number", "type": "str", "required": true } ] }, "response": { "schema_name": "BookingResponse", "fields": [ { "name": "customer_id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": false, "nullable": true }, { "name": "discount_id", "type": "str", "required": false, "nullable": true }, { "name": "number_of_adults", "type": "int", "required": false, "default": 0 }, { "name": "number_of_children", "type": "int", "required": false, "default": 0 }, { "name": "number_of_infants", "type": "int", "required": false, "default": 0 }, { "name": "subtotal", "type": "float", "required": false, "default": 0.0 }, { "name": "discount_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "tax_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "total_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_paid", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_due", "type": "float", "required": false, "default": 0.0 }, { "name": "booking_status", "type": "str", "required": false, "default": "pending" }, { "name": "payment_status", "type": "str", "required": false, "default": "unpaid" }, { "name": "special_requests", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "booking_number", "type": "str", "required": true }, { "name": "booking_date", "type": "datetime", "required": true }, { "name": "cancellation_reason", "type": "str", "required": false, "nullable": true }, { "name": "cancelled_at", "type": "datetime", "required": false, "nullable": 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 Bookings", "description": "Returns a paginated list of bookings. Supports optional filters for customer_id, tour_schedule_id, booking_status, and payment_status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "customer_id", "type": "str", "required": false }, { "name": "tour_schedule_id", "type": "str", "required": false }, { "name": "booking_status", "type": "str", "required": false }, { "name": "payment_status", "type": "str", "required": false } ], "response": { "schema_name": "BookingResponse", "fields": [ { "name": "customer_id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": false, "nullable": true }, { "name": "discount_id", "type": "str", "required": false, "nullable": true }, { "name": "number_of_adults", "type": "int", "required": false, "default": 0 }, { "name": "number_of_children", "type": "int", "required": false, "default": 0 }, { "name": "number_of_infants", "type": "int", "required": false, "default": 0 }, { "name": "subtotal", "type": "float", "required": false, "default": 0.0 }, { "name": "discount_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "tax_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "total_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_paid", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_due", "type": "float", "required": false, "default": 0.0 }, { "name": "booking_status", "type": "str", "required": false, "default": "pending" }, { "name": "payment_status", "type": "str", "required": false, "default": "unpaid" }, { "name": "special_requests", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "booking_number", "type": "str", "required": true }, { "name": "booking_date", "type": "datetime", "required": true }, { "name": "cancellation_reason", "type": "str", "required": false, "nullable": true }, { "name": "cancelled_at", "type": "datetime", "required": false, "nullable": true }, { "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 booking not found.", "path_params": [ { "name": "booking_id", "type": "str" } ], "response": { "schema_name": "BookingResponse", "fields": [ { "name": "customer_id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": false, "nullable": true }, { "name": "discount_id", "type": "str", "required": false, "nullable": true }, { "name": "number_of_adults", "type": "int", "required": false, "default": 0 }, { "name": "number_of_children", "type": "int", "required": false, "default": 0 }, { "name": "number_of_infants", "type": "int", "required": false, "default": 0 }, { "name": "subtotal", "type": "float", "required": false, "default": 0.0 }, { "name": "discount_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "tax_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "total_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_paid", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_due", "type": "float", "required": false, "default": 0.0 }, { "name": "booking_status", "type": "str", "required": false, "default": "pending" }, { "name": "payment_status", "type": "str", "required": false, "default": "unpaid" }, { "name": "special_requests", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "booking_number", "type": "str", "required": true }, { "name": "booking_date", "type": "datetime", "required": true }, { "name": "cancellation_reason", "type": "str", "required": false, "nullable": true }, { "name": "cancelled_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{booking_id}", "summary": "Update Booking", "description": "Updates an existing booking. Validates referenced entities (booking_agent, discount) if provided. Returns 404 if booking not found.", "path_params": [ { "name": "booking_id", "type": "str" } ], "request_body": { "schema_name": "BookingUpdate", "fields": [ { "name": "booking_agent_id", "type": "str", "required": false, "nullable": true }, { "name": "discount_id", "type": "str", "required": false, "nullable": true }, { "name": "number_of_adults", "type": "int", "required": false, "nullable": true }, { "name": "number_of_children", "type": "int", "required": false, "nullable": true }, { "name": "number_of_infants", "type": "int", "required": false, "nullable": true }, { "name": "subtotal", "type": "float", "required": false, "nullable": true }, { "name": "discount_amount", "type": "float", "required": false, "nullable": true }, { "name": "tax_amount", "type": "float", "required": false, "nullable": true }, { "name": "total_amount", "type": "float", "required": false, "nullable": true }, { "name": "amount_paid", "type": "float", "required": false, "nullable": true }, { "name": "amount_due", "type": "float", "required": false, "nullable": true }, { "name": "booking_status", "type": "str", "required": false, "nullable": true }, { "name": "payment_status", "type": "str", "required": false, "nullable": true }, { "name": "special_requests", "type": "str", "required": false, "nullable": true }, { "name": "cancellation_reason", "type": "str", "required": false, "nullable": true }, { "name": "cancelled_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookingResponse", "fields": [ { "name": "customer_id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": false, "nullable": true }, { "name": "discount_id", "type": "str", "required": false, "nullable": true }, { "name": "number_of_adults", "type": "int", "required": false, "default": 0 }, { "name": "number_of_children", "type": "int", "required": false, "default": 0 }, { "name": "number_of_infants", "type": "int", "required": false, "default": 0 }, { "name": "subtotal", "type": "float", "required": false, "default": 0.0 }, { "name": "discount_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "tax_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "total_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_paid", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_due", "type": "float", "required": false, "default": 0.0 }, { "name": "booking_status", "type": "str", "required": false, "default": "pending" }, { "name": "payment_status", "type": "str", "required": false, "default": "unpaid" }, { "name": "special_requests", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "booking_number", "type": "str", "required": true }, { "name": "booking_date", "type": "datetime", "required": true }, { "name": "cancellation_reason", "type": "str", "required": false, "nullable": true }, { "name": "cancelled_at", "type": "datetime", "required": false, "nullable": true }, { "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 by ID. Cascades to related travelers, payments, invoice, and documents. Returns 404 if booking not found.", "path_params": [ { "name": "booking_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{booking_id}/details", "summary": "Get Booking Details", "description": "Returns detailed booking information including customer, tour schedule, tour package, tour guide, booking agent, discount, travelers, payments, and invoice with line items. Uses eager loading to prevent N+1 queries.", "path_params": [ { "name": "booking_id", "type": "str" } ], "response": { "schema_name": "BookingDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_number", "type": "str", "required": true }, { "name": "booking_date", "type": "datetime", "required": true }, { "name": "number_of_adults", "type": "int", "required": true }, { "name": "number_of_children", "type": "int", "required": true }, { "name": "number_of_infants", "type": "int", "required": true }, { "name": "subtotal", "type": "float", "required": true }, { "name": "discount_amount", "type": "float", "required": true }, { "name": "tax_amount", "type": "float", "required": true }, { "name": "total_amount", "type": "float", "required": true }, { "name": "amount_paid", "type": "float", "required": true }, { "name": "amount_due", "type": "float", "required": true }, { "name": "booking_status", "type": "str", "required": true }, { "name": "payment_status", "type": "str", "required": true }, { "name": "special_requests", "type": "str", "required": false, "nullable": true }, { "name": "customer", "type": "CustomerDetailResponse", "required": true, "fields": [ { "name": "user", "type": "CustomerUserResponse", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] } ] }, { "name": "tour_schedule", "type": "TourScheduleDetailResponse", "required": true, "fields": [ { "name": "tour_package", "type": "TourPackageResponse", "required": true, "fields": [ { "name": "name", "type": "str", "required": true } ] }, { "name": "tour_guide", "type": "TourGuideDetailResponse", "required": false, "nullable": true, "fields": [ { "name": "user", "type": "TourGuideUserResponse", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] } ] }, { "name": "booking_agent", "type": "BookingAgentResponse", "required": false, "nullable": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] }, { "name": "discount", "type": "DiscountResponse", "required": false, "nullable": true, "fields": [ { "name": "code", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "discount_type", "type": "DiscountType", "required": true, "enum_values": [ "PERCENTAGE", "FIXED_AMOUNT", "EARLY_BIRD", "GROUP", "LOYALTY" ] }, { "name": "discount_value", "type": "Decimal", "required": true }, { "name": "min_booking_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "max_discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "min_travelers", "type": "int", "required": false, "nullable": true }, { "name": "applicable_tour_package_id", "type": "str", "required": false, "nullable": true }, { "name": "valid_from", "type": "date", "required": true }, { "name": "valid_to", "type": "date", "required": true }, { "name": "usage_limit", "type": "int", "required": false, "nullable": true }, { "name": "usage_count", "type": "int", "required": false, "default": 0 }, { "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 } ] }, { "name": "travelers", "type": "List[TravelerResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "traveler_type", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "str", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "passport_number", "type": "str", "required": false, "nullable": true }, { "name": "passport_expiry", "type": "date", "required": false, "nullable": true }, { "name": "special_requirements", "type": "str", "required": false, "nullable": true }, { "name": "meal_preference", "type": "str", "required": false, "nullable": true }, { "name": "is_primary", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "payments", "type": "List[PaymentDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "amount", "type": "float", "required": true }, { "name": "payment_status", "type": "str", "required": true } ] }, { "name": "invoice", "type": "InvoiceDetailResponse", "required": false, "nullable": true, "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "invoice_number", "type": "str", "required": true }, { "name": "invoice_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "subtotal", "type": "Decimal", "required": true }, { "name": "tax_amount", "type": "Decimal", "required": true }, { "name": "discount_amount", "type": "Decimal", "required": true }, { "name": "total_amount", "type": "Decimal", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "terms", "type": "str", "required": false, "nullable": true }, { "name": "invoice_status", "type": "InvoiceStatus", "required": true, "enum_values": [ "DRAFT", "SENT", "PAID", "OVERDUE", "CANCELLED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "invoice_line_items", "type": "List[InvoicelineitemResponse]", "required": false, "is_list": true, "item_fields": [ { "name": "invoice_id", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "unit_price", "type": "Decimal", "required": true }, { "name": "total_price", "type": "Decimal", "required": true }, { "name": "item_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] } ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{booking_id}/confirm", "summary": "Confirm Booking", "description": "Confirms a pending booking and updates tour schedule capacity. Validates available slots and booking status. Returns 400 if booking is not pending or insufficient slots available.", "path_params": [ { "name": "booking_id", "type": "str" } ], "response": { "schema_name": "BookingResponse", "fields": [ { "name": "customer_id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": false, "nullable": true }, { "name": "discount_id", "type": "str", "required": false, "nullable": true }, { "name": "number_of_adults", "type": "int", "required": false, "default": 0 }, { "name": "number_of_children", "type": "int", "required": false, "default": 0 }, { "name": "number_of_infants", "type": "int", "required": false, "default": 0 }, { "name": "subtotal", "type": "float", "required": false, "default": 0.0 }, { "name": "discount_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "tax_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "total_amount", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_paid", "type": "float", "required": false, "default": 0.0 }, { "name": "amount_due", "type": "float", "required": false, "default": 0.0 }, { "name": "booking_status", "type": "str", "required": false, "default": "pending" }, { "name": "payment_status", "type": "str", "required": false, "default": "unpaid" }, { "name": "special_requests", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "booking_number", "type": "str", "required": true }, { "name": "booking_date", "type": "datetime", "required": true }, { "name": "cancellation_reason", "type": "str", "required": false, "nullable": true }, { "name": "cancelled_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Service Provider Management", "prefix": "/service-providers", "endpoints": [ { "method": "POST", "path": "/hotels", "summary": "Create Hotel", "description": "Creates a new hotel record for a service provider. Validates that the service provider exists and returns 404 if not found.", "request_body": { "schema_name": "HotelCreate", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "star_rating", "type": "int", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "check_in_time", "type": "time", "required": false, "nullable": true }, { "name": "check_out_time", "type": "time", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "policies", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "HotelResponse", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "star_rating", "type": "int", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "check_in_time", "type": "time", "required": false, "nullable": true }, { "name": "check_out_time", "type": "time", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "policies", "type": "str", "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": "/hotels/{hotel_id}", "summary": "Get Hotel By ID", "description": "Retrieves a single hotel record by its unique identifier. Returns 404 if the hotel does not exist.", "path_params": [ { "name": "hotel_id", "type": "str" } ], "response": { "schema_name": "HotelResponse", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "star_rating", "type": "int", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "check_in_time", "type": "time", "required": false, "nullable": true }, { "name": "check_out_time", "type": "time", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "policies", "type": "str", "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": "GET", "path": "/hotels", "summary": "List Hotels", "description": "Returns a paginated list of hotels. Supports optional filters for service provider ID and active status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "service_provider_id", "type": "str", "required": false }, { "name": "is_active", "type": "bool", "required": false } ], "response": { "schema_name": "HotelResponse", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "star_rating", "type": "int", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "check_in_time", "type": "time", "required": false, "nullable": true }, { "name": "check_out_time", "type": "time", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "policies", "type": "str", "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": "PUT", "path": "/hotels/{hotel_id}", "summary": "Update Hotel", "description": "Updates an existing hotel record. Only provided fields are updated. Returns 404 if the hotel or referenced service provider does not exist.", "path_params": [ { "name": "hotel_id", "type": "str" } ], "request_body": { "schema_name": "HotelUpdate", "fields": [ { "name": "service_provider_id", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "star_rating", "type": "int", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "check_in_time", "type": "time", "required": false, "nullable": true }, { "name": "check_out_time", "type": "time", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "policies", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "HotelResponse", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "star_rating", "type": "int", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "check_in_time", "type": "time", "required": false, "nullable": true }, { "name": "check_out_time", "type": "time", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "policies", "type": "str", "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": "/hotels/{hotel_id}", "summary": "Delete Hotel", "description": "Deletes a hotel record by ID. Cascades to delete associated room types and hotel amenities. Returns 404 if the hotel does not exist.", "path_params": [ { "name": "hotel_id", "type": "str" } ], "status_code": 204 }, { "method": "GET", "path": "/hotels/{hotel_id}/details", "summary": "Get Hotel Details", "description": "Retrieves detailed hotel information including service provider details, room types, and amenities. All related data is eagerly loaded. Returns 404 if the hotel does not exist.", "path_params": [ { "name": "hotel_id", "type": "str" } ], "response": { "schema_name": "HotelDetailResponse", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "star_rating", "type": "int", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "latitude", "type": "float", "required": false, "nullable": true }, { "name": "longitude", "type": "float", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "check_in_time", "type": "time", "required": false, "nullable": true }, { "name": "check_out_time", "type": "time", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "policies", "type": "str", "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 }, { "name": "service_provider", "type": "ServiceProviderResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "service_type", "type": "str", "required": true }, { "name": "contact_email", "type": "str", "required": false, "nullable": true } ] }, { "name": "room_types", "type": "List[RoomtypeResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "max_occupancy", "type": "int", "required": true }, { "name": "bed_configuration", "type": "str", "required": false, "nullable": true }, { "name": "room_size_sqm", "type": "float", "required": false, "nullable": true }, { "name": "price_per_night", "type": "float", "required": true }, { "name": "total_rooms", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "hotel_amenities", "type": "List[HotelAmenityDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "str", "required": true }, { "name": "amenity", "type": "AmenityResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "amenity_type", "type": "str", "required": true } ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/hotel-amenities", "summary": "Create Hotel Amenity Association", "description": "Associates an amenity with a hotel. Validates that both the hotel and amenity exist. Returns 409 if the association already exists.", "request_body": { "schema_name": "HotelamenityCreate", "fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "amenity_id", "type": "str", "required": true } ] }, "response": { "schema_name": "HotelamenityResponse", "fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "amenity_id", "type": "str", "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": "/hotel-amenities/{hotel_amenity_id}", "summary": "Get Hotel Amenity By ID", "description": "Retrieves a single hotel amenity association by its unique identifier. Returns 404 if not found.", "path_params": [ { "name": "hotel_amenity_id", "type": "str" } ], "response": { "schema_name": "HotelamenityResponse", "fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "amenity_id", "type": "str", "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": "/hotel-amenities", "summary": "List Hotel Amenities", "description": "Returns a paginated list of hotel amenity associations. Supports optional filter by hotel ID.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "hotel_id", "type": "str", "required": false } ], "response": { "schema_name": "HotelamenityResponse", "fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "amenity_id", "type": "str", "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": "DELETE", "path": "/hotel-amenities/{hotel_amenity_id}", "summary": "Delete Hotel Amenity Association", "description": "Removes an amenity association from a hotel. Returns 404 if the association does not exist.", "path_params": [ { "name": "hotel_amenity_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/room-types", "summary": "Create Room Type", "description": "Creates a new room type for a hotel. Validates that the hotel exists and that capacity, price, and total rooms are positive. Returns 404 if the hotel does not exist.", "request_body": { "schema_name": "RoomtypeCreate", "fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "max_occupancy", "type": "int", "required": true }, { "name": "bed_configuration", "type": "str", "required": false, "nullable": true }, { "name": "room_size_sqm", "type": "float", "required": false, "nullable": true }, { "name": "price_per_night", "type": "float", "required": true }, { "name": "total_rooms", "type": "int", "required": true } ] }, "response": { "schema_name": "RoomtypeResponse", "fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "max_occupancy", "type": "int", "required": true }, { "name": "bed_configuration", "type": "str", "required": false, "nullable": true }, { "name": "room_size_sqm", "type": "float", "required": false, "nullable": true }, { "name": "price_per_night", "type": "float", "required": true }, { "name": "total_rooms", "type": "int", "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": "/room-types/{room_type_id}", "summary": "Get Room Type By ID", "description": "Retrieves a single room type record by its unique identifier. Returns 404 if not found.", "path_params": [ { "name": "room_type_id", "type": "str" } ], "response": { "schema_name": "RoomtypeResponse", "fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "max_occupancy", "type": "int", "required": true }, { "name": "bed_configuration", "type": "str", "required": false, "nullable": true }, { "name": "room_size_sqm", "type": "float", "required": false, "nullable": true }, { "name": "price_per_night", "type": "float", "required": true }, { "name": "total_rooms", "type": "int", "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": "/room-types", "summary": "List Room Types", "description": "Returns a paginated list of room types. Supports optional filter by hotel ID.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "hotel_id", "type": "str", "required": false } ], "response": { "schema_name": "RoomtypeResponse", "fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "max_occupancy", "type": "int", "required": true }, { "name": "bed_configuration", "type": "str", "required": false, "nullable": true }, { "name": "room_size_sqm", "type": "float", "required": false, "nullable": true }, { "name": "price_per_night", "type": "float", "required": true }, { "name": "total_rooms", "type": "int", "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": "PUT", "path": "/room-types/{room_type_id}", "summary": "Update Room Type", "description": "Updates an existing room type record. Only provided fields are updated. Returns 404 if the room type or referenced hotel does not exist.", "path_params": [ { "name": "room_type_id", "type": "str" } ], "request_body": { "schema_name": "RoomtypeUpdate", "fields": [ { "name": "hotel_id", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "max_occupancy", "type": "int", "required": false, "nullable": true }, { "name": "bed_configuration", "type": "str", "required": false, "nullable": true }, { "name": "room_size_sqm", "type": "float", "required": false, "nullable": true }, { "name": "price_per_night", "type": "float", "required": false, "nullable": true }, { "name": "total_rooms", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "RoomtypeResponse", "fields": [ { "name": "hotel_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "max_occupancy", "type": "int", "required": true }, { "name": "bed_configuration", "type": "str", "required": false, "nullable": true }, { "name": "room_size_sqm", "type": "float", "required": false, "nullable": true }, { "name": "price_per_night", "type": "float", "required": true }, { "name": "total_rooms", "type": "int", "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": "/room-types/{room_type_id}", "summary": "Delete Room Type", "description": "Deletes a room type record by ID. Returns 404 if the room type does not exist.", "path_params": [ { "name": "room_type_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/transportations", "summary": "Create Transportation", "description": "Creates a new transportation service for a service provider. Validates that the service provider exists and that capacity is positive. Returns 404 if the service provider does not exist.", "request_body": { "schema_name": "TransportationCreate", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "transport_type", "type": "TransportType", "required": true, "enum_values": [ "BUS", "FLIGHT", "TRAIN", "CAR", "BOAT", "OTHER" ] }, { "name": "vehicle_name", "type": "str", "required": false, "nullable": true }, { "name": "vehicle_number", "type": "str", "required": false, "nullable": true }, { "name": "capacity", "type": "int", "required": true }, { "name": "amenities", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "TransportationResponse", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "transport_type", "type": "TransportType", "required": true, "enum_values": [ "BUS", "FLIGHT", "TRAIN", "CAR", "BOAT", "OTHER" ] }, { "name": "vehicle_name", "type": "str", "required": false, "nullable": true }, { "name": "vehicle_number", "type": "str", "required": false, "nullable": true }, { "name": "capacity", "type": "int", "required": true }, { "name": "amenities", "type": "str", "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": "/transportations/{transportation_id}", "summary": "Get Transportation By ID", "description": "Retrieves a single transportation record by its unique identifier. Returns 404 if not found.", "path_params": [ { "name": "transportation_id", "type": "str" } ], "response": { "schema_name": "TransportationResponse", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "transport_type", "type": "TransportType", "required": true, "enum_values": [ "BUS", "FLIGHT", "TRAIN", "CAR", "BOAT", "OTHER" ] }, { "name": "vehicle_name", "type": "str", "required": false, "nullable": true }, { "name": "vehicle_number", "type": "str", "required": false, "nullable": true }, { "name": "capacity", "type": "int", "required": true }, { "name": "amenities", "type": "str", "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": "GET", "path": "/transportations", "summary": "List Transportations", "description": "Returns a paginated list of transportation services. Supports optional filters for service provider ID, transport type, and active status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "service_provider_id", "type": "str", "required": false }, { "name": "transport_type", "type": "TransportType", "required": false }, { "name": "is_active", "type": "bool", "required": false } ], "response": { "schema_name": "TransportationResponse", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "transport_type", "type": "TransportType", "required": true, "enum_values": [ "BUS", "FLIGHT", "TRAIN", "CAR", "BOAT", "OTHER" ] }, { "name": "vehicle_name", "type": "str", "required": false, "nullable": true }, { "name": "vehicle_number", "type": "str", "required": false, "nullable": true }, { "name": "capacity", "type": "int", "required": true }, { "name": "amenities", "type": "str", "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": "PUT", "path": "/transportations/{transportation_id}", "summary": "Update Transportation", "description": "Updates an existing transportation record. Only provided fields are updated. Returns 404 if the transportation or referenced service provider does not exist.", "path_params": [ { "name": "transportation_id", "type": "str" } ], "request_body": { "schema_name": "TransportationUpdate", "fields": [ { "name": "service_provider_id", "type": "str", "required": false, "nullable": true }, { "name": "transport_type", "type": "TransportType", "required": false, "nullable": true, "enum_values": [ "BUS", "FLIGHT", "TRAIN", "CAR", "BOAT", "OTHER" ] }, { "name": "vehicle_name", "type": "str", "required": false, "nullable": true }, { "name": "vehicle_number", "type": "str", "required": false, "nullable": true }, { "name": "capacity", "type": "int", "required": false, "nullable": true }, { "name": "amenities", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "TransportationResponse", "fields": [ { "name": "service_provider_id", "type": "str", "required": true }, { "name": "transport_type", "type": "TransportType", "required": true, "enum_values": [ "BUS", "FLIGHT", "TRAIN", "CAR", "BOAT", "OTHER" ] }, { "name": "vehicle_name", "type": "str", "required": false, "nullable": true }, { "name": "vehicle_number", "type": "str", "required": false, "nullable": true }, { "name": "capacity", "type": "int", "required": true }, { "name": "amenities", "type": "str", "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": "/transportations/{transportation_id}", "summary": "Delete Transportation", "description": "Deletes a transportation record by ID. Returns 404 if the transportation does not exist.", "path_params": [ { "name": "transportation_id", "type": "str" } ], "status_code": 204 } ] }, { "name": "Payment Management", "prefix": "/payments", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Payment", "description": "Creates a new payment record for a booking. Validates that the booking exists and the payment amount is greater than zero. Returns 404 if the booking is not found.", "request_body": { "schema_name": "PaymentCreate", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "BANK_TRANSFER", "CASH", "PAYPAL", "STRIPE", "OTHER" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "payment_status", "type": "TransactionStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "payment_date", "type": "datetime", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "gateway_response", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "BANK_TRANSFER", "CASH", "PAYPAL", "STRIPE", "OTHER" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "payment_status", "type": "TransactionStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "payment_date", "type": "datetime", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "gateway_response", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "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": "/{payment_id}", "summary": "Get Payment", "description": "Retrieves a single payment record by ID. Returns 404 if the payment is not found.", "path_params": [ { "name": "payment_id", "type": "str" } ], "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "BANK_TRANSFER", "CASH", "PAYPAL", "STRIPE", "OTHER" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "payment_status", "type": "TransactionStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "payment_date", "type": "datetime", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "gateway_response", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "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": "/", "summary": "List Payments", "description": "Returns a paginated list of payments. Supports optional filters for booking_id, payment_status, and payment_method.", "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 }, { "name": "payment_status", "type": "str", "required": false }, { "name": "payment_method", "type": "str", "required": false } ], "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "BANK_TRANSFER", "CASH", "PAYPAL", "STRIPE", "OTHER" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "payment_status", "type": "TransactionStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "payment_date", "type": "datetime", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "gateway_response", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "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": "PUT", "path": "/{payment_id}", "summary": "Update Payment", "description": "Updates an existing payment record. Validates that the booking exists if booking_id is updated. Returns 404 if the payment or booking is not found.", "path_params": [ { "name": "payment_id", "type": "str" } ], "request_body": { "schema_name": "PaymentUpdate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "payment_method", "type": "PaymentMethod", "required": false, "nullable": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "BANK_TRANSFER", "CASH", "PAYPAL", "STRIPE", "OTHER" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false, "nullable": true }, { "name": "payment_status", "type": "TransactionStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "payment_date", "type": "datetime", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "gateway_response", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "BANK_TRANSFER", "CASH", "PAYPAL", "STRIPE", "OTHER" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "payment_status", "type": "TransactionStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED" ] }, { "name": "payment_date", "type": "datetime", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "gateway_response", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "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": "/{payment_id}", "summary": "Delete Payment", "description": "Deletes a payment record by ID. Returns 404 if the payment is not found.", "path_params": [ { "name": "payment_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Reviews", "prefix": "/reviews", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Review", "description": "Creates a new review for a completed booking. Validates that the booking exists, is completed, and does not already have a review. Returns 404 if booking, customer, tour package, or tour guide not found. Returns 400 if booking is not completed. Returns 409 if review already exists for the booking.", "request_body": { "schema_name": "ReviewCreate", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "tour_guide_id", "type": "str", "required": false, "nullable": true }, { "name": "overall_rating", "type": "int", "required": false }, { "name": "guide_rating", "type": "int", "required": false, "nullable": true }, { "name": "accommodation_rating", "type": "int", "required": false, "nullable": true }, { "name": "transportation_rating", "type": "int", "required": false, "nullable": true }, { "name": "value_for_money_rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "photos", "type": "List[str]", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "default": true }, { "name": "is_published", "type": "bool", "required": false, "default": false }, { "name": "management_response", "type": "str", "required": false, "nullable": true }, { "name": "response_date", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "tour_guide_id", "type": "str", "required": false, "nullable": true }, { "name": "overall_rating", "type": "int", "required": false }, { "name": "guide_rating", "type": "int", "required": false, "nullable": true }, { "name": "accommodation_rating", "type": "int", "required": false, "nullable": true }, { "name": "transportation_rating", "type": "int", "required": false, "nullable": true }, { "name": "value_for_money_rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "photos", "type": "List[str]", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "default": true }, { "name": "is_published", "type": "bool", "required": false, "default": false }, { "name": "management_response", "type": "str", "required": false, "nullable": true }, { "name": "response_date", "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 Reviews", "description": "Returns a paginated list of reviews. Supports optional filters for customer_id, tour_package_id, tour_guide_id, is_published, and is_verified. 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": "customer_id", "type": "str", "required": false }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "tour_guide_id", "type": "str", "required": false }, { "name": "is_published", "type": "bool", "required": false }, { "name": "is_verified", "type": "bool", "required": false } ], "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "tour_guide_id", "type": "str", "required": false, "nullable": true }, { "name": "overall_rating", "type": "int", "required": false }, { "name": "guide_rating", "type": "int", "required": false, "nullable": true }, { "name": "accommodation_rating", "type": "int", "required": false, "nullable": true }, { "name": "transportation_rating", "type": "int", "required": false, "nullable": true }, { "name": "value_for_money_rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "photos", "type": "List[str]", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "default": true }, { "name": "is_published", "type": "bool", "required": false, "default": false }, { "name": "management_response", "type": "str", "required": false, "nullable": true }, { "name": "response_date", "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 Review", "description": "Returns a single review by ID. Returns 404 if review not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "tour_guide_id", "type": "str", "required": false, "nullable": true }, { "name": "overall_rating", "type": "int", "required": false }, { "name": "guide_rating", "type": "int", "required": false, "nullable": true }, { "name": "accommodation_rating", "type": "int", "required": false, "nullable": true }, { "name": "transportation_rating", "type": "int", "required": false, "nullable": true }, { "name": "value_for_money_rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "photos", "type": "List[str]", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "default": true }, { "name": "is_published", "type": "bool", "required": false, "default": false }, { "name": "management_response", "type": "str", "required": false, "nullable": true }, { "name": "response_date", "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 Review Details", "description": "Returns detailed review information including customer name, tour package name, tour guide name, and booking number. Uses eager loading to minimize database queries. Returns 404 if review not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ReviewDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "customer_id", "type": "str", "required": true }, { "name": "tour_package_id", "type": "str", "required": true }, { "name": "tour_guide_id", "type": "str", "required": false, "nullable": true }, { "name": "overall_rating", "type": "int", "required": true }, { "name": "guide_rating", "type": "int", "required": false, "nullable": true }, { "name": "accommodation_rating", "type": "int", "required": false, "nullable": true }, { "name": "transportation_rating", "type": "int", "required": false, "nullable": true }, { "name": "value_for_money_rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "photos", "type": "List[str]", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": true }, { "name": "is_published", "type": "bool", "required": true }, { "name": "management_response", "type": "str", "required": false, "nullable": true }, { "name": "response_date", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "customer_first_name", "type": "str", "required": true }, { "name": "customer_last_name", "type": "str", "required": true }, { "name": "tour_package_name", "type": "str", "required": true }, { "name": "tour_guide_first_name", "type": "str", "required": false, "nullable": true }, { "name": "tour_guide_last_name", "type": "str", "required": false, "nullable": true }, { "name": "booking_number", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Review", "description": "Updates an existing review. All fields are optional. Validates foreign key references if they are being updated. Returns 404 if review or any referenced entity not found.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "ReviewUpdate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "tour_package_id", "type": "str", "required": false, "nullable": true }, { "name": "tour_guide_id", "type": "str", "required": false, "nullable": true }, { "name": "overall_rating", "type": "int", "required": false, "nullable": true }, { "name": "guide_rating", "type": "int", "required": false, "nullable": true }, { "name": "accommodation_rating", "type": "int", "required": false, "nullable": true }, { "name": "transportation_rating", "type": "int", "required": false, "nullable": true }, { "name": "value_for_money_rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "photos", "type": "List[str]", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "nullable": true }, { "name": "is_published", "type": "bool", "required": false, "nullable": true }, { "name": "management_response", "type": "str", "required": false, "nullable": true }, { "name": "response_date", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "tour_guide_id", "type": "str", "required": false, "nullable": true }, { "name": "overall_rating", "type": "int", "required": false }, { "name": "guide_rating", "type": "int", "required": false, "nullable": true }, { "name": "accommodation_rating", "type": "int", "required": false, "nullable": true }, { "name": "transportation_rating", "type": "int", "required": false, "nullable": true }, { "name": "value_for_money_rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "photos", "type": "List[str]", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "default": true }, { "name": "is_published", "type": "bool", "required": false, "default": false }, { "name": "management_response", "type": "str", "required": false, "nullable": true }, { "name": "response_date", "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 Review", "description": "Deletes a review by ID. Returns 404 if review not found.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{id}/publish", "summary": "Publish Review", "description": "Publishes a review making it visible to the public. Returns 400 if review is already published. Returns 404 if review not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "tour_guide_id", "type": "str", "required": false, "nullable": true }, { "name": "overall_rating", "type": "int", "required": false }, { "name": "guide_rating", "type": "int", "required": false, "nullable": true }, { "name": "accommodation_rating", "type": "int", "required": false, "nullable": true }, { "name": "transportation_rating", "type": "int", "required": false, "nullable": true }, { "name": "value_for_money_rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "photos", "type": "List[str]", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "default": true }, { "name": "is_published", "type": "bool", "required": false, "default": false }, { "name": "management_response", "type": "str", "required": false, "nullable": true }, { "name": "response_date", "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": "POST", "path": "/{id}/respond", "summary": "Respond To Review", "description": "Adds a management response to a published review and records the response timestamp. Returns 400 if review is not published. Returns 404 if review not found.", "path_params": [ { "name": "id", "type": "str" } ], "query_params": [ { "name": "response_text", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "tour_package_id", "type": "str", "required": false }, { "name": "tour_guide_id", "type": "str", "required": false, "nullable": true }, { "name": "overall_rating", "type": "int", "required": false }, { "name": "guide_rating", "type": "int", "required": false, "nullable": true }, { "name": "accommodation_rating", "type": "int", "required": false, "nullable": true }, { "name": "transportation_rating", "type": "int", "required": false, "nullable": true }, { "name": "value_for_money_rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "photos", "type": "List[str]", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "default": true }, { "name": "is_published", "type": "bool", "required": false, "default": false }, { "name": "management_response", "type": "str", "required": false, "nullable": true }, { "name": "response_date", "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 } ] }, { "name": "Cancellation Requests", "prefix": "/cancellation-requests", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Cancellation Request", "description": "Creates a new cancellation request for a booking. Validates that the booking exists, belongs to the customer, is not already cancelled, and that no pending or approved cancellation request exists. Returns 400 if validation fails, 404 if booking or customer not found, 409 if a conflicting cancellation request exists.", "request_body": { "schema_name": "CancellationrequestCreate", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "reason", "type": "str", "required": false }, { "name": "requested_date", "type": "datetime", "required": true }, { "name": "cancellation_fee", "type": "Decimal", "required": false }, { "name": "refund_amount", "type": "Decimal", "required": false }, { "name": "status", "type": "CancellationRequestStatus", "required": false, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ] }, { "name": "processed_by", "type": "str", "required": false, "nullable": true }, { "name": "processed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "admin_notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CancellationrequestResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "reason", "type": "str", "required": false }, { "name": "requested_date", "type": "datetime", "required": true }, { "name": "cancellation_fee", "type": "Decimal", "required": false }, { "name": "refund_amount", "type": "Decimal", "required": false }, { "name": "status", "type": "CancellationRequestStatus", "required": false, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ] }, { "name": "processed_by", "type": "str", "required": false, "nullable": true }, { "name": "processed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "admin_notes", "type": "str", "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 Cancellation Requests", "description": "Returns a paginated list of cancellation requests. Supports optional filters for status, customer_id, and booking_id. 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": "status_filter", "type": "CancellationRequestStatus", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "booking_id", "type": "str", "required": false } ], "response": { "schema_name": "CancellationrequestResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "reason", "type": "str", "required": false }, { "name": "requested_date", "type": "datetime", "required": true }, { "name": "cancellation_fee", "type": "Decimal", "required": false }, { "name": "refund_amount", "type": "Decimal", "required": false }, { "name": "status", "type": "CancellationRequestStatus", "required": false, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ] }, { "name": "processed_by", "type": "str", "required": false, "nullable": true }, { "name": "processed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "admin_notes", "type": "str", "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 Request", "description": "Returns a single cancellation request by ID. Returns 404 if the cancellation request does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "CancellationrequestResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "reason", "type": "str", "required": false }, { "name": "requested_date", "type": "datetime", "required": true }, { "name": "cancellation_fee", "type": "Decimal", "required": false }, { "name": "refund_amount", "type": "Decimal", "required": false }, { "name": "status", "type": "CancellationRequestStatus", "required": false, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ] }, { "name": "processed_by", "type": "str", "required": false, "nullable": true }, { "name": "processed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "admin_notes", "type": "str", "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 Request Details", "description": "Returns detailed information about a cancellation request including related booking, customer, and processor information. Uses eager loading to minimize database queries. Returns 404 if the cancellation request does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "CancellationrequestDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "customer_id", "type": "str", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "requested_date", "type": "datetime", "required": true }, { "name": "cancellation_fee", "type": "Decimal", "required": true }, { "name": "refund_amount", "type": "Decimal", "required": true }, { "name": "status", "type": "CancellationRequestStatus", "required": true, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ] }, { "name": "processed_by", "type": "str", "required": false, "nullable": true }, { "name": "processed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "admin_notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "booking", "type": "dict", "required": false, "nullable": true }, { "name": "customer", "type": "dict", "required": false, "nullable": true }, { "name": "processor", "type": "dict", "required": false, "nullable": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Cancellation Request", "description": "Updates an existing cancellation request. Validates that referenced booking, customer, and processor exist if those fields are being updated. Returns 400 if validation fails, 404 if the cancellation request or referenced entities do not exist.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "CancellationrequestUpdate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "requested_date", "type": "datetime", "required": false, "nullable": true }, { "name": "cancellation_fee", "type": "Decimal", "required": false, "nullable": true }, { "name": "refund_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "status", "type": "CancellationRequestStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ] }, { "name": "processed_by", "type": "str", "required": false, "nullable": true }, { "name": "processed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "admin_notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CancellationrequestResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "reason", "type": "str", "required": false }, { "name": "requested_date", "type": "datetime", "required": true }, { "name": "cancellation_fee", "type": "Decimal", "required": false }, { "name": "refund_amount", "type": "Decimal", "required": false }, { "name": "status", "type": "CancellationRequestStatus", "required": false, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ] }, { "name": "processed_by", "type": "str", "required": false, "nullable": true }, { "name": "processed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "admin_notes", "type": "str", "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 Request", "description": "Deletes a cancellation request. Only pending cancellation requests can be deleted. Returns 400 if the request is not pending, 404 if the cancellation request does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{id}/approve", "summary": "Approve Cancellation Request", "description": "Approves a pending cancellation request. Updates the status to approved, records the processor and processing date, and optionally stores admin notes. Returns 400 if the request is not pending, 404 if the cancellation request or processor does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "query_params": [ { "name": "processed_by", "type": "str", "required": false, "default": null }, { "name": "admin_notes", "type": "str", "required": false } ], "response": { "schema_name": "CancellationrequestResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "reason", "type": "str", "required": false }, { "name": "requested_date", "type": "datetime", "required": true }, { "name": "cancellation_fee", "type": "Decimal", "required": false }, { "name": "refund_amount", "type": "Decimal", "required": false }, { "name": "status", "type": "CancellationRequestStatus", "required": false, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ] }, { "name": "processed_by", "type": "str", "required": false, "nullable": true }, { "name": "processed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "admin_notes", "type": "str", "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": "POST", "path": "/{id}/reject", "summary": "Reject Cancellation Request", "description": "Rejects a pending cancellation request. Updates the status to rejected, records the processor and processing date, and optionally stores admin notes. Returns 400 if the request is not pending, 404 if the cancellation request or processor does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "query_params": [ { "name": "processed_by", "type": "str", "required": false, "default": null }, { "name": "admin_notes", "type": "str", "required": false } ], "response": { "schema_name": "CancellationrequestResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "reason", "type": "str", "required": false }, { "name": "requested_date", "type": "datetime", "required": true }, { "name": "cancellation_fee", "type": "Decimal", "required": false }, { "name": "refund_amount", "type": "Decimal", "required": false }, { "name": "status", "type": "CancellationRequestStatus", "required": false, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ] }, { "name": "processed_by", "type": "str", "required": false, "nullable": true }, { "name": "processed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "admin_notes", "type": "str", "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 } ] }, { "name": "Financial Management", "prefix": "/financial", "endpoints": [ { "method": "POST", "path": "/expenses", "summary": "Create Expense", "description": "Creates a new expense record for a tour schedule or general operational cost. Validates that the submitter user exists and the tour schedule exists if provided. Returns 404 if referenced entities are not found.", "request_body": { "schema_name": "ExpenseCreate", "fields": [ { "name": "tour_schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "category", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "currency", "type": "str", "required": false }, { "name": "vendor_name", "type": "str", "required": false, "nullable": true }, { "name": "expense_date", "type": "date", "required": true }, { "name": "payment_method", "type": "str", "required": false, "nullable": true }, { "name": "receipt_url", "type": "str", "required": false, "nullable": true }, { "name": "submitted_by", "type": "str", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "ExpenseResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "category", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "vendor_name", "type": "str", "required": false, "nullable": true }, { "name": "expense_date", "type": "date", "required": true }, { "name": "payment_method", "type": "str", "required": false, "nullable": true }, { "name": "receipt_url", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "submitted_by", "type": "str", "required": true }, { "name": "approved_by", "type": "str", "required": false, "nullable": true }, { "name": "approval_date", "type": "datetime", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/expenses/{expense_id}", "summary": "Get Expense By ID", "description": "Retrieves a single expense record by its unique identifier. Returns 404 if the expense does not exist.", "path_params": [ { "name": "expense_id", "type": "str" } ], "response": { "schema_name": "ExpenseResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "category", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "vendor_name", "type": "str", "required": false, "nullable": true }, { "name": "expense_date", "type": "date", "required": true }, { "name": "payment_method", "type": "str", "required": false, "nullable": true }, { "name": "receipt_url", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "submitted_by", "type": "str", "required": true }, { "name": "approved_by", "type": "str", "required": false, "nullable": true }, { "name": "approval_date", "type": "datetime", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/expenses", "summary": "List Expenses", "description": "Returns a paginated list of expense records. Supports optional filters for status, tour schedule, and submitter. 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": "status_filter", "type": "ExpenseStatus", "required": false }, { "name": "tour_schedule_id", "type": "str", "required": false }, { "name": "submitted_by", "type": "str", "required": false } ], "response": { "schema_name": "ExpenseResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "category", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "vendor_name", "type": "str", "required": false, "nullable": true }, { "name": "expense_date", "type": "date", "required": true }, { "name": "payment_method", "type": "str", "required": false, "nullable": true }, { "name": "receipt_url", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "submitted_by", "type": "str", "required": true }, { "name": "approved_by", "type": "str", "required": false, "nullable": true }, { "name": "approval_date", "type": "datetime", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/expenses/{expense_id}", "summary": "Update Expense", "description": "Updates an existing expense record. Only provided fields are updated. Validates that referenced users and tour schedules exist. Returns 404 if the expense or referenced entities are not found.", "path_params": [ { "name": "expense_id", "type": "str" } ], "request_body": { "schema_name": "ExpenseUpdate", "fields": [ { "name": "tour_schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "category", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false, "nullable": true }, { "name": "vendor_name", "type": "str", "required": false, "nullable": true }, { "name": "expense_date", "type": "date", "required": false, "nullable": true }, { "name": "payment_method", "type": "str", "required": false, "nullable": true }, { "name": "receipt_url", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ExpenseStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "APPROVED", "REJECTED", "PAID" ] }, { "name": "submitted_by", "type": "str", "required": false, "nullable": true }, { "name": "approved_by", "type": "str", "required": false, "nullable": true }, { "name": "approval_date", "type": "datetime", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "ExpenseResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "category", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "vendor_name", "type": "str", "required": false, "nullable": true }, { "name": "expense_date", "type": "date", "required": true }, { "name": "payment_method", "type": "str", "required": false, "nullable": true }, { "name": "receipt_url", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "submitted_by", "type": "str", "required": true }, { "name": "approved_by", "type": "str", "required": false, "nullable": true }, { "name": "approval_date", "type": "datetime", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/expenses/{expense_id}", "summary": "Delete Expense", "description": "Deletes an expense record by its unique identifier. Returns 404 if the expense does not exist.", "path_params": [ { "name": "expense_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/expenses/{expense_id}/approve", "summary": "Approve Expense", "description": "Approves a pending expense. Updates the status to approved, records the approver and approval date. Returns 400 if the expense is not in pending status, 404 if the expense or approver user does not exist.", "path_params": [ { "name": "expense_id", "type": "str" } ], "response": { "schema_name": "ExpenseResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "category", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "vendor_name", "type": "str", "required": false, "nullable": true }, { "name": "expense_date", "type": "date", "required": true }, { "name": "payment_method", "type": "str", "required": false, "nullable": true }, { "name": "receipt_url", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "submitted_by", "type": "str", "required": true }, { "name": "approved_by", "type": "str", "required": false, "nullable": true }, { "name": "approval_date", "type": "datetime", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/expenses/{expense_id}/reject", "summary": "Reject Expense", "description": "Rejects a pending expense. Updates the status to rejected, records the rejector and rejection date. Optional notes can be provided. Returns 400 if the expense is not in pending status, 404 if the expense or rejector user does not exist.", "path_params": [ { "name": "expense_id", "type": "str" } ], "query_params": [ { "name": "notes", "type": "str", "required": false } ], "response": { "schema_name": "ExpenseResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "tour_schedule_id", "type": "str", "required": false, "nullable": true }, { "name": "category", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "vendor_name", "type": "str", "required": false, "nullable": true }, { "name": "expense_date", "type": "date", "required": true }, { "name": "payment_method", "type": "str", "required": false, "nullable": true }, { "name": "receipt_url", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "submitted_by", "type": "str", "required": true }, { "name": "approved_by", "type": "str", "required": false, "nullable": true }, { "name": "approval_date", "type": "datetime", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/commissions", "summary": "Create Commission", "description": "Creates a new commission record for a booking agent. Validates that the booking and agent user exist. Commission amount is calculated based on booking amount and commission rate. Returns 404 if referenced entities are not found.", "request_body": { "schema_name": "CommissionCreate", "fields": [ { "name": "booking_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": true }, { "name": "booking_amount", "type": "Decimal", "required": false }, { "name": "commission_rate", "type": "Decimal", "required": false }, { "name": "commission_amount", "type": "Decimal", "required": false }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CommissionResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": true }, { "name": "booking_amount", "type": "Decimal", "required": true }, { "name": "commission_rate", "type": "Decimal", "required": true }, { "name": "commission_amount", "type": "Decimal", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/commissions/{commission_id}", "summary": "Get Commission By ID", "description": "Retrieves a single commission record by its unique identifier. Returns 404 if the commission does not exist.", "path_params": [ { "name": "commission_id", "type": "str" } ], "response": { "schema_name": "CommissionResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": true }, { "name": "booking_amount", "type": "Decimal", "required": true }, { "name": "commission_rate", "type": "Decimal", "required": true }, { "name": "commission_amount", "type": "Decimal", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/commissions", "summary": "List Commissions", "description": "Returns a paginated list of commission records. Supports optional filters for status and booking agent. 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": "status_filter", "type": "CommissionStatus", "required": false }, { "name": "booking_agent_id", "type": "str", "required": false } ], "response": { "schema_name": "CommissionResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": true }, { "name": "booking_amount", "type": "Decimal", "required": true }, { "name": "commission_rate", "type": "Decimal", "required": true }, { "name": "commission_amount", "type": "Decimal", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/commissions/{commission_id}", "summary": "Update Commission", "description": "Updates an existing commission record. Only provided fields are updated. Validates that referenced booking and agent user exist. Returns 404 if the commission or referenced entities are not found.", "path_params": [ { "name": "commission_id", "type": "str" } ], "request_body": { "schema_name": "CommissionUpdate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "booking_agent_id", "type": "str", "required": false, "nullable": true }, { "name": "booking_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "commission_rate", "type": "Decimal", "required": false, "nullable": true }, { "name": "commission_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "status", "type": "CommissionStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "APPROVED", "PAID" ] }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CommissionResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": true }, { "name": "booking_amount", "type": "Decimal", "required": true }, { "name": "commission_rate", "type": "Decimal", "required": true }, { "name": "commission_amount", "type": "Decimal", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/commissions/{commission_id}", "summary": "Delete Commission", "description": "Deletes a commission record by its unique identifier. Returns 404 if the commission does not exist.", "path_params": [ { "name": "commission_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/commissions/{commission_id}/approve", "summary": "Approve Commission", "description": "Approves a pending commission. Updates the status to approved. Returns 400 if the commission is not in pending status, 404 if the commission does not exist.", "path_params": [ { "name": "commission_id", "type": "str" } ], "response": { "schema_name": "CommissionResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": true }, { "name": "booking_amount", "type": "Decimal", "required": true }, { "name": "commission_rate", "type": "Decimal", "required": true }, { "name": "commission_amount", "type": "Decimal", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/commissions/{commission_id}/pay", "summary": "Pay Commission", "description": "Marks an approved commission as paid and records the payment date. Returns 400 if the commission is not in approved status (must be approved before payment), 404 if the commission does not exist.", "path_params": [ { "name": "commission_id", "type": "str" } ], "response": { "schema_name": "CommissionResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "booking_id", "type": "str", "required": true }, { "name": "booking_agent_id", "type": "str", "required": true }, { "name": "booking_amount", "type": "Decimal", "required": true }, { "name": "commission_rate", "type": "Decimal", "required": true }, { "name": "commission_amount", "type": "Decimal", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Notifications", "prefix": "/notifications", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Notification", "description": "Creates a new notification for a user. Validates that the user exists before creating the notification. Returns 404 if the user is not found.", "request_body": { "schema_name": "NotificationCreate", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "BOOKING", "PAYMENT", "CANCELLATION", "REMINDER", "PROMOTION", "SYSTEM", "REVIEW" ] }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "link_url", "type": "str", "required": false, "nullable": true }, { "name": "delivery_method", "type": "DeliveryMethod", "required": true, "enum_values": [ "IN_APP", "EMAIL", "SMS", "PUSH" ] }, { "name": "delivery_status", "type": "DeliveryStatus", "required": false, "enum_values": [ "PENDING", "SENT", "FAILED" ] } ] }, "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "BOOKING", "PAYMENT", "CANCELLATION", "REMINDER", "PROMOTION", "SYSTEM", "REVIEW" ] }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "link_url", "type": "str", "required": false, "nullable": true }, { "name": "delivery_method", "type": "DeliveryMethod", "required": true, "enum_values": [ "IN_APP", "EMAIL", "SMS", "PUSH" ] }, { "name": "delivery_status", "type": "DeliveryStatus", "required": false, "enum_values": [ "PENDING", "SENT", "FAILED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "sent_at", "type": "datetime", "required": false, "nullable": 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 Notifications", "description": "Returns a paginated list of notifications. Supports optional filters for user_id, notification_type, is_read status, and delivery_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": "notification_type", "type": "str", "required": false }, { "name": "is_read", "type": "bool", "required": false }, { "name": "delivery_status", "type": "str", "required": false } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "BOOKING", "PAYMENT", "CANCELLATION", "REMINDER", "PROMOTION", "SYSTEM", "REVIEW" ] }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "link_url", "type": "str", "required": false, "nullable": true }, { "name": "delivery_method", "type": "DeliveryMethod", "required": true, "enum_values": [ "IN_APP", "EMAIL", "SMS", "PUSH" ] }, { "name": "delivery_status", "type": "DeliveryStatus", "required": false, "enum_values": [ "PENDING", "SENT", "FAILED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "sent_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/unread", "summary": "List Unread Notifications", "description": "Returns a paginated list of unread notifications for a specific user. Validates that the user exists. Returns 404 if the user is not found.", "query_params": [ { "name": "user_id", "type": "str", "required": false, "default": null }, { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "BOOKING", "PAYMENT", "CANCELLATION", "REMINDER", "PROMOTION", "SYSTEM", "REVIEW" ] }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "link_url", "type": "str", "required": false, "nullable": true }, { "name": "delivery_method", "type": "DeliveryMethod", "required": true, "enum_values": [ "IN_APP", "EMAIL", "SMS", "PUSH" ] }, { "name": "delivery_status", "type": "DeliveryStatus", "required": false, "enum_values": [ "PENDING", "SENT", "FAILED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "sent_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{notification_id}", "summary": "Get Notification", "description": "Returns a single notification by ID. Returns 404 if the notification is not found.", "path_params": [ { "name": "notification_id", "type": "str" } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "BOOKING", "PAYMENT", "CANCELLATION", "REMINDER", "PROMOTION", "SYSTEM", "REVIEW" ] }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "link_url", "type": "str", "required": false, "nullable": true }, { "name": "delivery_method", "type": "DeliveryMethod", "required": true, "enum_values": [ "IN_APP", "EMAIL", "SMS", "PUSH" ] }, { "name": "delivery_status", "type": "DeliveryStatus", "required": false, "enum_values": [ "PENDING", "SENT", "FAILED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "sent_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{notification_id}", "summary": "Update Notification", "description": "Updates an existing notification. All fields are optional. Validates that the user exists if user_id is being updated. Returns 404 if the notification or user is not found.", "path_params": [ { "name": "notification_id", "type": "str" } ], "request_body": { "schema_name": "NotificationUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "notification_type", "type": "NotificationType", "required": false, "nullable": true, "enum_values": [ "BOOKING", "PAYMENT", "CANCELLATION", "REMINDER", "PROMOTION", "SYSTEM", "REVIEW" ] }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "link_url", "type": "str", "required": false, "nullable": true }, { "name": "is_read", "type": "bool", "required": false, "nullable": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "delivery_method", "type": "DeliveryMethod", "required": false, "nullable": true, "enum_values": [ "IN_APP", "EMAIL", "SMS", "PUSH" ] }, { "name": "delivery_status", "type": "DeliveryStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "SENT", "FAILED" ] }, { "name": "sent_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "BOOKING", "PAYMENT", "CANCELLATION", "REMINDER", "PROMOTION", "SYSTEM", "REVIEW" ] }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "link_url", "type": "str", "required": false, "nullable": true }, { "name": "delivery_method", "type": "DeliveryMethod", "required": true, "enum_values": [ "IN_APP", "EMAIL", "SMS", "PUSH" ] }, { "name": "delivery_status", "type": "DeliveryStatus", "required": false, "enum_values": [ "PENDING", "SENT", "FAILED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "sent_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{notification_id}", "summary": "Delete Notification", "description": "Deletes a notification by ID. Returns 404 if the notification is not found.", "path_params": [ { "name": "notification_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{notification_id}/mark-read", "summary": "Mark Notification As Read", "description": "Marks a single notification as read and sets the read_at timestamp. If the notification is already read, returns it unchanged. Returns 404 if the notification is not found.", "path_params": [ { "name": "notification_id", "type": "str" } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "BOOKING", "PAYMENT", "CANCELLATION", "REMINDER", "PROMOTION", "SYSTEM", "REVIEW" ] }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "link_url", "type": "str", "required": false, "nullable": true }, { "name": "delivery_method", "type": "DeliveryMethod", "required": true, "enum_values": [ "IN_APP", "EMAIL", "SMS", "PUSH" ] }, { "name": "delivery_status", "type": "DeliveryStatus", "required": false, "enum_values": [ "PENDING", "SENT", "FAILED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "sent_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/mark-all-read", "summary": "Mark All Notifications As Read", "description": "Marks all unread notifications for a specific user as read. Validates that the user exists. Returns the count of notifications marked as read. Returns 404 if the user is not found.", "query_params": [ { "name": "user_id", "type": "str", "required": false, "default": null } ], "status_code": 200 } ] }, { "name": "Documents", "prefix": "/documents", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Document", "description": "Creates a new document record. Validates that the uploader user exists and that at least one of booking_id or customer_id is provided. If booking_id is provided, validates that the booking exists. If customer_id is provided, validates that the customer exists. Returns 400 if validation fails.", "request_body": { "schema_name": "DocumentCreate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "document_type", "type": "DocumentTypeEnum", "required": true, "enum_values": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] }, { "name": "file_name", "type": "str", "required": false }, { "name": "file_url", "type": "str", "required": false }, { "name": "file_size_kb", "type": "int", "required": false, "nullable": true }, { "name": "mime_type", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "uploaded_by", "type": "str", "required": false } ] }, "response": { "schema_name": "DocumentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "document_type", "type": "DocumentTypeEnum", "required": true, "enum_values": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] }, { "name": "file_name", "type": "str", "required": false }, { "name": "file_url", "type": "str", "required": false }, { "name": "file_size_kb", "type": "int", "required": false, "nullable": true }, { "name": "mime_type", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "uploaded_by", "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 Documents", "description": "Returns a paginated list of documents. Supports optional filtering by booking_id, customer_id, document_type, and uploaded_by. 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": "booking_id", "type": "str", "required": false }, { "name": "customer_id", "type": "str", "required": false }, { "name": "document_type", "type": "DocumentTypeEnum", "required": false }, { "name": "uploaded_by", "type": "str", "required": false } ], "response": { "schema_name": "DocumentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "document_type", "type": "DocumentTypeEnum", "required": true, "enum_values": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] }, { "name": "file_name", "type": "str", "required": false }, { "name": "file_url", "type": "str", "required": false }, { "name": "file_size_kb", "type": "int", "required": false, "nullable": true }, { "name": "mime_type", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "uploaded_by", "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": "/{document_id}", "summary": "Get Document", "description": "Returns a single document by ID. Returns 404 if the document does not exist.", "path_params": [ { "name": "document_id", "type": "str" } ], "response": { "schema_name": "DocumentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "document_type", "type": "DocumentTypeEnum", "required": true, "enum_values": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] }, { "name": "file_name", "type": "str", "required": false }, { "name": "file_url", "type": "str", "required": false }, { "name": "file_size_kb", "type": "int", "required": false, "nullable": true }, { "name": "mime_type", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "uploaded_by", "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": "/{document_id}/details", "summary": "Get Document Details", "description": "Returns detailed information about a document including uploader name, booking number, and customer name. Uses eager loading to fetch related entities efficiently. Returns 404 if the document does not exist.", "path_params": [ { "name": "document_id", "type": "str" } ], "response": { "schema_name": "DocumentDetailResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "document_type", "type": "DocumentTypeEnum", "required": true, "enum_values": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] }, { "name": "file_name", "type": "str", "required": false }, { "name": "file_url", "type": "str", "required": false }, { "name": "file_size_kb", "type": "int", "required": false, "nullable": true }, { "name": "mime_type", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "uploaded_by", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "uploader_name", "type": "str", "required": false, "nullable": true }, { "name": "booking_number", "type": "str", "required": false, "nullable": true }, { "name": "customer_name", "type": "str", "required": false, "nullable": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{document_id}", "summary": "Update Document", "description": "Updates an existing document. All fields are optional. If booking_id or customer_id are provided, validates that they exist. Returns 404 if the document does not exist, 400 if validation fails.", "path_params": [ { "name": "document_id", "type": "str" } ], "request_body": { "schema_name": "DocumentUpdate", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "document_type", "type": "DocumentTypeEnum", "required": false, "nullable": true, "enum_values": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] }, { "name": "file_name", "type": "str", "required": false, "nullable": true }, { "name": "file_url", "type": "str", "required": false, "nullable": true }, { "name": "file_size_kb", "type": "int", "required": false, "nullable": true }, { "name": "mime_type", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "DocumentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "document_type", "type": "DocumentTypeEnum", "required": true, "enum_values": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] }, { "name": "file_name", "type": "str", "required": false }, { "name": "file_url", "type": "str", "required": false }, { "name": "file_size_kb", "type": "int", "required": false, "nullable": true }, { "name": "mime_type", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "uploaded_by", "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": "/{document_id}", "summary": "Delete Document", "description": "Deletes a document by ID. Returns 404 if the document does not exist.", "path_params": [ { "name": "document_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/booking/{booking_id}/documents", "summary": "Get Booking Documents", "description": "Returns all documents associated with a specific booking. Returns 404 if the booking does not exist.", "path_params": [ { "name": "booking_id", "type": "str" } ], "response": { "schema_name": "DocumentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "document_type", "type": "DocumentTypeEnum", "required": true, "enum_values": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] }, { "name": "file_name", "type": "str", "required": false }, { "name": "file_url", "type": "str", "required": false }, { "name": "file_size_kb", "type": "int", "required": false, "nullable": true }, { "name": "mime_type", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "uploaded_by", "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": "/customer/{customer_id}/documents", "summary": "Get Customer Documents", "description": "Returns all documents associated with a specific customer. Returns 404 if the customer does not exist.", "path_params": [ { "name": "customer_id", "type": "str" } ], "response": { "schema_name": "DocumentResponse", "fields": [ { "name": "booking_id", "type": "str", "required": false, "nullable": true }, { "name": "customer_id", "type": "str", "required": false, "nullable": true }, { "name": "document_type", "type": "DocumentTypeEnum", "required": true, "enum_values": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] }, { "name": "file_name", "type": "str", "required": false }, { "name": "file_url", "type": "str", "required": false }, { "name": "file_size_kb", "type": "int", "required": false, "nullable": true }, { "name": "mime_type", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "uploaded_by", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 } ] } ], "enums": { "UserRole": [ "SUPER_ADMIN", "TOUR_MANAGER", "BOOKING_AGENT", "TOUR_GUIDE", "SERVICE_PROVIDER", "CUSTOMER", "FINANCE_MANAGER" ], "LoyaltyStatus": [ "BRONZE", "SILVER", "GOLD", "PLATINUM" ], "ServiceType": [ "HOTEL", "TRANSPORTATION", "RESTAURANT", "ACTIVITY", "INSURANCE", "OTHER" ], "SeasonType": [ "PEAK", "OFF_PEAK", "SHOULDER" ], "AmenityType": [ "ACCOMMODATION", "TRANSPORT", "TOUR", "GENERAL" ], "DifficultyLevel": [ "EASY", "MODERATE", "CHALLENGING", "DIFFICULT" ], "BookingStatus": [ "PENDING", "CONFIRMED", "CANCELLED", "COMPLETED", "REFUNDED" ], "PaymentStatus": [ "UNPAID", "PARTIAL", "PAID", "REFUNDED" ], "TravelerType": [ "ADULT", "CHILD", "INFANT" ], "Gender": [ "MALE", "FEMALE", "OTHER" ], "TourScheduleStatus": [ "SCHEDULED", "CONFIRMED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ], "ResourceBookingStatus": [ "PENDING", "CONFIRMED", "CANCELLED" ], "TransportType": [ "BUS", "FLIGHT", "TRAIN", "CAR", "BOAT", "OTHER" ], "PaymentMethod": [ "CREDIT_CARD", "DEBIT_CARD", "BANK_TRANSFER", "CASH", "PAYPAL", "STRIPE", "OTHER" ], "TransactionStatus": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED" ], "InvoiceStatus": [ "DRAFT", "SENT", "PAID", "OVERDUE", "CANCELLED" ], "DiscountType": [ "PERCENTAGE", "FIXED_AMOUNT", "EARLY_BIRD", "GROUP", "LOYALTY" ], "CancellationRequestStatus": [ "PENDING", "APPROVED", "REJECTED", "PROCESSED" ], "ExpenseStatus": [ "PENDING", "APPROVED", "REJECTED", "PAID" ], "CommissionStatus": [ "PENDING", "APPROVED", "PAID" ], "NotificationType": [ "BOOKING", "PAYMENT", "CANCELLATION", "REMINDER", "PROMOTION", "SYSTEM", "REVIEW" ], "DeliveryMethod": [ "IN_APP", "EMAIL", "SMS", "PUSH" ], "DeliveryStatus": [ "PENDING", "SENT", "FAILED" ], "DocumentTypeEnum": [ "VOUCHER", "TICKET", "INSURANCE", "PASSPORT", "VISA", "ITINERARY", "INVOICE", "RECEIPT", "OTHER" ] } }