# API Documentation - Thao tác đơn hàng (Driver App)

## Mục lục
1. [Cập nhật trạng thái lấy hàng thành công](#1-cập-nhật-trạng-thái-lấy-hàng-thành-công)
2. [Cập nhật trạng thái lấy hàng thất bại](#2-cập-nhật-trạng-thái-lấy-hàng-thất-bại)
3. [Cập nhật trạng thái giao hàng thành công](#3-cập-nhật-trạng-thái-giao-hàng-thành-công)
4. [Cập nhật trạng thái giao hàng thất bại](#4-cập-nhật-trạng-thái-giao-hàng-thất-bại)
5. [Lấy danh sách lý do thất bại](#5-lấy-danh-sách-lý-do-thất-bại)

---

## 1. Cập nhật trạng thái lấy hàng thành công

### 1.1. Cập nhật trạng thái lấy hàng thành công

**Endpoint**: `POST /api/DriverOrderOps/Pickup`  
**Authorization**: `DriverApp.Pickup`

Mô tả: API dùng để cập nhật trạng thái lấy hàng thành công từ tài xế.

**Request (Form-Data):**
- `Id` (int, required): ID của đơn hàng
- `AgencyId` (int, required): ID đại lý
- `MediaList` (IFormFile[], optional): Danh sách file media (ảnh, video) minh chứng lấy hàng

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": true
}
```

---

## 2. Cập nhật trạng thái lấy hàng thất bại

### 2.1. Cập nhật trạng thái lấy hàng thất bại

**Endpoint**: `POST /api/DriverOrderOps/PickupFail`  
**Authorization**: `DriverApp.PickupFail`

Mô tả: API dùng để cập nhật trạng thái lấy hàng thất bại kèm theo lý do cụ thể.

**Request (Form-Data):**
- `Id` (int, required): ID đơn hàng
- `Reason` (string, required): Lý do lấy hàng thất bại
- `Type` (int, required): Loại thao tác (1 = PickupFail). Với API này, giá trị `Type` thường là `1`.
- `MediaList` (IFormFile[], optional): Danh sách file ảnh minh chứng thất bại

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": true
}
```

---

## 3. Cập nhật trạng thái giao hàng thành công

### 3.1. Cập nhật trạng thái giao hàng thành công

**Endpoint**: `POST /api/DriverOrderOps/Delivery`  
**Authorization**: `DriverApp.Delivery`

Mô tả: API dùng để cập nhật trạng thái giao hàng thành công từ tài xế.

**Request (Form-Data):**
- `Id` (int, required): ID của đơn hàng
- `AgencyId` (int, required): ID đại lý
- `MediaList` (IFormFile[], optional): Danh sách file media (ảnh, video) minh chứng đã giao hàng

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": true
}
```

---

## 4. Cập nhật trạng thái giao hàng thất bại

### 4.1. Cập nhật trạng thái giao hàng thất bại

**Endpoint**: `POST /api/DriverOrderOps/DeliveryFail`  
**Authorization**: `DriverApp.DeliveryFail`

Mô tả: API dùng để cập nhật trạng thái giao hàng thất bại kèm theo lý do cụ thể.

**Request (Form-Data):**
- `Id` (int, required): ID đơn hàng
- `Reason` (string, required): Lý do giao hàng thất bại
- `Type` (int, required): Loại thao tác (2 = DeliveryFail). Với API này, giá trị `Type` thường là `2`.
- `MediaList` (IFormFile[], optional): Danh sách file ảnh minh chứng thất bại

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": true
}
```

---

## 5. Lấy danh sách lý do thất bại

### 5.1. Lấy danh sách lý do lấy/giao hàng thất bại

**Endpoint**: `GET /api/DriverOrderOps/GetFailReasons?type={type}`  
**Authorization**: `DriverApp.GetFailReasons`

Mô tả: API dùng để lấy danh sách các lý do thất bại được cấu hình sẵn cho thao tác lấy hàng hoặc giao hàng trên app. Chỉ trả về các lý do đang hoạt động (`IsActive = true`).

**Request (Query String):**
- `type` (int, required): `1` = Lấy hàng (Pickup), `2` = Giao hàng (Delivery)

> Nếu `type = 1` (Pickup): trả về các lý do có `Type = 1` (Pickup) hoặc `Type = 3` (Both).  
> Nếu `type = 2` (Delivery): trả về các lý do có `Type = 2` (Delivery) hoặc `Type = 3` (Both).

**Response:**
```json
[
  {
    "Id": 1,
    "Name": "Khách không nghe máy",
    "Description": "Đã gọi nhiều lần nhưng khách không nhấc máy",
    "Type": 1,
    "TypeName": "Lấy hàng",
    "IsMediaRequired": true,
    "MediaTitle": "Ảnh chụp màn hình lịch sử cuộc gọi",
    "SortOrder": 1,
    "IsActive": true,
    "CreatedTime": "2024-01-01T08:00:00+07:00",
    "CreatedByUserName": "admin",
    "UpdatedTime": "2024-01-10T10:00:00+07:00",
    "UpdatedByUserName": "admin"
  },
  {
    "Id": 2,
    "Name": "Sai địa chỉ",
    "Description": "Địa chỉ trên đơn hàng không chính xác hoặc không tồn tại",
    "Type": 3,
    "TypeName": "Cả hai",
    "IsMediaRequired": false,
    "MediaTitle": "",
    "SortOrder": 2,
    "IsActive": true,
    "CreatedTime": "2024-01-01T08:00:00+07:00",
    "CreatedByUserName": "admin",
    "UpdatedTime": null,
    "UpdatedByUserName": null
  }
]
```

**Ghi chú:**
- `Type`: `1` = Pickup, `2` = Delivery, `3` = Both (cả hai)
- `TypeName`: Tên loại hiển thị bằng tiếng Việt (`"Lấy hàng"`, `"Giao hàng"`, `"Cả hai"`)
- `IsMediaRequired`: Nếu `true`, lái xe cần phải tải ảnh minh chứng khi chọn lý do này
- `MediaTitle`: Tiêu đề/hướng dẫn loại ảnh cần tải (ví dụ: `"Ảnh chụp màn hình lịch sử cuộc gọi"`)
- Response trả về trực tiếp dạng **mảng** (array), đã sắp xếp theo `SortOrder` tăng dần

> [!NOTE]
> **Logic trả về**
> API chỉ trả về các lý do đang hoạt động (`IsActive = true`).
> Trường `Type` của lý do trả về có thể là giá trị truyền vào (1 hoặc 2) hoặc bằng 3 (Áp dụng cho cả hai).
