13.1. Giới thiệu Partner API

SmaxAI Partner API cho phép các developer và đối tác tích hợp hệ thống bên ngoài (CRM, ERP, website, n8n, Make, Zapier…) với nền tảng SmaxAI — bao gồm quản lý khách hàng, gửi tin nhắn đa kênh, quản lý sản phẩm, đơn hàng và nhiều chức năng khác.

Tài liệu API tương tác (Swagger UI) có sẵn tại:

👉 https://smax.ai/api/partner/docs

---

I. Kiến trúc tổng quan

1. Base URL

Tất cả request đều gửi đến:

https://api.smax.ai

Các endpoint được tổ chức theo pattern:

/partner/bizs/{bizAlias}/...

trong đó {bizAlias} là mã định danh duy nhất của doanh nghiệp (Business) trên SmaxAI. Mỗi tài khoản có thể quản lý nhiều Business, mỗi Business có một bizAlias riêng.

💡 Tìm bizAlias ở đâu? Đăng nhập SmaxAI → chọn Business → xem trên URL hoặc trong phần Cài đặt doanh nghiệp.

2. Tiêu chuẩn API

3. Sơ đồ tích hợp

┌─────────────────┐         HTTPS/JSON          ┌─────────────────┐
│  Hệ thống       │  ◄──────────────────────►   │  SmaxAI         │
│  bên ngoài      │                              │  Partner API    │
│                  │                              │                 │
│  • Website       │    Authorization: Bearer     │  api.smax.ai    │
│  • CRM           │    ──────────────────────►   │                 │
│  • n8n / Make    │                              │  /partner/bizs/ │
│  • WooCommerce   │    ◄──────────────────────   │  {bizAlias}/... │
│  • App mobile    │    JSON Response             │                 │
└─────────────────┘                              └─────────────────┘

---

II. Xác thực (Authentication)

1. Phương thức: Bearer Token (JWT)

Partner API sử dụng Bearer Token theo chuẩn JWT (JSON Web Token). Mọi request đều phải kèm header:

http
Authorization: Bearer <YOUR_API_TOKEN>

2. Lấy API Token

Để lấy token, bạn thực hiện các bước sau trong giao diện SmaxAI:

1. Đăng nhập tại https://app.smax.ai
2. Chọn Business mà bạn muốn tích hợp
3. Vào Cài đặt (Settings) → API hoặc Tích hợp (Integration)
4. Tạo API Token mới hoặc sao chép token hiện có

⚠️ Bảo mật token:

• Không chia sẻ token qua kênh không an toàn (chat, email thường)
• Không commit token vào source code / GitHub
• Sử dụng biến môi trường (environment variable) để lưu token
• Mỗi token gắn với một Business cụ thể — nếu bạn quản lý nhiều Business, bạn cần nhiều token tương ứng

3. Ví dụ request có xác thực

cURL:

bash
curl -X GET "https://api.smax.ai/partner/bizs/my-shop/customers?limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

JavaScript (fetch):

javascript
const response = await fetch(
  "https://api.smax.ai/partner/bizs/my-shop/customers?limit=10",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
      "Content-Type": "application/json"
    }
  }
);
const data = await response.json();
console.log(data);

Python (requests):

python
import requests

url = "https://api.smax.ai/partner/bizs/my-shop/customers"
headers = {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
    "Content-Type": "application/json"
}
params = {"limit": 10}

response = requests.get(url, headers=headers, params=params)
print(response.json())

n8n (HTTP Request node):

---

III. Các khái niệm cốt lõi

Trước khi làm việc với API, bạn cần nắm rõ các khái niệm sau:

1. bizAlias — Mã doanh nghiệp

Mỗi doanh nghiệp trên SmaxAI có một alias duy nhất (dạng chuỗi, ví dụ: my-cosmetics-shop). Đây là tham số bắt buộc trong mọi endpoint.

2. page_pid — Mã trang kênh

Mỗi kênh đã kết nối (Facebook Page, Zalo OA, Website…) có một page_pid riêng. Bạn lấy danh sách trang qua endpoint:

GET /partner/bizs/{bizAlias}/pages

3. tid — Thread ID (Mã hội thoại)

Mỗi cuộc hội thoại giữa khách hàng và trang có một tid duy nhất. Sử dụng để gửi/đọc tin nhắn trong cuộc hội thoại cụ thể.

4. customer_pid — Mã khách hàng

Mã định danh duy nhất của một khách hàng trên SmaxAI, dùng để tra cứu thông tin hoặc gửi tin nhắn đến khách.

5. Roles (Quyền truy cập)

Một số endpoint yêu cầu quyền (role) đặc biệt:

Nếu token của bạn không có quyền tương ứng, API sẽ trả về lỗi 403 Forbidden.

---

IV. Tổng quan các nhóm Endpoint

Partner API bao gồm 9 nhóm chức năng chính với tổng cộng 28 endpoints:

1. 💬 Message (Tin nhắn) — 4 endpoints

Gửi tin nhắn qua block/script, gửi/đọc/xóa tin nhắn trong thread.

2. 👤 Customer (Khách hàng) — 5 endpoints

Tạo mới, tra cứu, lấy danh sách và đếm khách hàng.

3. 🔗 Integration (Tích hợp) — 3 endpoints

Quản lý kết nối với hệ thống bên thứ 3.

4. 🏢 Biz (Doanh nghiệp) — 1 endpoint

5. 📄 Partner Page (Trang & Kênh) — 7 endpoints

Quản lý trang, kết bạn Zalo OA, gửi tin Zalo Web và ZNS.

6. 🏷️ Tag (Nhãn) — 1 endpoint

7. 💬 Threads (Hội thoại) — 2 endpoints

8. 📦 Partner Block (Kịch bản) — 2 endpoints

9. 🛒 Products & Orders (Sản phẩm & Đơn hàng) — 10 endpoints

Sản phẩm (5 endpoints):

Đơn hàng (4 endpoints):

Mã khuyến mãi (2 endpoints):

📌 Lưu ý: Nhóm Products, Orders và Promotion Code sử dụng prefix /api/partner/ hoặc /api/ thay vì /partner/ như các nhóm khác.

---

V. Cấu trúc Response

1. Response thành công

API trả về JSON với HTTP status 200 (GET) hoặc 201 (POST):

json
{
  "data": [ ... ],
  "total": 50,
  "page": 1,
  "limit": 10
}

hoặc với endpoint trả về đối tượng đơn lẻ:

json
{
  "id": "abc123",
  "name": "Nguyễn Văn A",
  "phone": "0901234567",
  ...
}

2. Response lỗi

---

VI. Hướng dẫn sử dụng Swagger UI

Swagger UI tại https://smax.ai/api/partner/docs cho phép bạn test API trực tiếp trên trình duyệt mà không cần viết code.

Bước 1: Xác thực trên Swagger

1. Mở trang Swagger UI
2. Click nút Authorize (🔓) ở góc trên bên phải
3. Nhập token theo định dạng: Bearer <YOUR_TOKEN> (hoặc chỉ nhập token tùy giao diện)
4. Click Authorize → Close

Bước 2: Test một endpoint

1. Chọn nhóm endpoint (ví dụ: Customer)
2. Click vào endpoint cần test (ví dụ: GET /partner/bizs/{bizAlias}/customers)
3. Click Try it out
4. Điền các tham số bắt buộc (ví dụ: bizAlias)
5. Click Execute
6. Xem kết quả tại phần Response body

Bước 3: Sao chép cURL

Sau khi Execute, Swagger UI sẽ hiển thị lệnh cURL tương ứng. Bạn có thể copy lệnh này để chạy trên terminal hoặc chuyển đổi sang ngôn ngữ lập trình khác.

---

VII. Lưu ý quan trọng

Rate Limit (Giới hạn tần suất)

Để đảm bảo hiệu suất hệ thống, API áp dụng giới hạn số lượng request trong một khoảng thời gian. Khi vượt quá giới hạn, bạn sẽ nhận được response 429 Too Many Requests. Khuyến nghị:

• Giãn cách các request ít nhất 100ms
• Sử dụng cơ chế retry với exponential backoff khi gặp lỗi 429
• Cache kết quả từ các endpoint ít thay đổi (ví dụ: danh sách tags, blocks)

Pagination (Phân trang)

Các endpoint trả về danh sách hỗ trợ phân trang qua query parameters:

Environment

• DELETE /messages được đánh dấu "For env dev" — chỉ sử dụng trong môi trường phát triển
• Luôn test trên môi trường sandbox/dev trước khi triển khai production

---

\