---
# System prepended metadata

title: Proposed Engineroom revamp API

---

# Proposed Engineroom revamp API

## Required services:
- Auth service:
    - [Search-customer-by-phone-number](#Search-customer-by-phone-number)
- Data Science:
- Ratings:
    - [Get-driver-rating-tags](#Get-driver-rating-tags)
    - [Get-drivers-rating-details](#Get-drivers-rating-details)
    - [Get-drivers-rating](#Get-drivers-rating)
    - [Get-customers-rating-details](#Get-customers-rating-details)
    - [Get-customers-rating](#Get-customers-rating)
- Rides:
    - [Get driver total rides](#Get-drivers-total-rides)
    - [Get-customers-rides-details-by-phone-no](#Get-customers-rides-details-by-phone-no)
    - [Rides-listing-and-search](#Rides-listing-and-search)
    - [Get-rides-details](#Get-rides-details)
    - [Update-ride-details](#Update-ride-details)
    - [Block-future-pairing-of-customer-amp-driver](#Block-future-pairing-of-customer-amp-driver)
    - [Appease-customer-for-a-ride](#Appease-customer-for-a-ride)
    - [Change-customer-rating-for-a-ride](#Change-customer-rating-for-a-ride)
    - [Change-driver-rating-for-a-ride](#Change-driver-rating-for-a-ride)
- Quest:
    - [Quest-history-for-driver-last-3-months-order-by-latest](#Quest-history-for-driver-last-3-months-order-by-latest)
- Driver management: dms.service
    - [Driver details by phone no](#Driver-details-by-phone-no)
    - [Make driver online/offline](#Make-driver-onlineoffline)
- Payouts:
    - [Get-drivers-current-total-due](#Get-drivers-current-total-due)
    - [Get-rides-flagged-status](#Get-rides-flagged-status)
    - [Get-ride-flagged-status](#Get-ride-flagged-status)
- Wallet:
    - [GET-Rides-payment-method](#GET-Rides-payment-method)


## Driver profile screen


### Driver details by phone no
> [locked]
> GET dms.service/drivers?q[phone_number]=01772793058
> +DMS 
```json
{
    data: [
        {
            id: 2412,
            profile_picture: "cdn.pathao.com/pp.jpg",
            phone_number: "01763049088",
            suspended: true, 
            type: {
                id: "motorbike", // motorbikebike|car|bicyle|auto,
                name: "Bike"
            },
            freelancer: true,
            joining_date: "",                // string|null
            payment: {
                type: "mfs",                 // cash|mfs|bank|digital
                account: {                   // null|object null-on-cash
                    number: "01824018123",
                    type: "bKash"
                } 
            },
            city: {
                id: 1,
                name: "Dhaka", // Dhaka|Kathmundu etc.
            },
            country: {
                id: 1,
                name: "Bangladesh" // Bangladesh|Nepal etc.
            },
            vehicle: [
                {
                    id: 881, 
                    active: true,
                    type: { 
                        id: 3,
                        name: 'Car',
                        category: {        // null|object
                            id: 1,
                            name: "Lite"
                        }
                    },
                    country: {
                        id: 1,
                        name: "Bangladesh"
                    },
                    model: {
                        name: "",         // string/null
                        company: "",      // string|null
                        series: "",       // string|null
                        year: "",         // string|null
                        color: ""         // string|null
                    },
                    registration: {
                        name: "",         // string/null
                        region: "",       // string/null
                        series: "",       // string/null
                        number: ""        // string/null
                    }, 
                }
            ]
        }
    ]
}
```


### Make driver online/offline
> [pending]
> POST dms.service/drivers/:driver_id/toggle-online

payload:
```json
{ 
    is_online: boolean 
}
```

### Get drivers total rides
> GET rides.service/drivers/profile?phone_no=01763049077
> [locked]
> +rides +ratings
```json
{
    data: {
        total_rides: 100, // Rides Service
        ?completion_rate: number, //x
    }
}

```

### Get drivers current total due
> GET payout.service/drivers/profile?phone_no=01763049077
> [pending]
> +payouts
```json
{
    data: {
        current_total_due: 2000, // Payout service
    }
}
```

### Quest history for driver last 3 months order by latest
> GET quest.service/drivers/:driver_id/quests?page=1&per_page=10
> [locked]
> +quest
```json
{
    data: [{
        name: "quest name",
        is_active: boolean,
        date: {start_date, end_date, start_time, end_time},
        required_completion_rate,
        completion_rate,
        total_completed,
        total_assigned,
        completed_rides,
        required_rides,
        milestones: { required_milestones, achieved_milestones},
        reward: [100, 0, 0], 
        currency: BDT|RUPEE
    }],
    meta: {
        total: 10,
        page: 1,
        per_page: 5,
        next_page: 2,
        previous_page: null,
    }
}

```
> Payout history for driver (INCOMPLETE, waiting for payout new version)
> GET payout.service/drivers/:driver_id/payouts?page=1&per_page=10&transaction_type=ride_payout|food_payout|parcel_payout
> +payout
```json
{
    data: [{
        processed_on: timestamp,
        description: "bounce back"
        transaction_type: ride_payout|food_payout|parcel_payout
        amount: 100,
        promo_amount: 50,
        due: 20,
        total_due: 90
    }],
    meta: {
        total: 10,
        page: 1,
        per_page: 5,
        next_page: 2,
        previous_page: null,
    }
}
```


## Customer profile
### Search customer by phone number
> GET auth.service/customers/profile?phone_no=01763049088&type=user/driver
> [locked]
> +auth
```json
{
    data: {
        profile_picture: "cdn.pathao.com/pp.jpg",
        name: "Ziaul Haq",
        customer_id: 1,
        joining_date: timestamp,
        phone_no: 01763049088,
        is_suspended: false,
        email: nullable,
    }
}
```

### Get customers rides details by phone no
> GET rides.service/customers/profile?phone_no=01763049077 
> [locked]
> +rides +ratings
```json
{
    data: {
        total_bikes_rides_taken: 99, // rides service
        total_car_rides_taken: 99, // rides service
    }
}
```


> Customer's promo history [locked] same as promo dashboard
> GET ds.service/customers/promo-history?phone_no=01763049077&vertical=Food|Ride|Parcel|Car+,page=1&per_page=10
> +ds
```json
{
    data: [{
        start_time: timestamp,
        promo_code: 50FREE,
        promo_type: total|rides_discount_pc,
        promo_title: string,
        expiry_date: timestamp,
        description: "50% (upto 35)",
        cap: -1|0|300|number,
        city: {id, name},
        vertical: Food|Ride|Parcel|Car+,
        is_applied: true,
        total_transactions: 56|number,
    }],
    meta: {
        total: 10,
        page: 1,
        per_page: 5,
        next_page: 2,
        previous_page: null,
    }
}
```


## Ride screens

### Rides listing and search
> GET rides.service/rides?city_id&ride_type&ride_status&hashed_id&customer_phone_no&driver_phone_no&start_datetime&end_datetime,per_page=20,page=1
> +rides
> [locked]
```json
{
    data: [{
        hashed_id,
        created_at,
        customer: { name, phone_no, profile_picture},
        driver: { name, phone_no, profile_picture},
        fare: '200',
        currency: 'BDT'|'<or>symbol',
        payment_type: cash|wallet,
        promo_code: 50FREE,
        customer_rating: <rating_value/1-5>,
        driver_rating: <rating_value/1-5>,
        ride_status: started|completed|accepted|(+)
        is_reported: false,
        driver_commission_percentage: 80
    }],
    meta: {
        total: <total_pages_number>,
        page: 1,
        per_page: 5,
        // next_page: 2,
        // previous_page: null,
    }
}
```


### Get rides flagged status
> POST payouts.service/rides/is-flagged
> [pending]
> Payload
```json 
{
    order_ids: [1,2,3]
}
```

> Response
```json
{
    data: [
        {
            order_id,
            is_flagged: boolean, // payout
        }
    ]
}
```

### Get ride flagged status
> GET payouts.service/rides/is-flagged/:hashed_id 
> [pending]
```json
{
    data: {
        is_flagged: boolean, // payout
    }
}
```


### GET Rides payment method
> GET wallets.service/rides/:hashed_id
> [pending]
```json
{
    data: {
        payment_method: Bkash, // Wallet service    
    }
}
```

### Get rides details
> GET rides.service/:hashed_id
> +rides
```json
{
    data: {
        ride_id,
        hashed_id: "HASC45",
        ride_status: "COMPLETED",
        created_at: "2010-12-12 00:02:23",
        assigned_at: "2010-12-12 00:02:23",
        accepted_at: "2010-12-12 00:02:23",
//        arrived_at: "2010-12-12 00:02:23",
        started_at: "2010-12-12 00:02:23",
        ended_at: "2010-12-12 00:02:23",
        ?assignment_details: { address: "Banani, Dhaka", lat, lng}, // blocker
        selected_pickup: {lat, lng}, 
        actual_pickup: {lat, lng},
        selected_dropoff:  {lat, lng},
        actual_dropoff:  {lat, lng},
        is_reported_by_customer: false,
        is_reported_by_driver: false,
        is_block_paired: false,
        driver_feedback: {
            rating: 5,
        },
        customer_feedback: {
            rating: 3,
            has_given_halmet: true,
            tags: "Professional, Well behaved",
        },
        driver: {
            name:"imran",
            phone_no: "01763049088",
            mfs: "Bkash 01763049088",
            vehicle_info: "Apache TVS,HA-23-455",
            ?is_online: false, // driver service
            is_suspended: false,
            driver_type: {id: 1, label: "Bike"},
            profile_pic: "cdn.pathao.com/pp.jpg"
        },
        customer: {
            id,
            name:"Fahim",
            phone_no: "018888999",
            profile_pic: "cdn.pathao.com/pp.jpg",
            total_rides_taken: 99,
            is_suspended: false,
            rating
        },
        fare_currency: "BDT",
        base_fare: 20,
        fare_per_km: 12,
        fare_per_min: 0.5,
        promo: {
            description: "get 50Off flat",
            label: 50OFF
        },
        estimated_fare_breakdown: {
            distance: 17.73 [km],
            surge: {times: 1, charge: 0},
            duration: 34 [minute],
            sub_total: 239.76,
            driver_cut: 201.52,
            pathao_commission: 38.24
        },
        original_fare_breakdown: {
            distance: 17.73 [km],
            surge: 1,
            surge_amount: 0,
            duration: 34 [minute],
            sub_total: 239.76,
            driver_cut: 201.52,
            pathao_commission: 38.24,
            has_threshold_applied: false // upfront
        },
        final_fare_breakdown: {
            distance: 17.73 [km],
            surge: 1,
            surge_amount: 0,
            duration: 34 [minute],
            sub_total: 239.76,
            driver_cut: 201.52,
            pathao_commission: 38.24,
            cash_promo_discount: 0,
            digital_promo_discount: 15,
            fare: float, // users_paid_amount, collected_cash
            rounding: float
        },
        updated_fare_breakdown: {
            distance: 17.73 [km],
            surge: {times: 1, charge: 0},
            duration: 34 [minute],
            sub_total: 239.76,
            driver_cut: 201.52, // riders_cut
            pathao_commission: 38.24, // pathaos_cut
            cash_promo_discount: number,
            digital_promo_discount: number,
            fare: float, collected_cash
            rounding: float,
        },
        
    }
}
```

### Get driver rating tags 
> GET ratings.service/customer-feedback-tags
> [pending]
```json
{
    data: ["professional", "good"]
}
```



### Get drivers rating details
> GET rating.service/drivers/:driver_id/customer-feedbacks
> [locked]
```json
{
    data: {
        rating: { percentage: "90" },
        ratings: [
            { rating: 5, count: 60},
            { rating: 4, count: 40},
        ]
    }
}
```


### Get drivers rating
> GET rating.service/drivers/:driver_id/ratings_percentage
> [locked]
```json
{
    data: {
        rating_percentage: "90"
    }
}
```

### Get customers rating details
> GET rating.service/customers/:customer_id/driver-feedbacks
> [locked]
```json
{
    data: {
        rating: { percentage: "90" },
        ratings: [
            { rating: 5, count: 60},
            { rating: 4, count: 40},
            { rating: 3, count: 40},
            { rating: 2, count: 40},
            { rating: 1, count: 40},
            
        ]
    }
}
```

### Get customers rating
> GET rating.service/customers/:customer_id/ratings_percentage
>  [locked]
```json
{
    data: {
        rating_percentage: "90"
    }
}
```


### Update ride details
> PUT rides.service/:hashed_id
> [locked]
 
payload:
```json
{
    pickup: {lat, lng},
    dropoff: {lat, lng},
    distance: 2.4 [km],
    duration: 40 [min],
}
```

### Change driver rating for a ride
> POST rides.service/:hashed_id/customer-feedback
>  [locked]

payload:
```json
{
    tags: "overcharged,navigation-issue"
    rating: 1-5,
    had_halment: true
}
```

### Change customer rating for a ride
> POST rides.service/:hashed_id/driver-feedback
>  [locked]
>  
payload:
```json
{
    rating: 1|5
}
```

### Appease customer for a ride
> POST rides.service/:hashed_id/appease-customer
> [locked]

payload:
```json
{
    appeasement_type: percentage|flat,
    appeasement_amount: 100
}
```

### Block future pairing of customer & driver
> POST rides.service/:hashed_id/block-pairing
> [locked]

payload:
```json
{
    days: 7|30|180|365
}
```
