# Tài Liệu API - MKT Zalo Service

Tài liệu API đầy đủ cho tất cả endpoints.

## Base URL

```
http://localhost/api/v1/zalo
```

## Xác Thực

- **Webhooks**: Xác thực chữ ký (HMAC SHA256)
- **Customer APIs**: JWT Bearer token
- **Admin APIs**: JWT Bearer token + role `admin` hoặc `marketing_manager`

---

## Webhook APIs

### POST /webhooks

Nhận events từ Zalo Official Account.

**Xác thực**: Xác thực chữ ký

**Headers**:
```
X-Zalo-Signature: <hmac_sha256_signature>
Content-Type: application/json
```

**Request Body**:
```json
{
  "app_id": "1234567890",
  "event_name": "user_send_text",
  "timestamp": 1705586400000,
  "sender": {
    "id": "1234567890123456789"
  },
  "recipient": {
    "id": "9876543210"
  },
  "message": {
    "text": "Xin chào, tôi cần hỗ trợ",
    "msg_id": "msg_123456"
  }
}
```

**Response**: `200 OK`

---

## Conversation APIs

### GET /conversations

Danh sách hội thoại với phân trang.

**Xác thực**: Bắt buộc (JWT)

**Query Parameters**:
- `skip` (int, mặc định: 0)
- `take` (int, mặc định: 20, tối đa: 100)
- `status` (enum: active, closed, all)
- `zaloUserId` (string, tùy chọn)
- `fromDate` (datetime, tùy chọn)
- `toDate` (datetime, tùy chọn)

**Response**:
```json
{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "uuid",
        "zaloUserId": "...",
        "customerName": "Nguyễn Văn A",
        "status": "active",
        "lastMessage": "Cảm ơn bạn",
        "lastMessageAt": "2026-01-18T10:30:00Z",
        "messageCount": 15
      }
    ],
    "totalCount": 120
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 120,
    "totalPages": 6
  }
}
```

### GET /conversations/{id}

Lấy chi tiết hội thoại với lịch sử tin nhắn.

**Xác thực**: Bắt buộc (JWT)

**Response**:
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "zaloUserId": "...",
    "customer": {
      "id": "uuid",
      "displayName": "Nguyễn Văn A",
      "tags": ["vip", "interested-in-retail"]
    },
    "messages": [
      {
        "id": "msg-001",
        "type": "text",
        "content": "Xin chào",
        "direction": "incoming",
        "isFromBot": false,
        "sentAt": "2026-01-18T10:00:00Z"
      }
    ]
  }
}
```

### POST /conversations/{id}/messages

Gửi tin nhắn trong hội thoại.

**Xác thực**: Bắt buộc (JWT)

**Request Body**:
```json
{
  "type": "text",
  "content": "Cảm ơn bạn đã liên hệ."
}
```

**Response**: `201 Created`

### POST /conversations/{id}/close

Đóng hội thoại đang hoạt động.

**Xác thực**: Bắt buộc (JWT)

**Response**: `200 OK`

---

## Customer APIs

### GET /customers

Danh sách khách hàng Zalo.

**Xác thực**: Bắt buộc (JWT)

**Query Parameters**:
- `skip`, `take` (phân trang)
- `search` (string): Tìm theo tên, số điện thoại, email
- `segment` (enum): new, regular, active, vip
- `tags` (string[]): Tags cách nhau bởi dấu phẩy

**Response**:
```json
{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "uuid",
        "zaloUserId": "...",
        "displayName": "Nguyễn Văn A",
        "segment": "vip",
        "tags": ["vip", "high-value"],
        "conversationCount": 12
      }
    ]
  }
}
```

### GET /customers/{id}

Lấy chi tiết khách hàng.

**Xác thực**: Bắt buộc (JWT)

### PUT /customers/{id}

Cập nhật hồ sơ khách hàng.

**Xác thực**: Bắt buộc (JWT)

**Request Body**:
```json
{
  "phoneNumber": "+84901234567",
  "email": "customer@example.com",
  "tags": ["vip", "interested-in-retail"]
}
```

---

## Chatbot Rule APIs

### GET /chatbot-rules

Danh sách quy tắc tự động hóa.

**Xác thực**: Bắt buộc (JWT)

**Response**:
```json
{
  "success": true,
  "data": {
    "rules": [
      {
        "id": "uuid",
        "name": "Quy tắc chào hỏi",
        "type": "keyword",
        "priority": 100,
        "isActive": true,
        "conditions": [
          {
            "field": "message_text",
            "operator": "contains",
            "value": "xin chào"
          }
        ],
        "action": {
          "type": "send_text",
          "responseText": "Xin chào! Tôi có thể giúp gì cho bạn?"
        }
      }
    ]
  }
}
```

### POST /chatbot-rules

Tạo quy tắc tự động hóa.

**Xác thực**: Bắt buộc (JWT)

### PUT /chatbot-rules/{id}

Cập nhật quy tắc.

**Xác thực**: Bắt buộc (JWT)

### DELETE /chatbot-rules/{id}

Xóa quy tắc.

**Xác thực**: Bắt buộc (JWT)

**Response**: `204 No Content`

---

## Template APIs

### GET /templates

Danh sách ZNS templates.

**Xác thực**: Bắt buộc (JWT)

### POST /templates/{id}/send

Gửi tin nhắn template.

**Xác thực**: Bắt buộc (JWT)

**Request Body**:
```json
{
  "zaloUserId": "...",
  "parameters": {
    "order_id": "ORD-12345",
    "total_amount": "500000"
  }
}
```

---

## Admin APIs

### GET /admin/analytics

Lấy analytics dashboard.

**Xác thực**: Bắt buộc (JWT + Admin role)

**Query Parameters**:
- `fromDate` (date, bắt buộc)
- `toDate` (date, bắt buộc)
- `groupBy` (enum): day, week, month

**Response**:
```json
{
  "success": true,
  "data": {
    "metrics": {
      "totalConversations": 1523,
      "activeConversations": 234,
      "automationRate": 0.72
    },
    "timeline": [
      {
        "date": "2026-01-01",
        "conversations": 45,
        "messages": 567
      }
    ]
  }
}
```

### GET /admin/messages

Tìm kiếm tất cả tin nhắn (chỉ admin).

**Xác thực**: Bắt buộc (JWT + Admin role)

### POST /admin/broadcast

Broadcast tin nhắn đến các segments.

**Xác thực**: Bắt buộc (JWT + Admin role)

**Request Body**:
```json
{
  "targetSegments": ["vip", "active"],
  "message": {
    "type": "text",
    "content": "Khuyến mãi đặc biệt!"
  },
  "scheduleAt": "2026-01-20T10:00:00Z"
}
```

---

## Error Responses

### Định Dạng Lỗi Chuẩn

```json
{
  "success": false,
  "error": "Thông báo lỗi",
  "details": {
    "code": "ERROR_CODE",
    "field": "fieldName"
  }
}
```

### Mã HTTP Status Codes

| Mã | Ý Nghĩa |
|----|---------|
| 200 | OK |
| 201 | Created |
| 204 | No Content |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 422 | Unprocessable Entity |
| 500 | Internal Server Error |

---

**Tổng Số Endpoints**: 17  
**Phiên Bản Tài Liệu**: 1.0  
**Cập Nhật Lần Cuối**: 2026-01-18
