# 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`

    {
      "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`

    {
      "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`

    {
      "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`

    {
      "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**:

  {
    "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`

    {
      "status": "success",
      "message": "Order successfully canceled."
    }

- **Invalid Cancel Reason**:
- **HTTP Status Code**: `400 Bad Request`

    {
      "status": "error",
      "message": "Invalid cancel reason code.",
      "error_code": 2001
    }

- **Unsupported Vertical**:
- **HTTP Status Code**: `400 Bad Request`

    {
      "status": "error",
      "message": "Invalid vertical specified.",
      "error_code": 2002
    }

- **No Active Order**:
- **HTTP Status Code**: `404 Not Found`

    {
      "status": "error",
      "message": "No active order found for the user.",
      "error_code": 2003
    }

- **User Not Eligible to Cancel**:
- **HTTP Status Code**: `403 Forbidden`

    {
      "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`

    {
      "status": "success",
      "data": {
        "reasons": [
          {
            "id": "string",
            "slug": "string",
            "title": "string",
            "description": "string"
          }
        ]
      }
    }

- **Invalid Parameters**:
- **HTTP Status Code**: `400 Bad Request`

    {
      "status": "error",
      "message": "Invalid parameters provided.",
      "error_code": 2005
    }

## Error Handling

### Common Error Response Format

{
  "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) |