pos-system/services/mkt-facebook-service-net/docs/vi/API.md

# Tài Liệu API

**Dịch vụ**: mkt-facebook-service-net  
**Base URL**: `http://localhost/api/v1/mkt-facebook`  
**Phiên bản API**: v1.0

## Xác Thực

Tất cả REST API endpoints (trừ webhooks) yêu cầu JWT Bearer token.

```http
Authorization: Bearer {jwt_token}
```

## Webhooks API

### Verify Facebook Webhook

Facebook dùng endpoint này để verify webhook trong quá trình setup.

```http
GET /api/v1/webhooks/facebook
```

**Query Parameters**:
| Parameter | Type | Mô Tả |
|-----------|------|-------|
| `hub.mode` | string | Phải là "subscribe" |
| `hub.verify_token` | string | Token được cấu hình trong Facebook App |
| `hub.challenge` | string | Chuỗi random từ Facebook |

**Response** (200 OK):
```
{hub.challenge}
```

---

### Nhận Facebook Messenger Events

Nhận messages, postbacks, và các events khác từ Facebook Messenger Platform.

```http
POST /api/v1/webhooks/facebook
```

**Headers**:
```
X-Hub-Signature-256: sha256={signature}
Content-Type: application/json
```

**Request Body** (Message Event):
```json
{
  "object": "page",
  "entry": [{
    "id": "PAGE_ID",
    "time": 1234567890,
    "messaging": [{
      "sender": { "id": "USER_ID" },
      "recipient": { "id": "PAGE_ID" },
      "timestamp": 1234567890,
      "message": {
        "mid": "MESSAGE_ID",
        "text": "Hello chatbot!",
        "quick_reply": {
          "payload": "QUICK_REPLY_PAYLOAD"
        }
      }
    }]
  }]
}
```

**Response** (200 OK):
```json
{
  "success": true
}
```

---

## Conversations API

### Danh Sách Conversations

Lấy danh sách conversations có phân trang.

```http
GET /api/v1/conversations
```

**Query Parameters**:
| Parameter | Type | Required | Default | Mô Tả |
|-----------|------|----------|---------|-------|
| `shopId` | guid | Yes | - | Shop/Business ID |
| `status` | string | No | - | Lọc theo status (Active, Closed) |
| `skip` | int | No | 0 | Số records bỏ qua |
| `take` | int | No | 20 | Số records trả về |

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "customerId": "650e8400-e29b-41d4-a716-446655440001",
        "customerName": "Nguyễn Văn A",
        "pageId": "123456789",
        "status": "Active",
        "channel": "FacebookMessenger",
        "lastMessageText": "Cảm ơn!",
        "lastMessageAt": "2026-01-18T10:30:00Z",
        "createdAt": "2026-01-18T09:00:00Z"
      }
    ],
    "totalCount": 150
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

---

### Lấy Conversation Theo ID

Lấy một conversation với toàn bộ lịch sử tin nhắn.

```http
GET /api/v1/conversations/{id}
```

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "customer": {
      "id": "650e8400-e29b-41d4-a716-446655440001",
      "name": "Nguyễn Văn A",
      "tags": ["VIP", "Khách hàng quay lại"]
    },
    "messages": [
      {
        "id": "msg-001",
        "senderId": "1234567890",
        "content": "Xin chào, tôi cần hỗ trợ",
        "messageType": "Text",
        "direction": "Incoming",
        "sentAt": "2026-01-18T09:00:00Z"
      }
    ]
  }
}
```

---

## Customers API

### Danh Sách Khách Hàng

Lấy danh sách khách hàng có phân trang.

```http
GET /api/v1/customers
```

**Query Parameters**:
| Parameter | Type | Required | Default | Mô Tả |
|-----------|------|----------|---------|-------|
| `shopId` | guid | Yes | - | Shop/Business ID |
| `tags` | string[] | No | - | Lọc theo tags |
| `search` | string | No | - | Tìm kiếm theo tên hoặc email |
| `skip` | int | No | 0 | Pagination offset |
| `take` | int | No | 20 | Page size |

---

## Chatbots API

### Danh Sách Automation Flows

Lấy tất cả automation flows của shop.

```http
GET /api/v1/chatbots/flows
```

**Response** (200 OK):
```json
{
  "success": true,
  "data": [
    {
      "id": "flow-001",
      "name": "Welcome Flow",
      "shopId": "shop-123",
      "triggerType": "GetStarted",
      "isActive": true,
      "nodeCount": 8
    }
  ]
}
```

---

### Lấy AI Chatbot Config

Lấy cấu hình AI chatbot của shop.

```http
GET /api/v1/chatbots/ai-config?shopId={shopId}
```

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "id": "ai-config-001",
    "shopId": "shop-123",
    "provider": "OpenAI",
    "model": "gpt-4-turbo",
    "systemPrompt": "Bạn là trợ lý AI...",
    "temperature": 0.7,
    "maxTokens": 500,
    "isEnabled": true
  }
}
```

---

## Phản Hồi Lỗi

### Format Lỗi Chuẩn

```json
{
  "success": false,
  "error": "Thông báo lỗi",
  "errorCode": "ERROR_CODE",
  "details": {
    "field": "Lỗi cụ thể của field"
  }
}
```

### Mã Lỗi Thường Gặp

| Status Code | Error Code | Mô Tả |
|-------------|------------|-------|
| 400 | `INVALID_REQUEST` | Request parameters không hợp lệ |
| 401 | `UNAUTHORIZED` | Thiếu hoặc token không hợp lệ |
| 403 | `FORBIDDEN` | Không có quyền |
| 404 | `NOT_FOUND` | Không tìm thấy resource |
| 429 | `RATE_LIMIT_EXCEEDED` | Quá nhiều requests |
| 500 | `INTERNAL_ERROR` | Lỗi server |

---

## Giới Hạn Tỷ Lệ

Giới hạn API mỗi API key:
- **100 requests/phút** cho read operations (GET)
- **20 requests/phút** cho write operations (POST, PUT, DELETE)

---

## Tài Nguyên

- [Tài Liệu Kiến Trúc](./ARCHITECTURE.md)
- [Hướng Dẫn Setup Facebook](./FACEBOOK_SETUP.md)