# Customer Reconciliation Slip - Action APIs Documentation

## Overview
This document describes the action APIs for Customer Reconciliation Slips, including Approve, Reject, Complete, and Excel Export functionalities.

---

## Table of Contents
1. [Approve Slip](#1-approve-slip)
2. [Reject Slip](#2-reject-slip)
3. [Complete Slip](#3-complete-slip)
4. [Export Excel List](#4-export-excel-list)
5. [Export Excel Detail](#5-export-excel-detail)
6. [Data Models](#data-models)
7. [Business Rules](#business-rules)
8. [Error Codes](#error-codes)

---

## 1. Approve Slip

### Endpoint
```
PUT /api/CustomerReconciliationSlip/Approve/{id}
```

### Description
Duyệt phiếu đối soát khách hàng. Chức năng này chỉ áp dụng cho **phiếu chi tiền (Receivable)** - công ty chuyển tiền cho khách hàng.

### Authorization
**Required Roles:** `CustomerReconciliationSlip.Approve` OR `Founder` OR `Accountant`

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | int | Yes | ID của phiếu đối soát cần duyệt |

### Request Example
```http
PUT /api/CustomerReconciliationSlip/Approve/123
Authorization: Bearer {token}
```

### Response

#### Success Response (200 OK)
```json
{
  "Message": "Duyệt phiếu thành công"
}
```

#### Error Responses

**400 Bad Request** - Trạng thái phiếu không hợp lệ
```json
{
  "Message": "Trạng thái phiếu không hợp lệ"
}
```

**401 Unauthorized** - Không xác định được người dùng
```json
{
  "Message": "Unauthorized"
}
```

**403 Forbidden** - Không có quyền duyệt phiếu
```json
{
  "Message": "Forbidden"
}
```

**404 Not Found** - Phiếu không tồn tại
```json
{
  "Message": "Phiếu không tồn tại"
}
```

### Business Logic

1. **Validation:**
   - Phiếu phải tồn tại
   - Phiếu phải ở trạng thái `PendingApproval` (Chờ duyệt)
   - Chỉ áp dụng cho phiếu loại `Receivable` (phiếu chi tiền)

2. **Process:**
   - Cập nhật trạng thái phiếu từ `PendingApproval` → `Approved`
   - Lưu thông tin người duyệt (ApprovedBy, ApprovedByUsername)
   - Lưu thời gian duyệt (ApprovedTime)
   - Ghi log hành động duyệt phiếu

3. **Side Effects:**
   - Tạo log trong bảng CustomerReconciliationLog
   - Có thể trigger notification cho người tạo phiếu

### Notes
- **Phiếu thu tiền (Payable)** không cần duyệt, bỏ qua bước này
- Sau khi duyệt, phiếu có thể chuyển sang trạng thái `Completed` thông qua API Complete

---

## 2. Reject Slip

### Endpoint
```
POST /api/CustomerReconciliationSlip/Reject
```

### Description
Từ chối phiếu đối soát khách hàng với lý do cụ thể. Áp dụng cho cả phiếu thu tiền và phiếu chi tiền.

### Authorization
**Required Roles:** 
- Người tạo phiếu (Creator)
- `CustomerReconciliationSlip.Reject`
- `Founder`
- `Accountant`

### Request Body
```json
{
  "Id": 123,
  "Reason": "Thông tin đơn hàng không chính xác, cần kiểm tra lại"
}
```

### Request Model: `RejectCustomerReconciliationSlipModel`
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| Id | int | Yes | ID của phiếu đối soát cần từ chối |
| Reason | string | Yes | Lý do từ chối (bắt buộc) |

### Request Example
```http
POST /api/CustomerReconciliationSlip/Reject
Content-Type: application/json
Authorization: Bearer {token}

{
  "Id": 123,
  "Reason": "Số tiền COD không khớp với thực tế"
}
```

### Response

#### Success Response (200 OK)
```json
{
  "Message": "Từ chối phiếu thành công"
}
```

#### Error Responses

**400 Bad Request** - Validation errors
```json
{
  "Message": "Vui lòng nhập lý do từ chối"
}
```

**400 Bad Request** - Không thể từ chối phiếu ở trạng thái này
```json
{
  "Message": "Không thể từ chối phiếu ở trạng thái này"
}
```

**401 Unauthorized**
```json
{
  "Message": "Unauthorized"
}
```

**403 Forbidden** - Không có quyền từ chối phiếu
```json
{
  "Message": "Forbidden"
}
```

**404 Not Found**
```json
{
  "Message": "Phiếu không tồn tại"
}
```

### Business Logic

1. **Validation:**
   - Phiếu phải tồn tại
   - Phiếu không được ở trạng thái `Completed` hoặc `Rejected`
   - Lý do từ chối không được để trống

2. **Permission Check:**
   - Người tạo phiếu có thể từ chối
   - Founder có thể từ chối
   - Accountant có thể từ chối
   - User có quyền `CustomerReconciliationSlip.Reject` có thể từ chối

3. **Process:**
   - Cập nhật trạng thái phiếu → `Rejected`
   - Lưu lý do từ chối vào `InternalNote`
   - Ghi log hành động từ chối với lý do

4. **Side Effects:**
   - Các đơn hàng trong phiếu bị từ chối sẽ được mở khóa
   - Có thể tạo phiếu đối soát mới với các đơn hàng này
   - Trigger notification cho người tạo phiếu

### Notes
- Phiếu bị từ chối có thể được tạo lại với thông tin chính xác
- Đơn hàng trong phiếu bị từ chối có thể được đưa vào phiếu đối soát khác

---

## 3. Complete Slip

### Endpoint
```
POST /api/CustomerReconciliationSlip/Complete
```

### Description
Hoàn thành phiếu đối soát và xác nhận thanh toán đã được thực hiện.

### Authorization
**Required Roles:** `CustomerReconciliationSlip.Complete` OR `Founder` OR `Accountant`

### Request Body
```json
{
  "Id": 123,
  "PaymentMethod": "Chuyển khoản Vietcombank",
  "TransactionCode": "FT24120912345678",
  "ProofImageUrl": "https://example.com/proof/image.jpg",
  "Note": "Đã chuyển khoản lúc 14:30 ngày 09/12/2024"
}
```

### Request Model: `CompleteCustomerReconciliationSlipModel`
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| Id | int | Yes | ID của phiếu đối soát cần hoàn thành |
| PaymentMethod | string | Yes | Phương thức thanh toán (tên ngân hàng/ví) |
| TransactionCode | string | No | Mã giao dịch ngân hàng |
| ProofImageUrl | string | No | URL ảnh chứng từ thanh toán |
| Note | string | No | Ghi chú thêm |

### Request Example
```http
POST /api/CustomerReconciliationSlip/Complete
Content-Type: application/json
Authorization: Bearer {token}

{
  "Id": 123,
  "PaymentMethod": "Chuyển khoản Vietcombank",
  "TransactionCode": "FT24120912345678",
  "ProofImageUrl": "https://storage.example.com/proofs/slip_123.jpg",
  "Note": "Đã chuyển khoản cho khách hàng"
}
```

### Response

#### Success Response (200 OK)
```json
{
  "Message": "Xác nhận thanh toán thành công"
}
```

#### Error Responses

**400 Bad Request** - Validation errors
```json
{
  "Message": "Vui lòng nhập phương thức thanh toán"
}
```

**400 Bad Request** - Phiếu chưa được duyệt (chỉ áp dụng cho phiếu Receivable)
```json
{
  "Message": "Phiếu chưa được duyệt"
}
```

**401 Unauthorized**
```json
{
  "Message": "Unauthorized"
}
```

**403 Forbidden**
```json
{
  "Message": "Forbidden"
}
```

**404 Not Found**
```json
{
  "Message": "Phiếu không tồn tại"
}
```

### Business Logic

1. **Validation:**
   - Phiếu phải tồn tại
   - **Phiếu chi tiền (Receivable):** Phải ở trạng thái `Approved`
   - **Phiếu thu tiền (Payable):** Có thể hoàn thành trực tiếp từ `PendingApproval`
   - PaymentMethod không được để trống

2. **Process:**
   - Cập nhật trạng thái phiếu → `Completed`
   - Lưu thông tin thanh toán:
     - PaymentMethod
     - TransactionCode
     - ProofImageUrl
   - Lưu thông tin người hoàn thành (CompletedBy, CompletedByUsername)
   - Lưu thời gian hoàn thành (CompletedTime)
   - Ghi log hành động hoàn thành

3. **Side Effects:**
   - Đơn hàng trong phiếu được đánh dấu đã đối soát
   - Có thể cập nhật số dư ví/tài khoản khách hàng
   - Trigger notification cho người tạo phiếu và khách hàng

### Workflow Differences

#### Phiếu Chi Tiền (Receivable - Công ty trả khách)
```
Draft → PendingApproval → Approved → Completed
                ↓
            Rejected
```
- Bắt buộc phải duyệt trước khi hoàn thành
- Kế toán duyệt → Kế toán/Founder xác nhận đã chuyển tiền

#### Phiếu Thu Tiền (Payable - Khách trả công ty)
```
Draft → PendingApproval → Completed
                ↓
            Rejected
```
- Không cần duyệt, hoàn thành trực tiếp
- Kế toán/Founder xác nhận đã nhận tiền từ khách

### Notes
- Phiếu đã hoàn thành không thể chỉnh sửa hoặc hủy
- Nên upload ảnh chứng từ để có bằng chứng thanh toán
- TransactionCode giúp đối chiếu với sao kê ngân hàng

---

## 4. Export Excel List

### Endpoint
```
POST /api/CustomerReconciliationSlip/ExportExcel
```

### Description
Xuất danh sách phiếu đối soát khách hàng ra file Excel với các tùy chọn lọc và định dạng.

**Implementation Status:** ✅ **COMPLETED** - Service layer fully implemented with `CustomerReconciliationSlipExcelService`

### Authorization
**Required Roles:** `CustomerReconciliationSlip.ExportExcel` OR `Founder`

### Request Body
```json
{
  "FileName": "DanhSachPhieuDoiSoat_Thang12",
  "CustomerReconciliationSlipIds": [1, 2, 3, 4, 5],
  "FromDate": "2024-12-01T00:00:00Z",
  "ToDate": "2024-12-31T23:59:59Z",
  "CustomerId": 123,
  "Status": 4,
  "Type": 1,
  "IncludeOrderDetails": true,
  "IncludeApprovalInfo": true,
  "IncludeNotes": true,
  "FolderPath": "/exports/reconciliation"
}
```

### Request Model: `CustomerReconciliationSlipExcelExportModel`
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| FileName | string | No | Tên file Excel (không bao gồm .xlsx) |
| CustomerReconciliationSlipIds | List<int> | No | Danh sách ID phiếu cần xuất (nếu null thì xuất theo filter) |
| FromDate | DateTime? | No | Ngày bắt đầu để lọc |
| ToDate | DateTime? | No | Ngày kết thúc để lọc |
| CustomerId | int? | No | Lọc theo khách hàng |
| Status | int? | No | Lọc theo trạng thái (1=Draft, 2=PendingApproval, 3=Approved, 4=Completed, 8=Rejected) |
| Type | int? | No | Lọc theo loại (1=Receivable, 2=Payable) |
| IncludeOrderDetails | bool | No | Bao gồm chi tiết đơn hàng (default: true) |
| IncludeApprovalInfo | bool | No | Bao gồm thông tin duyệt/hoàn thành (default: true) |
| IncludeNotes | bool | No | Bao gồm ghi chú (default: true) |
| FolderPath | string | No | Đường dẫn thư mục lưu file |

### Request Example
```http
POST /api/CustomerReconciliationSlip/ExportExcel
Content-Type: application/json
Authorization: Bearer {token}

{
  "FileName": "PhieuDoiSoat_KhachHang_ABC_Thang12",
  "CustomerId": 123,
  "FromDate": "2024-12-01T00:00:00Z",
  "ToDate": "2024-12-31T23:59:59Z",
  "Status": 4,
  "IncludeOrderDetails": true,
  "IncludeApprovalInfo": true,
  "IncludeNotes": true
}
```

### Response

#### Success Response (200 OK)
```json
{
  "Result": 1,
  "Message": "Xuất file Excel thành công",
  "FilePath": "/wwwroot/exports/customer-reconciliation-slips/PhieuDoiSoat_KhachHang_ABC_Thang12_20241209_105030.xlsx",
  "FileName": "PhieuDoiSoat_KhachHang_ABC_Thang12_20241209_105030.xlsx",
  "FileSize": 245760,
  "TotalRecords": 15,
  "DownloadUrl": "/api/FinanceExcelExport/Download/PhieuDoiSoat_KhachHang_ABC_Thang12_20241209_105030.xlsx",
  "ProcessStartTime": "2024-12-09T10:50:30Z",
  "ProcessEndTime": "2024-12-09T10:50:33Z",
  "ProcessingTimeMs": 3000,
  "ProcessInfo": {
    "DatabaseQueryTimeMs": 800,
    "DataConversionTimeMs": 500,
    "ExcelGenerationTimeMs": 1500,
    "FileSaveTimeMs": 200,
    "TotalProcessingTimeMs": 3000
  }
}
```

#### Error Responses

**400 Bad Request** - Validation errors
```json
{
  "Result": 2,
  "Message": "Ngày bắt đầu không được lớn hơn ngày kết thúc"
}
```

**401 Unauthorized**
```json
{
  "Message": "Không xác định được người dùng"
}
```

**403 Forbidden**
```json
{
  "Message": "Forbidden"
}
```

**500 Internal Server Error**
```json
{
  "Result": 3,
  "Message": "Lỗi hệ thống: {error details}"
}
```

### Excel File Structure

#### Sheet: "Danh sách phiếu đối soát"
| Column | Description |
|--------|-------------|
| STT | Số thứ tự |
| Mã phiếu | Mã phiếu đối soát (CR-YYMMDD-XXXX) |
| Khách hàng | Tên đầy đủ của khách hàng |
| Loại phiếu | Chi tiền / Thu tiền |
| Trạng thái | Nháp / Chờ duyệt / Đã duyệt / Hoàn thành / Từ chối |
| Tổng COD | Tổng tiền thu hộ COD |
| Tổng phí | Tổng phí vận chuyển |
| Số tiền cuối | Số tiền cần thanh toán/thu |
| Số đơn hàng | Tổng số đơn hàng trong phiếu |
| Ngày tạo | Thời gian tạo phiếu (dd/MM/yyyy HH:mm) |
| Người tạo | Tên người tạo phiếu |
| Ngày hoàn thành | Thời gian hoàn thành (nếu có) |
| Ghi chú | Ghi chú nội bộ |

**Format:**
- Header: Light blue background (#ADD8E6), bold text, centered
- Auto-fit columns for optimal width
- Border cho tất cả cells
- Number format cho tiền: `#,##0 ₫`
- Date format: `dd/MM/yyyy HH:mm`

### Implementation Details

**Service:** `CustomerReconciliationSlipExcelService`
- Query data từ database với Include để eager load related entities
- Apply filters (IDs, date range, customer, status, type)
- Generate Excel với EPPlus library
- Save file qua `IExcelFileService`
- Return download URL và file metadata

**File Storage:**
- Location: `wwwroot/exports/customer-reconciliation-slips/`
- Naming: `{FileName}_{YYYYMMDD}_{HHmmss}.xlsx`
- Auto-cleanup: Files older than 24 hours are automatically deleted

### Notes
- ✅ File Excel được tạo với định dạng .xlsx
- ✅ Hỗ trợ xuất tối đa 10,000 bản ghi trong một lần
- ✅ File được lưu tạm thời và tự động xóa sau 24 giờ
- ✅ Download file qua DownloadUrl trong response
- ✅ Processing time được track và trả về trong response

---

## 5. Export Excel Detail

### Endpoint
```
POST /api/CustomerReconciliationSlip/ExportExcelDetail/{slipId}
```

### Description
Xuất chi tiết một phiếu đối soát cụ thể ra file Excel với đầy đủ thông tin.

**Implementation Status:** ✅ **COMPLETED** - Service layer fully implemented with `CustomerReconciliationSlipExcelService`

### Authorization
**Required Roles:** `CustomerReconciliationSlip.ExportExcel` OR `Founder`

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| slipId | int | Yes | ID của phiếu đối soát cần xuất |

### Request Body
```json
{
  "FileName": "ChiTietPhieu_CR-241209-A1B2",
  "IncludeOrderDetails": true,
  "IncludeApprovalInfo": true,
  "IncludeNotes": true
}
```

### Request Model: `CustomerReconciliationSlipExcelExportModel`
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| FileName | string | No | Tên file Excel (không bao gồm .xlsx) |
| IncludeOrderDetails | bool | No | Bao gồm chi tiết đơn hàng (default: true) |
| IncludeApprovalInfo | bool | No | Bao gồm thông tin duyệt/hoàn thành (default: true) |
| IncludeNotes | bool | No | Bao gồm lịch sử thao tác (default: true) |

### Request Example
```http
POST /api/CustomerReconciliationSlip/ExportExcelDetail/123
Content-Type: application/json
Authorization: Bearer {token}

{
  "FileName": "ChiTietPhieu_CR-241209-A1B2",
  "IncludeOrderDetails": true,
  "IncludeApprovalInfo": true,
  "IncludeNotes": true
}
```

### Response

#### Success Response (200 OK)
```json
{
  "Result": 1,
  "Message": "Xuất file Excel thành công",
  "FilePath": "/wwwroot/exports/customer-reconciliation-slips/ChiTietPhieu_CR-241209-A1B2_20241209_105530.xlsx",
  "FileName": "ChiTietPhieu_CR-241209-A1B2_20241209_105530.xlsx",
  "FileSize": 102400,
  "TotalRecords": 1,
  "DownloadUrl": "/api/FinanceExcelExport/Download/ChiTietPhieu_CR-241209-A1B2_20241209_105530.xlsx",
  "ProcessStartTime": "2024-12-09T10:55:30Z",
  "ProcessEndTime": "2024-12-09T10:55:32Z",
  "ProcessingTimeMs": 2000,
  "ProcessInfo": {
    "DatabaseQueryTimeMs": 500,
    "DataConversionTimeMs": 300,
    "ExcelGenerationTimeMs": 1000,
    "FileSaveTimeMs": 200,
    "TotalProcessingTimeMs": 2000
  }
}
```

#### Error Responses

**400 Bad Request** - Invalid slip ID
```json
{
  "Message": "ID phiếu đối soát không hợp lệ"
}
```

**401 Unauthorized**
```json
{
  "Message": "Không xác định được người dùng"
}
```

**403 Forbidden** - No permission to view this slip
```json
{
  "Message": "Bạn không có quyền xem phiếu này"
}
```

**404 Not Found**
```json
{
  "Result": 2,
  "Message": "Không tìm thấy phiếu đối soát"
}
```

**500 Internal Server Error**
```json
{
  "Result": 3,
  "Message": "Lỗi hệ thống: {error details}"
}
```

### Excel File Structure

#### Sheet: "Phiếu đối soát chi tiết"

**Section 1: Company Header**
- CÔNG TY TNHH LADA EXPRESS (bold, 14pt)
- Website: https://ladaexpress.vn (10pt)
- Hotline: 1900.633.659 (10pt)
- Title: PHIẾU ĐỐI SOÁT KHÁCH HÀNG (bold, 16pt, centered)

**Section 2: General Info**
- Mã phiếu | Loại phiếu
- Khách hàng | Trạng thái
- Tổng tiền COD (formatted as currency)
- Tổng phí vận chuyển (formatted as currency)
- Số tiền cuối cùng (formatted as currency, bold)

**Section 3: Order Details Table** (if IncludeOrderDetails = true)
Header: "DANH SÁCH ĐƠN HÀNG" (bold, 14pt, centered)

| Column | Description |
|--------|-------------|
| Mã đơn hàng | Mã đơn hàng |
| Tiền COD | Tiền thu hộ COD (formatted) |
| Phí vận chuyển | Phí vận chuyển (formatted) |
| Tiền ròng | COD - Phí (formatted) |
| Trạng thái | Trạng thái đơn hàng |

**Format:**
- Company header row: 60px height
- All cells: Wrap text enabled, borders
- Header table: Light blue background (#ADD8E6), bold, centered
- Number format: `#,##0 ₫`
- Column widths optimized for readability

### Implementation Details

**Service:** `CustomerReconciliationSlipExcelService.ExportCustomerReconciliationSlipDetailAsync`
- Query single slip với full Include (Customer, Details, Orders, Logs)
- Generate professional Excel với company branding
- Multiple sections với clear separation
- Rich formatting với colors, fonts, borders
- Save file qua `IExcelFileService`

**File Storage:**
- Location: `wwwroot/exports/customer-reconciliation-slips/`
- Naming: `{FileName}_{YYYYMMDD}_{HHmmss}.xlsx`
- Auto-cleanup: Files older than 24 hours

### Notes
- ✅ File Excel được format đẹp với header màu sắc
- ✅ Các section được phân cách rõ ràng
- ✅ Số liệu được format theo định dạng tiền tệ VND
- ✅ Ngày tháng được format theo định dạng dd/MM/yyyy HH:mm
- ✅ Professional layout với company branding
- ✅ Optimized column widths và row heights

---

## Data Models

### CustomerReconciliationSlipType (Enum)
```csharp
public enum CustomerReconciliationSlipType
{
    Receivable = 1,  // Phiếu chi tiền (công ty trả khách)
    Payable = 2      // Phiếu thu tiền (khách trả công ty)
}
```

### CustomerReconciliationSlipStatus (Enum)
```csharp
public enum CustomerReconciliationSlipStatus
{
    Draft = 1,              // Nháp
    PendingApproval = 2,    // Chờ duyệt
    Approved = 3,           // Đã duyệt
    Completed = 4,          // Hoàn thành
    Rejected = 8            // Từ chối
}
```

### RejectCustomerReconciliationSlipModel
```csharp
public class RejectCustomerReconciliationSlipModel
{
    [Required]
    public int Id { get; set; }

    [Required(ErrorMessage = "Vui lòng nhập lý do từ chối")]
    public string Reason { get; set; }
}
```

### CompleteCustomerReconciliationSlipModel
```csharp
public class CompleteCustomerReconciliationSlipModel
{
    [Required]
    public int Id { get; set; }

    [Required]
    public string PaymentMethod { get; set; }

    public string TransactionCode { get; set; }
    public string ProofImageUrl { get; set; }
    public string Note { get; set; }
}
```

---

## Business Rules

### Workflow Rules

#### Phiếu Chi Tiền (Receivable - Type = 1)
```
Create → PendingApproval → Approve → Complete
                    ↓
                 Reject
```

**Rules:**
1. Phải được duyệt trước khi hoàn thành
2. Chỉ Founder/Accountant/User có quyền Approve mới được duyệt
3. Sau khi duyệt mới có thể hoàn thành
4. Có thể từ chối ở bất kỳ trạng thái nào (trừ Completed và Rejected)

#### Phiếu Thu Tiền (Payable - Type = 2)
```
Create → PendingApproval → Complete
                    ↓
                 Reject
```

**Rules:**
1. Không cần duyệt, có thể hoàn thành trực tiếp
2. Bắt buộc phải upload ảnh chứng từ khi tạo phiếu
3. Kế toán xác nhận đã nhận tiền từ khách
4. Có thể từ chối ở bất kỳ trạng thái nào (trừ Completed và Rejected)

### Permission Matrix

| Action | Creator | Founder | Accountant | Approve Permission | Reject Permission | Complete Permission |
|--------|---------|---------|------------|-------------------|-------------------|---------------------|
| View | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Create | ✓ | ✓ | - | - | - | - |
| Approve (Receivable only) | - | ✓ | ✓ | ✓ | - | - |
| Reject | ✓ | ✓ | ✓ | - | ✓ | - |
| Complete | - | ✓ | ✓ | - | - | ✓ |
| Export Excel | - | ✓ | - | - | - | - |

### Validation Rules

1. **Approve:**
   - Phiếu phải ở trạng thái `PendingApproval`
   - Chỉ áp dụng cho phiếu loại `Receivable`

2. **Reject:**
   - Phiếu không được ở trạng thái `Completed` hoặc `Rejected`
   - Lý do từ chối không được để trống
   - Lý do từ chối tối thiểu 10 ký tự

3. **Complete:**
   - **Receivable:** Phiếu phải ở trạng thái `Approved`
   - **Payable:** Phiếu phải ở trạng thái `PendingApproval`
   - PaymentMethod không được để trống
   - TransactionCode nên được cung cấp để đối chiếu

4. **Export Excel:**
   - FromDate không được lớn hơn ToDate
   - Danh sách IDs phải chứa giá trị hợp lệ (> 0)
   - Tên file không được chứa ký tự đặc biệt

---

## Error Codes

### HTTP Status Codes

| Code | Description | When to use |
|------|-------------|-------------|
| 200 | OK | Request successful |
| 400 | Bad Request | Validation errors, invalid data |
| 401 | Unauthorized | User not authenticated |
| 403 | Forbidden | User doesn't have required permissions |
| 404 | Not Found | Resource not found |
| 500 | Internal Server Error | System error |

### Result Codes (in response body)

| Code | Name | Description |
|------|------|-------------|
| 1 | Success | Operation completed successfully |
| 2 | Failed | Operation failed due to business logic |
| 3 | SystemError | System error occurred |

---

## Usage Examples

### Example 1: Complete Workflow for Receivable Slip

#### Step 1: Create Slip
```http
POST /api/CustomerReconciliationSlip/Create
```

#### Step 2: Approve Slip
```http
PUT /api/CustomerReconciliationSlip/Approve/123
```

#### Step 3: Complete Slip
```http
POST /api/CustomerReconciliationSlip/Complete
Content-Type: application/json

{
  "Id": 123,
  "PaymentMethod": "Chuyển khoản Vietcombank",
  "TransactionCode": "FT24120912345678"
}
```

#### Step 4: Export to Excel
```http
POST /api/CustomerReconciliationSlip/ExportExcelDetail/123
Content-Type: application/json

{
  "FileName": "PhieuDoiSoat_123",
  "IncludeOrderDetails": true,
  "IncludeApprovalInfo": true,
  "IncludeNotes": true
}
```

### Example 2: Complete Workflow for Payable Slip

#### Step 1: Create Slip (with proof image)
```http
POST /api/CustomerReconciliationSlip/Create
Content-Type: multipart/form-data
```

#### Step 2: Complete Slip (skip approval)
```http
POST /api/CustomerReconciliationSlip/Complete
Content-Type: application/json

{
  "Id": 124,
  "PaymentMethod": "Chuyển khoản từ khách hàng",
  "TransactionCode": "CK24120912345678",
  "Note": "Đã nhận tiền từ khách hàng"
}
```

### Example 3: Reject Slip
```http
POST /api/CustomerReconciliationSlip/Reject
Content-Type: application/json

{
  "Id": 125,
  "Reason": "Số tiền COD không khớp với thực tế, cần kiểm tra lại đơn hàng #ORD-123456"
}
```

### Example 4: Export Multiple Slips
```http
POST /api/CustomerReconciliationSlip/ExportExcel
Content-Type: application/json

{
  "FileName": "BaoCaoDoiSoat_Thang12_2024",
  "FromDate": "2024-12-01T00:00:00Z",
  "ToDate": "2024-12-31T23:59:59Z",
  "Status": 4,
  "IncludeOrderDetails": true,
  "IncludeApprovalInfo": true
}
```

---

## Security Considerations

1. **Authentication:** All endpoints require valid JWT token
2. **Authorization:** Role-based access control (RBAC)
3. **Data Access:** Users can only access slips they have permission to view
4. **Audit Trail:** All actions are logged in CustomerReconciliationLog table
5. **File Security:** Exported files are stored securely and auto-deleted after 24 hours
6. **Input Validation:** All inputs are validated to prevent injection attacks

---

## Performance Considerations

1. **Excel Export:**
   - Large exports (>1000 records) should be processed asynchronously
   - Consider implementing background job processing
   - Add progress tracking for long-running exports

2. **Database Queries:**
   - Use indexes on frequently queried fields (Status, CustomerId, CreatedTime)
   - Implement pagination for large result sets

3. **Caching:**
   - Cache frequently accessed data
   - Invalidate cache when data changes

---

## Related Documentation

- [Customer Reconciliation Slip - Overview](./API_CustomerReconciliationSlip.md)
- [Customer Reconciliation Slip - Permission Updates](./CustomerReconciliationSlip_Permission_Updates.md)
- [Customer Reconciliation Slip - Excel Export](./API_CustomerReconciliationSlipExcelExport.md)
- [Customer Reconciliation Slip - Create & Search](./API_CustomerReconciliationSlip_CreateSearch.md)
