---
# System prepended metadata

title: API Documentation

---

# API Documentation

## Overview

This API provides endpoints to manage user and driver information, retrieve active orders, and cancel ongoing orders. Authentication is enforced using **Client ID** and **Client Secret**.

---

## Authentication

All API requests must include the following headers:

### Headers:
- **Client-Id**: Unique client ID issued during registration.
- **Client-Secret**: Client secret issued during registration.

### Security Rules:
1. Both `Client-Id` and `Client-Secret` must match the records in the system.
2. Rate limits apply (max 10 requests per minute per user). Requests exceeding this limit will receive an error response.

---

## Endpoints

### 1. Retrieve User Information

**Endpoint:** `GET /api/user-info`
**Description:** Fetch user information based on the phone number, including whether the user has an active order.

#### Request:
- **Headers**:
  - `Client-Id`: Client ID issued during registration.
  - `Client-Secret`: Client Secret issued during registration.
- **Query Parameters**:
  - `phone_number` (string): The phone number of the user.

#### Response:
- **Success Response**:
  - **HTTP Status Code**: `200 OK`
    ```json
    {
      "status": "success",
      "data": {
        "is_registered": true,
        "has_runnding_ride": true,
        "country_id": 1, // Country ID, 1 for BD, 2 for NP
        "city_id": 1,
        "ride_type": "1|2|3|4|5|6|7|8|9", // Bike, CarLite, CarPlus, CarPrime, CarMax, CarCoach, Bicycle, Tuktuk
      }
    }
    ```
- **Unregistered User Response**:
  - **HTTP Status Code**: `404 Not Found`
    ```json
    {
      "status": "error",
      "message": "The provided phone number is not registered. Please use a registered phone number to proceed.",
      "error_code": 1001
    }
    ```

---

### 2. Retrieve Driver Information

**Endpoint:** `GET /api/driver-info`
**Description:** Fetch detailed information about a driver, including their `driver_type` and whether they have active orders.

#### Request:
- **Headers**:
  - `Client-Id`: Client ID issued during registration.
  - `Client-Secret`: Client Secret issued during registration.
- **Query Parameters**:
  - `phone_no` (string): The phone number of the driver.

#### Response:
- **Success Response**:
  - **HTTP Status Code**: `200 OK`
    ```json
    {
      "status": "success",
      "data": {
        "is_registered": true,
        "has_runnding_ride": true,
        "driver_type": 1, // DriverType.Bike
        "country_id": 1, // Country ID, 1 for BD, 2 for NP
        "city_id": 1,
        "ride_type": "1|2|3|4|5|6|7|8|9", // Bike, CarLite, CarPlus, CarPrime, CarMax, CarCoach, Bicycle, Tuktuk
      }
    }
    ```
- **Unregistered Driver Response**:
  - **HTTP Status Code**: `404 Not Found`
    ```json
    {
      "status": "error",
      "message": "The provided phone number is not registered. Please use a registered phone number to proceed.",
      "error_code": 1001
    }
    ```

#### Driver Types:
| Code | Driver Type |
|------|-------------|
| 1    | Bike        |
| 2    | CarPlus     |
| 4    | Bicycle     |
| 5    | CarLite     |
| 6    | Tuktuk      |
| 7    | CarPrime    |
| 8    | CarMax      |
| 9    | CarCoach    |

---

### 3. Cancel Active Order

**Endpoint:** `POST /api/cancel-active-order`
**Description:** Cancel an active order (ride, food, parcel) based on the provided `vertical` and `cancel_reason`.

#### Request:
- **Headers**:
  - `Client-Id`: Client ID issued during registration.
  - `Client-Secret`: Client Secret issued during registration.
- **Body**:
  ```json
  {
    "phone_no": "string",
    "vertical": "string",  // One of "ride", "food", "parcel"
    "cancel_reason": "string", // Cancellation reason slug
    "country_id": "1|2" // Country ID, 1 for BD, 2 for NP
  }
  ```

#### Vertical Parameter:
- `ride`: For ride cancellations.
- `food`: For food order cancellations (future use).
- `parcel`: For parcel cancellations.

#### ExampleCancel Reason Slugs:

##### User Cancellation Reasons (Ride):
1. **Bike**:
   - `ua_bike_refused_pickup` - Rider refused to pick me up
   - `ua_bike_pickup_or_destination_incorrect` - Incorrect pickup/destination location
   - `ua_bike_waiting_time_too_long` - Waited too long
   - `ua_bike_dont_need_ride` - Don't need ride anymore
   - `ua_bike_unreachable` - Rider unreachable
   - `ua_bike_rude` - Rider was rude
   - `ua_bike_vehicle_or_person_not_same` - Vehicle/person not matching
   - `ua_bike_refused_dp` - Refused digital payment
   - `ua_bike_ride_refused_destination` - Refused to go to destination
   - `ua_bike_rider_is_far_away` - Rider is too far
   - `ua_bike_asked_me_to_cancel` - Rider asked to cancel

2. **Car Plus**:
   - `ua_car_plus_refused_pickup` - Captain refused pickup
   - `ua_car_plus_pickup_or_destination_incorrect` - Incorrect location
   - `ua_car_plus_waiting_time_too_long` - Long wait
   - `ua_car_plus_dont_need_ride` - Don't need ride
   - `ua_car_plus_unreachable` - Captain unreachable
   - `ua_car_plus_rude` - Captain was rude
   - `ua_car_plus_vehicle_or_person_not_same` - Vehicle/person mismatch
   - `ua_car_plus_refused_dp` - Refused digital payment
   - `ua_car_plus_rider_is_far_away` - Captain is far
   - `ua_car_plus_asked_me_to_cancel` - Captain asked to cancel

##### Driver Cancellation Reasons (Ride):
1. **Bike**:
   - `da_bike_pickup_far_away` - Pickup location far
   - `da_bike_pickup_or_destination_incorrect` - Incorrect location
   - `da_bike_waiting_time_too_long` - Waited too long
   - `da_bike_unreachable` - User unreachable
   - `da_bike_more_than_1_person` - More than 1 passenger
   - `da_bike_rude` - User was rude
   - `da_bike_mistakenly_ordered` - Mistaken order
   - `da_bike_asked_to_cancel` - User requested cancellation
   - `da_bike_others` - Other reasons

2. **Car Plus**:
   - `da_car_plus_pickup_far_away` - Pickup location far
   - `da_car_plus_pickup_or_destination_incorrect` - Incorrect location
   - `da_car_plus_waiting_time_too_long` - Long wait
   - `da_car_plus_unreachable` - User unreachable
   - `da_car_plus_more_than_4_people` - More than 4 passengers
   - `da_car_plus_rude` - User was rude
   - `da_car_plus_mistakenly_ordered` - Mistaken order
   - `da_car_plus_had_too_many_baggages` - Too many bags
   - `da_car_plus_asked_to_cancel` - User requested cancellation
   - `da_car_plus_others` - Other reasons

##### Parcel Cancellation Reasons:
- `da_parcel_overweight_product` - Overweight product
- `da_parcel_pickup_or_destination_incorrect` - Incorrect location
- `da_parcel_sender_or_receiver_unreachable` - Sender/receiver unreachable
- `da_parcel_sender_requested_cancelation` - Sender requested cancellation
- `da_parcel_sender_pickup_location_far_away` - Pickup location too far
- `da_parcel_mistakenly_ordered` - Mistaken order
- `da_parcel_waited_long_time` - Long wait time
- `da_parcel_suspicious_goods` - Suspicious goods
- `da_parcel_others` - Other reasons

#### Response:
- **Successful Cancellation**:
  - **HTTP Status Code**: `200 OK`
    ```json
    {
      "status": "success",
      "message": "Order successfully canceled."
    }
    ```

- **Invalid Cancel Reason**:
  - **HTTP Status Code**: `400 Bad Request`
    ```json
    {
      "status": "error",
      "message": "Invalid cancel reason code.",
      "error_code": 2001
    }
    ```

- **Unsupported Vertical**:
  - **HTTP Status Code**: `400 Bad Request`
    ```json
    {
      "status": "error",
      "message": "Invalid vertical specified.",
      "error_code": 2002
    }
    ```

- **No Active Order**:
  - **HTTP Status Code**: `404 Not Found`
    ```json
    {
      "status": "error",
      "message": "No active order found for the user.",
      "error_code": 2003
    }
    ```

- **User Not Eligible to Cancel**:
  - **HTTP Status Code**: `403 Forbidden`
    ```json
    {
      "status": "error",
      "message": "User is not eligible to cancel the order.",
      "error_code": 2004
    }
    ```

---

### 4. Get Cancellation Reasons

**Endpoint:** `GET /api/cancellation-reasons`
**Description:** Retrieve a list of applicable cancellation reasons based on city, country, ride type, and user type.

#### Request:
- **Headers**:
  - `Client-Id`: Client ID issued during registration.
  - `Client-Secret`: Client Secret issued during registration.
- **Query Parameters**:
  - `city_id` (integer): City identifier
  - `country_id` (integer): Country identifier (1 for BD, 2 for NP)
  - `ride_type` (string): Type of ride (1: Bike, 2: CarLite, 3: CarPlus, etc.)
  - `user_type` (string): Type of user ("user" or "driver")

#### Response:
- **Success Response**:
  - **HTTP Status Code**: `200 OK`
    ```json
    {
      "status": "success",
      "data": {
        "reasons": [
          {
            "id": "string",
            "slug": "string",
            "title": "string",
            "description": "string"
          }
        ]
      }
    }
    ```

- **Invalid Parameters**:
  - **HTTP Status Code**: `400 Bad Request`
    ```json
    {
      "status": "error",
      "message": "Invalid parameters provided.",
      "error_code": 2005
    }
    ```

## Error Handling

### Common Error Response Format
```json
{
  "status": "error",
  "message": "string",
  "error_code": "integer"
}
```

### Error Codes

| Error Code | Description                                                               |
|------------|---------------------------------------------------------------------------|
| 1001       | Unregistered user (user not found in the system)                          |
| 1002       | Invalid phone number format                                               |
| 2001       | Invalid cancel reason code (for `cancel-active-order` endpoint)           |
| 2002       | Invalid vertical specified (e.g., unsupported vertical like "food")       |
| 2003       | No active order found for the user                                        |
| 2004       | User is not eligible to cancel the order (e.g., already completed, etc.)  |
| 2005       | Invalid parameters provided for cancellation reasons request              |
| 3001       | Authentication failure (missing or invalid Client-Id or Client-Secret)    |
| 3002       | Rate limit exceeded (more than 10 requests per minute)                    |
