{ "openapi": "3.0.3", "info": { "title": "Yatra / DriveMond Platform Master API", "description": "A production-ready on-demand mobility, parcel delivery, real-time dispatch, and fleet intelligence REST API platform. The REST API documented here **is the product** — every endpoint below is independently usable with Bearer token authentication, with no dependency on any web dashboard.\n\n### Products\n- **Customer Mobility** — ride requests, live driver bidding, fare estimates, trip lifecycle\n- **Parcel & Logistics** — on-demand parcel deliveries, category weight slabs, package tracking\n- **Driver Operations** — online/offline dispatch, custom price bidding, payouts & earnings\n- **Tracking & Telemetry** — high-frequency GPS coordinate streaming, heading, speed\n- **Wallet & Gateways** — multi-currency wallets, digital payments, loyalty points & coupons\n- **Zones & Geofencing** — operational boundaries, polygon geofences, surge pricing\n- **Safety & Emergency (SOS)** — emergency assistance broadcast, incident response, real-time safety alerts\n\nEverything else (business configurations, zones, promotional discounts, notification webhooks, driver verification) supports mobile clients integrating those APIs into real-time fleet operations.\n\n### Authentication\nAll authenticated endpoints require standard HTTP Bearer token authentication in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nThe access token is obtained via customer or driver authentication endpoints (`/api/customer/auth/login`, `/api/driver/auth/login`). Additionally, zone-restricted endpoints accept the `zoneId` header, and location-aware calls pass `latitude` and `longitude` coordinates.", "version": "2.5.0", "contact": { "name": "Yatra Core Engineering & API Architecture Team", "email": "api-support@yatra.com" }, "license": { "name": "Proprietary Commercial Enterprise License" } }, "servers": [ { "url": "https://yatra.inflancer.com", "description": "Active Environment Server" } ], "tags": [ { "name": "Customer - Authentication", "description": "Login, registration, phone OTP verification, password recovery, and social OAuth sign-in." }, { "name": "Customer - Profile & Loyalty", "description": "Profile management, address book, customer tiers/levels, loyalty points conversion, and referrals." }, { "name": "Customer - Rides & Bidding", "description": "Ride booking, fare estimation, real-time driver bidding, accepting bids, ride tracking, and cancellation." }, { "name": "Customer - Parcel Delivery", "description": "Parcel delivery requests, category weight slabs, vehicle suggestions, and live package tracking." }, { "name": "Customer - Wallet & Payments", "description": "Digital payment gateways, wallet balance, transaction ledger, and promotional coupon vouchers." }, { "name": "Customer - Chat & Messaging", "description": "Two-way in-app real-time chat channels with assigned drivers and customer support agents." }, { "name": "Customer - Safety & Emergency (SOS)", "description": "Emergency SOS alerts, emergency contacts management, and safety protocols." }, { "name": "Driver - Authentication & Status", "description": "Driver onboarding, login, online/offline toggle, and FCM push token registration." }, { "name": "Driver - Ride Dispatch & Bidding", "description": "Incoming ride alerts, submitting custom price bids, customer OTP verification, and trip lifecycle." }, { "name": "Driver - Live Location & Telemetry", "description": "High-frequency GPS coordinate streaming, heading, speed, and real-time passenger routing." }, { "name": "Driver - Earnings & Financials", "description": "Income statements, daily driving activity, wallet transactions, cash collect list, and payout requests." }, { "name": "Driver - Vehicles & Documents", "description": "Vehicle categories, brand models, license plate registration, and vehicle documentation." }, { "name": "Driver - Safety & SOS", "description": "Driver-side emergency SOS broadcast, incident reporting, and safety precaution guides." }, { "name": "Zones & Geofencing", "description": "Operational zones, polygon geofence coordinates, coordinate-to-zone resolution, and surge pricing." }, { "name": "System & Shared Configuration", "description": "Global business settings, cancellation reason lists, maps autocomplete, place details, and user account actions." } ], "paths": { "/api/customer/auth/login": { "post": { "tags": [ "Customer - Authentication" ], "summary": "Customer Login via Phone/Email & Password", "description": "Authenticates customer and returns Bearer token, verified status, and customer profile details.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email_or_phone", "password" ], "properties": { "email_or_phone": { "type": "string", "example": "+9779812345678", "description": "Customer registered phone or email" }, "password": { "type": "string", "format": "password", "example": "password123" } } } } } }, "responses": { "200": { "description": "Login Successful", "content": { "application/json": { "example": { "response_code": "auth_login_200", "message": "Successfully logged in", "content": { "token": "1|AbCdEf1234567890abcdef...", "is_profile_verified": 1, "user": { "id": "c3a7b912-3211-4f10-91bc-318e8df6a789", "first_name": "Aarav", "last_name": "Sharma", "phone": "+9779812345678", "email": "aarav@example.com", "profile_image": "https://iservers.blr1.cdn.digitaloceanspaces.com/yatra/customer/avatar.webp", "wallet_balance": 450.5 } } } } } }, "401": { "description": "Invalid credentials or user deactivated" }, "422": { "description": "Validation error (missing phone or invalid format)" } }, "operationId": "post.customer.auth.login" } }, "/api/customer/auth/registration": { "post": { "tags": [ "Customer - Authentication" ], "summary": "Customer Registration", "description": "Register a new customer account. Triggers OTP dispatch to given mobile number.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "first_name", "last_name", "phone", "password", "confirm_password" ], "properties": { "first_name": { "type": "string", "example": "Aarav" }, "last_name": { "type": "string", "example": "Sharma" }, "phone": { "type": "string", "example": "+9779812345678" }, "email": { "type": "string", "format": "email", "example": "aarav@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" }, "confirm_password": { "type": "string", "format": "password", "example": "password123" }, "referral_code": { "type": "string", "example": "YATRA2026" } } } } } }, "responses": { "200": { "description": "Registration initialized / OTP dispatched", "content": { "application/json": { "example": { "response_code": "registration_200", "message": "OTP code sent to phone number", "content": { "phone": "+9779812345678", "otp_expires_in_seconds": 120 } } } } }, "422": { "description": "Phone or Email already registered" } }, "operationId": "post.customer.auth.registration" } }, "/api/customer/auth/send-otp": { "post": { "tags": [ "Customer - Authentication" ], "summary": "Send or Resend Verification OTP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone_or_email" ], "properties": { "phone_or_email": { "type": "string", "example": "+9779812345678" } } } } } }, "responses": { "200": { "description": "OTP sent successfully", "content": { "application/json": { "example": { "response_code": "otp_sent_200", "message": "OTP sent successfully to +9779812345678" } } } } }, "operationId": "post.customer.auth.sendOtp" } }, "/api/customer/auth/otp-verification": { "post": { "tags": [ "Customer - Authentication" ], "summary": "Verify OTP Code & Obtain Access Token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone_or_email", "otp" ], "properties": { "phone_or_email": { "type": "string", "example": "+9779812345678" }, "otp": { "type": "string", "example": "1234" } } } } } }, "responses": { "200": { "description": "OTP verified successfully", "content": { "application/json": { "example": { "response_code": "otp_verified_200", "message": "Phone number verified successfully", "content": { "token": "1|XyZ987...", "verified": true } } } } }, "403": { "description": "Invalid or expired OTP code" } }, "operationId": "post.customer.auth.otpVerification" } }, "/api/customer/auth/social-login": { "post": { "tags": [ "Customer - Authentication" ], "summary": "Social Sign-In (Google / Apple / Facebook OAuth)", "description": "Authenticate customer using 3rd party OAuth provider credentials.\n\n### Flutter Integration Guide for Google Login:\n1. In Flutter, use the official `google_sign_in` package (`GoogleSignIn().signIn()`).\n2. After sign in, obtain the `GoogleSignInAuthentication` object:\n - `token`: Send the OpenID Connect JWT `auth.idToken` (recommended) or OAuth `auth.accessToken`.\n - `unique_id`: Send `googleUser.id` (or `sub`).\n - `medium`: Set to `\"google\"`.\n - `email`: Send `googleUser.email`.\n3. Handle Responses:\n - **200 OK (`auth_login_200`)**: User exists and is logged in. Use `content.token` as Bearer token for subsequent API calls.\n - **406 Not Acceptable (`auth_login_406`)**: New customer! Response contains prefilled `email`, `first_name`, and `last_name`. Navigate the customer to complete registration with their phone number via `/api/customer/auth/registration-from-social`.\n - **202 Accepted (`default_sent_otp_200`)**: Customer account exists but phone is not verified. An SMS OTP was sent. Direct customer to verify via `/api/customer/auth/otp-login`.\n - **403 Forbidden**: Social login is disabled in admin settings (`social_login_disabled_403`), account is deactivated (`default_user_disabled_401`), or token verification failed (`default_401`).\n - **401 Unauthorized**: Email mismatch between request and Google token payload.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "unique_id", "medium" ], "properties": { "token": { "type": "string", "description": "Google id_token (JWT) or access_token, or Apple authorization code.", "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFhMmIzYy...id_token_from_google_sign_in" }, "unique_id": { "type": "string", "description": "Provider user ID (Google account id / sub, or Apple user identifier).", "example": "109283746592837465019" }, "medium": { "type": "string", "enum": [ "google", "apple", "facebook" ], "example": "google" }, "email": { "type": "string", "format": "email", "description": "Required for Google and Facebook login.", "example": "customer@example.com" } } } } } }, "responses": { "200": { "description": "Social Login Successful (Customer already registered)", "content": { "application/json": { "example": { "response_code": "auth_login_200", "message": "Successfully authenticated", "content": { "token": "1|OAuthBearerTokenString...", "is_active": true, "is_phone_verified": 1, "is_profile_verified": 1 } } } } }, "406": { "description": "New Social User - Registration Required (Redirect to Complete Profile)", "content": { "application/json": { "example": { "response_code": "auth_login_406", "message": "User not registered yet. Please complete registration.", "content": { "medium": "google", "email": "customer@example.com", "first_name": "John", "last_name": "Doe", "refresh_token": null } } } } }, "202": { "description": "Login Accepted but Phone Unverified (OTP Sent)", "content": { "application/json": { "example": { "response_code": "default_sent_otp_200", "message": "OTP sent successfully", "content": { "is_phone_verified": 0, "verification_url": "/api/customer/auth/otp-login", "phone": "+9779812345678" } } } } }, "401": { "description": "Email mismatch between request payload and verified token" }, "403": { "description": "Social login disabled by admin, token verification failure, or suspended account" }, "422": { "description": "Validation error" } }, "operationId": "post.customer.auth.socialLogin" } }, "/api/customer/auth/registration-from-social": { "post": { "tags": [ "Customer - Authentication" ], "summary": "Complete Customer Registration from Social Login", "description": "Register new customer profile after receiving `406 Not Acceptable` from `/api/customer/auth/social-login`.\n\n### Flutter Integration Step:\nCollect phone number from customer and submit prefilled Google details (`first_name`, `last_name`, `email`, `phone`, `medium: 'google'`). If phone verification is enabled, an OTP is dispatched.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "first_name", "email", "phone", "medium" ], "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "example": "customer@example.com" }, "phone": { "type": "string", "example": "+9779812345678" }, "medium": { "type": "string", "enum": [ "google", "apple", "facebook" ], "example": "google" }, "referral_code": { "type": "string", "nullable": true, "example": "REF12345" }, "fcm_token": { "type": "string", "nullable": true, "example": "fcm_token_string..." }, "refresh_token": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Customer Registered & Logged In", "content": { "application/json": { "example": { "response_code": "auth_login_200", "message": "Registration successful", "content": { "token": "1|OAuthBearerTokenString...", "is_active": true, "is_phone_verified": 1, "is_profile_verified": 1 } } } } }, "202": { "description": "Registered, OTP sent to phone number for verification", "content": { "application/json": { "example": { "response_code": "default_sent_otp_200", "message": "OTP dispatched to phone", "content": { "is_phone_verified": 0, "verification_url": "/api/customer/auth/otp-login" } } } } }, "403": { "description": "Invalid referral code or tier level missing" }, "422": { "description": "Validation error (e.g. email or phone already registered)" } }, "operationId": "post.customer.auth.registrationFromSocial" } }, "/api/customer/auth/forget-password": { "post": { "tags": [ "Customer - Authentication" ], "summary": "Request Password Reset OTP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone_or_email" ], "properties": { "phone_or_email": { "type": "string", "example": "+9779812345678" } } } } } }, "responses": { "200": { "description": "Reset code dispatched" } }, "operationId": "post.customer.auth.forgetPassword" } }, "/api/customer/info": { "get": { "tags": [ "Customer - Profile & Loyalty" ], "summary": "Get Customer Profile & Wallet Info", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Customer profile data", "content": { "application/json": { "example": { "response_code": "default_200", "content": { "id": "c3a7b912-3211-4f10-91bc-318e8df6a789", "first_name": "Aarav", "last_name": "Sharma", "phone": "+9779812345678", "email": "aarav@example.com", "profile_image": "https://iservers.blr1.cdn.digitaloceanspaces.com/yatra/customer/profile/avatar.webp", "loyalty_points": 1250, "wallet_balance": 450.5, "user_level": { "name": "Gold Rider", "discount_percent": 5 }, "total_rides": 42 } } } } } }, "operationId": "get.customer.info" } }, "/api/customer/update/profile": { "put": { "tags": [ "Customer - Profile & Loyalty" ], "summary": "Update Customer Profile (Name, Email, Avatar)", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Aarav" }, "last_name": { "type": "string", "example": "Sharma" }, "email": { "type": "string", "format": "email", "example": "aarav.updated@example.com" }, "profile_image": { "type": "string", "format": "binary", "description": "Image up to 10MB, auto-optimized to WebP" } } } } } }, "responses": { "200": { "description": "Profile updated successfully" } }, "operationId": "put.customer.update.profile" } }, "/api/customer/update/fcm-token": { "put": { "tags": [ "Customer - Profile & Loyalty" ], "summary": "Update Firebase Cloud Messaging (FCM) Push Token", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fcm_token" ], "properties": { "fcm_token": { "type": "string", "example": "f7K3...fcm_push_token_string..." } } } } } }, "responses": { "200": { "description": "FCM Token registered" } }, "operationId": "put.customer.update.fcmToken" } }, "/api/customer/address/all-address": { "get": { "tags": [ "Customer - Profile & Loyalty" ], "summary": "Get Saved Address Book (Home, Work, Other)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of saved addresses", "content": { "application/json": { "example": { "response_code": "default_200", "content": [ { "id": "addr_99182", "title": "Home", "address": "House #12, Lazimpat, Kathmandu", "latitude": 27.7215, "longitude": 85.318, "category": "home" } ] } } } } }, "operationId": "get.customer.address.allAddress" } }, "/api/customer/loyalty-points/convert": { "post": { "tags": [ "Customer - Profile & Loyalty" ], "summary": "Convert Loyalty Points into Wallet Balance", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "points" ], "properties": { "points": { "type": "integer", "example": 500, "description": "Points to convert (min 100)" } } } } } }, "responses": { "200": { "description": "Points credited to wallet", "content": { "application/json": { "example": { "response_code": "default_200", "message": "500 points successfully converted into Rs. 50.00 wallet balance" } } } } }, "operationId": "post.customer.loyaltyPoints.convert" } }, "/api/customer/config/get-payment-methods": { "get": { "tags": [ "Customer - Wallet & Payments" ], "summary": "Get Active Payment Gateways (Esewa, Khalti, Stripe, Cash)", "responses": { "200": { "description": "Active payment methods", "content": { "application/json": { "example": { "response_code": "default_200", "content": [ { "gateway": "cash", "title": "Cash on Delivery / Ride", "is_active": true }, { "gateway": "wallet", "title": "Yatra In-App Wallet", "is_active": true }, { "gateway": "digital", "title": "Esewa / Khalti / Stripe", "is_active": true } ] } } } } }, "operationId": "get.customer.config.getPaymentMethods" } }, "/api/customer/transaction/list": { "get": { "tags": [ "Customer - Wallet & Payments" ], "summary": "Customer Wallet Transaction History", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 15 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Paginated transaction entries (credits, debits, cash payments)" } }, "operationId": "get.customer.transaction.list" } }, "/api/customer/coupon/apply": { "post": { "tags": [ "Customer - Wallet & Payments" ], "summary": "Validate and Apply Discount Coupon Code", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "coupon_code", "fare" ], "properties": { "coupon_code": { "type": "string", "example": "YATRAFIRST50" }, "fare": { "type": "number", "example": 380 } } } } } }, "responses": { "200": { "description": "Coupon discount applied successfully", "content": { "application/json": { "example": { "response_code": "coupon_applied_200", "content": { "discount_amount": 50, "final_fare": 330, "coupon_title": "Rs. 50 off on your first ride" } } } } } }, "operationId": "post.customer.coupon.apply" } }, "/api/customer/chat/channel-list": { "get": { "tags": [ "Customer - Chat & Messaging" ], "summary": "Get Active Chat Channels with Drivers", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Channels with latest unread messages and driver details" } }, "operationId": "get.customer.chat.channelList" } }, "/api/customer/chat/conversation": { "get": { "tags": [ "Customer - Chat & Messaging" ], "summary": "Get Messages for a Specific Channel", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "channel_id", "in": "query", "required": true, "schema": { "type": "string", "example": "chn_98124" } } ], "responses": { "200": { "description": "List of chronological messages with sender type and timestamps" } }, "operationId": "get.customer.chat.conversation" } }, "/api/customer/chat/send-message": { "put": { "tags": [ "Customer - Chat & Messaging" ], "summary": "Send Real-time Chat Message to Assigned Driver", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_id", "message" ], "properties": { "channel_id": { "type": "string", "example": "chn_98124" }, "message": { "type": "string", "example": "I am wearing a black jacket outside gate 1." } } } } } }, "responses": { "200": { "description": "Message delivered and FCM push sent to driver" } }, "operationId": "put.customer.chat.sendMessage" } }, "/api/customer/safety-alert/store": { "post": { "tags": [ "Customer - Safety & Emergency (SOS)" ], "summary": "Trigger Emergency SOS Alert During Ride", "description": "Instantly broadcasts high-priority SOS emergency alert to Admin Operations Dispatch and emergency contacts.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trip_request_id", "latitude", "longitude" ], "properties": { "trip_request_id": { "type": "string", "example": "trip_req_82736152" }, "latitude": { "type": "number", "example": 27.7172 }, "longitude": { "type": "number", "example": 85.324 }, "reason": { "type": "string", "example": "Driver took an unsafe unexpected detour" } } } } } }, "responses": { "200": { "description": "SOS alert active and broadcasted to emergency responders", "content": { "application/json": { "example": { "response_code": "safety_alert_200", "message": "Emergency SOS dispatched to Police (100) and Yatra Safety Dispatch" } } } } }, "operationId": "post.customer.safetyAlert.store" } }, "/api/customer/auth/reset-password": { "post": { "tags": [ "Customer - Authentication" ], "summary": "Reset Password with OTP Code", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone_or_email", "otp", "password", "confirm_password" ], "properties": { "phone_or_email": { "type": "string", "example": "+9779812345678" }, "otp": { "type": "string", "example": "1234" }, "password": { "type": "string", "format": "password", "example": "newPassword123" }, "confirm_password": { "type": "string", "format": "password", "example": "newPassword123" } } } } } }, "responses": { "200": { "description": "Password reset successfully" } }, "operationId": "post.customer.auth.resetPassword" } }, "/api/customer/ride/create": { "post": { "tags": [ "Customer - Rides & Bidding" ], "summary": "Create New Ride Request (Instant or Bidding)", "description": "Dispatches a new ride request and notifies all active nearby drivers in the specified zone.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "zoneId", "in": "header", "required": true, "schema": { "type": "string", "example": "zone_kathmandu_valley" }, "description": "Operating Zone UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pickup_coordinates", "destination_coordinates", "pickup_address", "destination_address", "vehicle_category_id", "payment_method" ], "properties": { "pickup_coordinates": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "example": 27.7172 }, "longitude": { "type": "number", "example": 85.324 } } }, "destination_coordinates": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "example": 27.671 }, "longitude": { "type": "number", "example": 85.3288 } } }, "pickup_address": { "type": "string", "example": "Durbar Marg, Kathmandu" }, "destination_address": { "type": "string", "example": "Patan Durbar Square, Lalitpur" }, "vehicle_category_id": { "type": "string", "example": "cat_sedan_4_seater" }, "estimated_fare": { "type": "number", "example": 380 }, "customer_bid_fare": { "type": "number", "example": 400, "description": "Optional custom passenger bid" }, "payment_method": { "type": "string", "enum": [ "cash", "wallet", "digital_payment" ], "example": "cash" }, "note": { "type": "string", "example": "Waiting near gate 2" } } } } } }, "responses": { "200": { "description": "Ride Request created successfully", "content": { "application/json": { "example": { "response_code": "ride_request_created_200", "message": "Searching for nearby drivers...", "content": { "id": "trip_req_82736152", "status": "pending", "estimated_fare": 380, "otp": "4819", "pickup_address": "Durbar Marg, Kathmandu", "destination_address": "Patan Durbar Square, Lalitpur", "created_at": "2026-10-17T18:30:00Z" } } } } } }, "operationId": "post.customer.ride.create" } }, "/api/customer/ride/get-estimated-fare": { "post": { "tags": [ "Customer - Rides & Bidding" ], "summary": "Calculate Estimated Fare for All Vehicle Categories", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "zoneId", "in": "header", "required": true, "schema": { "type": "string", "example": "zone_kathmandu_valley" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pickup_coordinates", "destination_coordinates" ], "properties": { "pickup_coordinates": { "$ref": "#/components/schemas/Coordinate" }, "destination_coordinates": { "$ref": "#/components/schemas/Coordinate" } } } } } }, "responses": { "200": { "description": "Fare options with distance, duration, and prices per vehicle category", "content": { "application/json": { "example": { "response_code": "default_200", "content": { "distance_km": 7.4, "duration_minutes": 22, "categories": [ { "id": "cat_bike", "name": "Bike / Scooter", "estimated_fare": 140, "eta_minutes": 4 }, { "id": "cat_sedan", "name": "Standard Sedan Car", "estimated_fare": 380, "eta_minutes": 7 }, { "id": "cat_comfort", "name": "Comfort SUV 6-Seater", "estimated_fare": 550, "eta_minutes": 10 } ] } } } } } }, "operationId": "post.customer.ride.getEstimatedFare" } }, "/api/customer/ride/bidding-list/{trip_request_id}": { "get": { "tags": [ "Customer - Rides & Bidding" ], "summary": "Get Real-Time Driver Bids for a Trip", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "trip_request_id", "in": "path", "required": true, "schema": { "type": "string", "example": "trip_req_82736152" } } ], "responses": { "200": { "description": "List of driver bids with rating and arrival ETA", "content": { "application/json": { "example": { "response_code": "default_200", "content": [ { "bid_id": "bid_91823", "bid_fare": 390, "driver_id": "drv_38172", "driver_name": "Bikash Thapa", "driver_avatar": "https://iservers.blr1.cdn.digitaloceanspaces.com/yatra/driver/avatar.webp", "driver_rating": 4.9, "vehicle_details": "White Suzuki Dzire - Ba 2 Cha 4920", "eta_minutes": 5 } ] } } } } }, "operationId": "get.customer.ride.biddingList" } }, "/api/customer/ride/trip-action": { "post": { "tags": [ "Customer - Rides & Bidding" ], "summary": "Accept or Reject a Driver Bid / Cancel Ride", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trip_request_id", "action" ], "properties": { "trip_request_id": { "type": "string", "example": "trip_req_82736152" }, "action": { "type": "string", "enum": [ "accept", "reject", "cancel" ], "example": "accept" }, "driver_id": { "type": "string", "example": "drv_38172" }, "cancellation_reason": { "type": "string", "example": "Driver took too long to arrive" } } } } } }, "responses": { "200": { "description": "Action processed successfully", "content": { "application/json": { "example": { "response_code": "trip_action_200", "message": "Driver bid accepted! Driver is arriving.", "content": { "trip_status": "accepted", "otp": "4819" } } } } } }, "operationId": "post.customer.ride.tripAction" } }, "/api/customer/ride/track-location": { "post": { "tags": [ "Customer - Rides & Bidding" ], "summary": "Track Live Driver Location During Active Ride", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trip_request_id" ], "properties": { "trip_request_id": { "type": "string", "example": "trip_req_82736152" } } } } } }, "responses": { "200": { "description": "Real-time driver coordinates and ETA", "content": { "application/json": { "example": { "response_code": "default_200", "content": { "driver_latitude": 27.718, "driver_longitude": 85.3235, "bearing": 182.5, "eta_minutes": 3, "trip_status": "ongoing" } } } } } }, "operationId": "post.customer.ride.trackLocation" } }, "/api/customer/ride/details/{trip_request_id}": { "get": { "tags": [ "Customer - Rides & Bidding" ], "summary": "Get Detailed Trip Overview & Invoice", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "trip_request_id", "in": "path", "required": true, "schema": { "type": "string", "example": "trip_req_82736152" } } ], "responses": { "200": { "description": "Full trip details, fare breakdown, and driver info" } }, "operationId": "get.customer.ride.details" } }, "/api/customer/parcel/category": { "get": { "tags": [ "Customer - Parcel Delivery" ], "summary": "Get Available Parcel Categories and Weight Limits", "responses": { "200": { "description": "List of parcel categories (Documents, Electronics, Food, Fragile)", "content": { "application/json": { "example": { "response_code": "default_200", "content": [ { "id": "par_doc", "name": "Documents & Envelopes", "max_weight_kg": 2, "base_fee": 100 }, { "id": "par_box", "name": "Medium Box / Gifts", "max_weight_kg": 10, "base_fee": 250 } ] } } } } }, "operationId": "get.customer.parcel.category" } }, "/api/customer/ride/ongoing-parcel-list": { "get": { "tags": [ "Customer - Parcel Delivery" ], "summary": "Get Customer Active Out-For-Delivery Parcels", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of live parcel shipments with driver contact and tracking status" } }, "operationId": "get.customer.ride.ongoingParcelList" } }, "/api/driver/auth/login": { "post": { "tags": [ "Driver - Authentication & Status" ], "summary": "Driver Login via Phone & Password", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email_or_phone", "password" ], "properties": { "email_or_phone": { "type": "string", "example": "+9779841234567" }, "password": { "type": "string", "format": "password", "example": "driverPass123" } } } } } }, "responses": { "200": { "description": "Driver authenticated successfully", "content": { "application/json": { "example": { "response_code": "auth_login_200", "content": { "token": "2|DriverBearerToken...", "is_online": 1, "driver": { "id": "drv_38172", "name": "Bikash Thapa", "rating": 4.9, "wallet_balance": 3420, "vehicle_status": "approved" } } } } } } }, "operationId": "post.driver.auth.login" } }, "/api/driver/update-online-status": { "post": { "tags": [ "Driver - Authentication & Status" ], "summary": "Toggle Driver Online / Offline Duty Status", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "latitude", "in": "header", "required": true, "schema": { "type": "number", "example": 27.7172 } }, { "name": "longitude", "in": "header", "required": true, "schema": { "type": "number", "example": 85.324 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "integer", "enum": [ 0, 1 ], "example": 1, "description": "1 = Online, 0 = Offline" } } } } } }, "responses": { "200": { "description": "Status updated successfully" } }, "operationId": "post.driver.updateOnlineStatus" } }, "/api/driver/update/fcm-token": { "put": { "tags": [ "Driver - Authentication & Status" ], "summary": "Update Driver Push Notification FCM Token", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fcm_token" ], "properties": { "fcm_token": { "type": "string", "example": "eM...driver_fcm_token..." } } } } } }, "responses": { "200": { "description": "Token updated" } }, "operationId": "put.driver.update.fcmToken" } }, "/api/driver/ride/pending-ride-list": { "get": { "tags": [ "Driver - Ride Dispatch & Bidding" ], "summary": "Get Live Pending Ride Requests in Driver Zone", "description": "Real-time pool of rides available for bidding or immediate acceptance.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "zoneId", "in": "header", "required": true, "schema": { "type": "string", "example": "zone_kathmandu_valley" } }, { "name": "latitude", "in": "header", "required": true, "schema": { "type": "number", "example": 27.7172 } }, { "name": "longitude", "in": "header", "required": true, "schema": { "type": "number", "example": 85.324 } } ], "responses": { "200": { "description": "List of pending rides in vicinity", "content": { "application/json": { "example": { "response_code": "default_200", "content": [ { "id": "trip_req_82736152", "pickup_address": "Durbar Marg, Kathmandu", "destination_address": "Patan Durbar Square, Lalitpur", "distance_km": 7.4, "estimated_fare": 380, "customer_name": "Aarav Sharma", "customer_rating": 4.8 } ] } } } } }, "operationId": "get.driver.ride.pendingRideList" } }, "/api/driver/ride/bid": { "post": { "tags": [ "Driver - Ride Dispatch & Bidding" ], "summary": "Submit Price Bid for a Pending Ride", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trip_request_id", "bid_fare" ], "properties": { "trip_request_id": { "type": "string", "example": "trip_req_82736152" }, "bid_fare": { "type": "number", "example": 400 } } } } } }, "responses": { "200": { "description": "Bid submitted to customer" } }, "operationId": "post.driver.ride.bid" } }, "/api/driver/ride/coordinate-arrival": { "put": { "tags": [ "Driver - Ride Dispatch & Bidding" ], "summary": "Notify Passenger Driver Has Reached Pickup Location", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trip_request_id" ], "properties": { "trip_request_id": { "type": "string", "example": "trip_req_82736152" } } } } } }, "responses": { "200": { "description": "Customer notified of arrival at pickup point" } }, "operationId": "put.driver.ride.coordinateArrival" } }, "/api/driver/ride/match-otp": { "post": { "tags": [ "Driver - Ride Dispatch & Bidding" ], "summary": "Verify Customer Ride OTP to Start Trip", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trip_request_id", "otp" ], "properties": { "trip_request_id": { "type": "string", "example": "trip_req_82736152" }, "otp": { "type": "string", "example": "4819" } } } } } }, "responses": { "200": { "description": "OTP matched! Trip started (status = ongoing)", "content": { "application/json": { "example": { "response_code": "otp_matched_200", "message": "Trip started successfully", "content": { "trip_status": "ongoing", "started_at": "2026-10-17T18:40:00Z" } } } } }, "403": { "description": "Incorrect OTP code" } }, "operationId": "post.driver.ride.matchOtp" } }, "/api/driver/ride/update-status": { "put": { "tags": [ "Driver - Ride Dispatch & Bidding" ], "summary": "Update Trip Lifecycle Status (completed / cancelled)", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trip_request_id", "status" ], "properties": { "trip_request_id": { "type": "string", "example": "trip_req_82736152" }, "status": { "type": "string", "enum": [ "completed", "cancelled" ], "example": "completed" }, "cancellation_reason": { "type": "string", "example": "Customer requested cancellation" } } } } } }, "responses": { "200": { "description": "Trip status updated and invoice calculated" } }, "operationId": "put.driver.ride.updateStatus" } }, "/api/driver/ride/track-location": { "post": { "tags": [ "Driver - Live Location & Telemetry" ], "summary": "Stream Driver GPS Telemetry Coordinates", "description": "Called continuously (every 3-5 seconds) by the Driver App during on-duty or active trips.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "example": 27.7175 }, "longitude": { "type": "number", "example": 85.3242 }, "bearing": { "type": "number", "example": 95.2, "description": "Compass heading in degrees (0-360)" }, "speed": { "type": "number", "example": 32.5, "description": "Speed in km/h" }, "trip_request_id": { "type": "string", "example": "trip_req_82736152" } } } } } }, "responses": { "200": { "description": "Coordinates buffered and broadcasted" } }, "operationId": "post.driver.ride.trackLocation" } }, "/api/driver/income-statement": { "get": { "tags": [ "Driver - Earnings & Financials" ], "summary": "Get Driver Earnings Statement (Daily, Weekly, Monthly)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "today", "this_week", "this_month", "all_time" ], "example": "this_week" } } ], "responses": { "200": { "description": "Income analytics breakdown", "content": { "application/json": { "example": { "response_code": "default_200", "content": { "total_earnings": 14250, "total_trips": 38, "cash_collected": 8900, "admin_fee_paid": 1425, "net_profit": 12825 } } } } } }, "operationId": "get.driver.incomeStatement" } }, "/api/driver/withdraw/request": { "post": { "tags": [ "Driver - Earnings & Financials" ], "summary": "Submit Payout / Balance Withdrawal Request", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "withdraw_method_id" ], "properties": { "amount": { "type": "number", "example": 2500 }, "withdraw_method_id": { "type": "string", "example": "wm_bank_nabil" }, "note": { "type": "string", "example": "Weekly payout" } } } } } }, "responses": { "200": { "description": "Withdrawal request registered for admin approval" } }, "operationId": "post.driver.withdraw.request" } }, "/api/driver/vehicle/category/list": { "get": { "tags": [ "Driver - Vehicles & Documents" ], "summary": "Get Registered Vehicle Categories for Driver Onboarding", "responses": { "200": { "description": "List of categories (Motorbike, Sedan, Hatchback, SUV, Parcel Van)" } }, "operationId": "get.driver.vehicle.category.list" } }, "/api/driver/vehicle/brand/list": { "get": { "tags": [ "Driver - Vehicles & Documents" ], "summary": "Get Vehicle Manufacturer Brands (Suzuki, Hyundai, Honda, Bajaj)", "responses": { "200": { "description": "List of brands" } }, "operationId": "get.driver.vehicle.brand.list" } }, "/api/driver/zone/list": { "get": { "tags": [ "Zones & Geofencing" ], "summary": "Get All Active Operating Zones & Geofence Coordinates", "responses": { "200": { "description": "List of operational zones with polygon boundaries", "content": { "application/json": { "example": { "response_code": "default_200", "content": [ { "id": "zone_kathmandu_valley", "name": "Kathmandu Valley Metropolitan", "is_active": true, "coordinates": [ { "lat": 27.76, "lng": 85.28 }, { "lat": 27.76, "lng": 85.38 }, { "lat": 27.65, "lng": 85.38 }, { "lat": 27.65, "lng": 85.28 } ] } ] } } } } }, "operationId": "get.driver.zone.list" } }, "/api/driver/config/get-zone-id": { "get": { "tags": [ "Zones & Geofencing" ], "summary": "Detect Zone ID by Given Latitude & Longitude", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "example": 27.7172 } }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "number", "example": 85.324 } } ], "responses": { "200": { "description": "Matching Zone identifier", "content": { "application/json": { "example": { "response_code": "default_200", "content": { "zone_id": "zone_kathmandu_valley", "zone_name": "Kathmandu Valley Metropolitan" } } } } } }, "operationId": "get.driver.config.getZoneId" } }, "/api/customer/config/geocode-api": { "get": { "tags": [ "Zones & Geofencing" ], "summary": "Reverse Geocode Coordinates into Street Address", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "example": 27.7172 } }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "number", "example": 85.324 } } ], "responses": { "200": { "description": "Formatted address, area, city, and country" } }, "operationId": "get.customer.config.geocodeApi" } }, "/api/customer/config/place-api-autocomplete": { "get": { "tags": [ "Zones & Geofencing" ], "summary": "Search Places & Landmark Suggestions (Google Maps Engine)", "parameters": [ { "name": "search_text", "in": "query", "required": true, "schema": { "type": "string", "example": "Tribhuvan" } } ], "responses": { "200": { "description": "Suggested places with place_id and main text" } }, "operationId": "get.customer.config.placeApiAutocomplete" } }, "/api/customer/configuration": { "get": { "tags": [ "System & Shared Configuration" ], "summary": "Get Customer Global Business Configuration", "description": "Returns currency symbols, base URLs, minimum ride charges, SOS emergency phone, and feature switches.", "responses": { "200": { "description": "Platform settings", "content": { "application/json": { "example": { "currency_symbol": "Rs.", "currency_code": "NPR", "base_url": "http://localhost:8085", "otp_resend_time": 60, "safety_phone": "100", "is_bidding_enabled": 1 } } } } }, "operationId": "get.customer.configuration" } }, "/api/customer/config/cancellation-reason-list": { "get": { "tags": [ "System & Shared Configuration" ], "summary": "Get Pre-configured Ride Cancellation Reasons", "responses": { "200": { "description": "List of standard reasons for cancelling a ride" } }, "operationId": "get.customer.config.cancellationReasonList" } }, "/api/user/logout": { "post": { "tags": [ "System & Shared Configuration" ], "summary": "Revoke Active Token and Logout User", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "User logged out and token invalidated" } }, "operationId": "post.user.logout" } }, "/api/user/change-password": { "post": { "tags": [ "System & Shared Configuration" ], "summary": "Change Password for Authenticated User", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "old_password", "password", "confirm_password" ], "properties": { "old_password": { "type": "string", "format": "password", "example": "oldPass123" }, "password": { "type": "string", "format": "password", "example": "newPass456" }, "confirm_password": { "type": "string", "format": "password", "example": "newPass456" } } } } } }, "responses": { "200": { "description": "Password updated successfully" } }, "operationId": "post.user.changePassword" } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "OAuth2 bearer token (Laravel Passport)", "description": "Input Bearer token obtained from login or registration endpoint. Example: `1|AbCdEf123456...`" } }, "schemas": { "StandardApiResponse": { "type": "object", "properties": { "response_code": { "type": "string", "example": "default_200" }, "message": { "type": "string", "example": "Operation successful" }, "content": { "type": "object" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "ValidationErrorResponse": { "type": "object", "properties": { "response_code": { "type": "string", "example": "validation_error_422" }, "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "array", "example": [ { "error_code": "phone", "message": "The phone field is required." } ] } } }, "Coordinate": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "format": "float", "example": 27.7172 }, "longitude": { "type": "number", "format": "float", "example": 85.324 } } } } } }