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.

Authorization: Bearer {jwt_token}

Webhooks API

Verify Facebook Webhook

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

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.

POST /api/v1/webhooks/facebook

Headers:

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

Request Body (Message Event):

{
  "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):

{
  "success": true
}

---

Conversations API

Danh Sách Conversations

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

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):

{
  "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.

GET /api/v1/conversations/{id}

Response (200 OK):

{
  "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.

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.

GET /api/v1/chatbots/flows

Response (200 OK):

{
  "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.

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

Response (200 OK):

{
  "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

{
  "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
• Hướng Dẫn Setup Facebook