> ## Documentation Index
> Fetch the complete documentation index at: https://docs.econtractid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Hợp đồng

> Các endpoint CRUD để quản lý vòng đời hợp đồng điện tử

## Danh sách hợp đồng

```http theme={null}
GET /api/contracts
```

**Query params:**

| Param      | Kiểu     | Mô tả                                                          |
| ---------- | -------- | -------------------------------------------------------------- |
| `page`     | `number` | Số trang (mặc định: 1)                                         |
| `limit`    | `number` | Số bản ghi / trang (mặc định: 20)                              |
| `status`   | `string` | `draft` \| `signing` \| `completed` \| `rejected` \| `expired` |
| `search`   | `string` | Tìm theo tên hợp đồng                                          |
| `fromDate` | `string` | ISO 8601, lọc từ ngày                                          |
| `toDate`   | `string` | ISO 8601, lọc đến ngày                                         |

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "data": [
    {
      "id": "ctr_abc123",
      "title": "Hợp đồng dịch vụ CNTT 2025",
      "status": "signing",
      "createdAt": "2025-01-15T08:00:00Z",
      "expiredAt": "2025-02-15T23:59:59Z",
      "signers": [
        {
          "email": "nguyen@example.com",
          "name": "Nguyễn Văn A",
          "order": 1,
          "status": "signed",
          "signedAt": "2025-01-16T10:30:00Z"
        }
      ]
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 45 }
}
```

***

## Tạo hợp đồng mới

```http theme={null}
POST /api/contracts
Content-Type: multipart/form-data
```

**Body (multipart/form-data):**

| Trường           | Kiểu          | Bắt buộc | Mô tả                           |
| ---------------- | ------------- | -------- | ------------------------------- |
| `file`           | `File`        | ✅        | File `.pdf` hoặc `.docx`        |
| `title`          | `string`      | ✅        | Tên hợp đồng                    |
| `contractTypeId` | `number`      | ✅        | ID loại hợp đồng                |
| `expiredAt`      | `string`      | ✅        | Deadline ký (ISO 8601)          |
| `signers`        | `JSON string` | ✅        | Danh sách bên ký (xem bên dưới) |
| `description`    | `string`      |          | Ghi chú                         |

**Cấu trúc `signers`:**

```json theme={null}
[
  {
    "name": "Nguyễn Văn A",
    "email": "a@example.com",
    "phone": "0901234567",
    "role": "party_a",
    "order": 1
  },
  {
    "name": "Trần Thị B",
    "email": "b@example.com",
    "phone": "0907654321",
    "role": "party_b",
    "order": 2
  }
]
```

**Response:**

```json theme={null}
{
  "statusCode": 201,
  "message": "Tạo hợp đồng thành công",
  "data": {
    "id": "ctr_abc123",
    "title": "Hợp đồng dịch vụ CNTT 2025",
    "status": "draft",
    "fileUrl": "https://storage.econtractid.vn/contracts/ctr_abc123.pdf"
  }
}
```

***

## Chi tiết hợp đồng

```http theme={null}
GET /api/contracts/:id
```

Trả về đầy đủ thông tin hợp đồng bao gồm danh sách bên ký, lịch sử thao tác (audit trail).

***

## Gửi hợp đồng đi ký

```http theme={null}
POST /api/contracts/:id/send
```

Chuyển hợp đồng từ trạng thái `draft` sang `signing` và gửi email thông báo tới bên ký **thứ 1**.

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "Đã gửi hợp đồng đi ký thành công",
  "data": {
    "id": "ctr_abc123",
    "status": "signing",
    "sentAt": "2025-01-15T09:00:00Z"
  }
}
```

***

## Hủy hợp đồng

```http theme={null}
DELETE /api/contracts/:id
Content-Type: application/json

{
  "reason": "Lý do hủy hợp đồng"
}
```

<Warning>
  Chỉ hủy được hợp đồng ở trạng thái `draft` hoặc `signing`. Hợp đồng đã `completed` **không thể hủy**.
</Warning>

***

## Tải xuống hợp đồng

```http theme={null}
GET /api/contracts/:id/download?type=signed
```

| Param `type` | Mô tả                                                   |
| ------------ | ------------------------------------------------------- |
| `original`   | File gốc chưa ký                                        |
| `signed`     | PDF đã nhúng chữ ký số (chỉ khi đã có ít nhất 1 chữ ký) |
| `audit`      | Biên bản kiểm tra (audit trail PDF)                     |

Trả về file PDF dạng binary stream.