13.2. Case Study 1 — Quản lý khách hàng (CRM Sync)

Mục này hướng dẫn bạn sử dụng Partner API để tạo, tra cứu, lọc khách hàng và gắn thuộc tính tùy chỉnh — nền tảng cho mọi kịch bản đồng bộ CRM, lead nurturing, và remarketing đa kênh.

---

Tổng quan endpoints sử dụng

---

I. Tạo khách hàng mới

Endpoint

POST /partner/bizs/{bizAlias}/customers

Request Body — CreateCustomerByPhoneDto

Mỗi phần tử trong attrs theo schema NameAndValueDto:

Ví dụ: Tạo khách hàng với thuộc tính mở rộng

cURL:

bash
curl -X POST "https://api.smax.ai/partner/bizs/my-shop/customers" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "zalo",
    "phone": "0901234567",
    "page_pid": "page_abc123",
    "name": "Nguyễn Văn A",
    "picture": "https://example.com/avatar.jpg",
    "attrs": [
      { "name": "email", "value": "nguyenvana@gmail.com" },
      { "name": "city", "value": "Hồ Chí Minh" },
      { "name": "source", "value": "facebook_ads" },
      { "name": "campaign", "value": "summer_sale_2026" }
    ]
  }'

JavaScript:

javascript
const BASE_URL = "https://api.smax.ai";
const TOKEN = process.env.SMAX_API_TOKEN;
const BIZ_ALIAS = "my-shop";

async function createCustomer({ phone, name, pagePid, platform, attrs }) {
  const response = await fetch(`${BASE_URL}/partner/bizs/${BIZ_ALIAS}/customers`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      platform: platform || "zalo",
      phone,
      page_pid: pagePid,
      name,
      attrs: attrs || []
    })
  });

  if (!response.ok) {
    throw new Error(`Create customer failed: ${response.status}`);
  }
  return response.json();
}

// Sử dụng
const customer = await createCustomer({
  phone: "0901234567",
  name: "Nguyễn Văn A",
  pagePid: "page_abc123",
  platform: "zalo",
  attrs: [
    { name: "email", value: "nguyenvana@gmail.com" },
    { name: "source", value: "landing_page" }
  ]
});
console.log("Created:", customer);

Python:

python
import requests
import os

BASE_URL = "https://api.smax.ai"
TOKEN = os.environ["SMAX_API_TOKEN"]
BIZ_ALIAS = "my-shop"

def create_customer(phone, name, page_pid, platform="zalo", attrs=None):
    url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/customers"
    headers = {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json"
    }
    payload = {
        "platform": platform,
        "phone": phone,
        "page_pid": page_pid,
        "name": name,
        "attrs": attrs or []
    }
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    return response.json()

# Sử dụng
customer = create_customer(
    phone="0901234567",
    name="Nguyễn Văn A",
    page_pid="page_abc123",
    attrs=[
        {"name": "email", "value": "nguyenvana@gmail.com"},
        {"name": "source", "value": "webinar_registration"}
    ]
)
print("Created:", customer)

💡 Mẹo: Trường phone đóng vai trò như primary key để SmaxAI nhận diện khách hàng. Nếu bạn POST một số điện thoại đã tồn tại, hệ thống sẽ cập nhật thay vì tạo trùng.

---

II. Tra cứu thông tin khách hàng

Endpoint

GET /partner/bizs/{bizAlias}/pages/{page_pid}/customers/{customer_pid}

Path Parameters

Ví dụ

cURL:

bash
curl -X GET "https://api.smax.ai/partner/bizs/my-shop/pages/page_abc123/customers/cust_xyz789" \
  -H "Authorization: Bearer <TOKEN>"

Python:

python
def get_customer(page_pid, customer_pid):
    url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/pages/{page_pid}/customers/{customer_pid}"
    headers = {"Authorization": f"Bearer {TOKEN}"}
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

customer = get_customer("page_abc123", "cust_xyz789")
print(f"Tên: {customer.get('name')}")
print(f"SĐT: {customer.get('phone')}")
print(f"Attrs: {customer.get('attrs')}")

Khi nào dùng endpoint này?

• Khi bạn đã biết customer_pid (ví dụ: từ webhook, từ thread, từ kết quả tìm kiếm)
• Cần lấy thông tin đầy đủ của 1 khách hàng cụ thể (tên, SĐT, avatar, attrs)

---

III. Tìm kiếm & lọc danh sách khách hàng

Endpoint

GET /partner/bizs/{bizAlias}/customers

⚠️ Yêu cầu role: GET_LIST_CUSTOMERS

Query Parameters

Ví dụ 1: Tìm khách hàng theo SĐT

bash
curl -X GET "https://api.smax.ai/partner/bizs/my-shop/customers?phone=0901234567" \
  -H "Authorization: Bearer <TOKEN>"

Ví dụ 2: Lọc khách Zalo OA có SĐT, tối đa 50 kết quả

bash
curl -X GET "https://api.smax.ai/partner/bizs/my-shop/customers?platform=zalo&exists_phone=true&limit=50" \
  -H "Authorization: Bearer <TOKEN>"

Ví dụ 3: Lọc batch theo nhiều SĐT

bash
curl -X GET "https://api.smax.ai/partner/bizs/my-shop/customers?phones[]=0901234567&phones[]=0912345678&phones[]=0923456789" \
  -H "Authorization: Bearer <TOKEN>"

Ví dụ 4: Lọc KH theo trang và thời gian tạo

python
def search_customers(platform=None, exists_phone=None, limit=20, lt_created_at=None, page_pids=None):
    url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/customers"
    headers = {"Authorization": f"Bearer {TOKEN}"}
    params = {"limit": limit}

    if platform:
        params["platform"] = platform
    if exists_phone is not None:
        params["exists_phone"] = str(exists_phone).lower()
    if lt_created_at:
        params["lt_created_at"] = lt_created_at
    if page_pids:
        params["page_pids"] = page_pids

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

# Lấy 30 khách Messenger có SĐT, tạo trước 2026-07-01
results = search_customers(
    platform="messenger",
    exists_phone=True,
    limit=30,
    lt_created_at="2026-07-01T00:00:00Z"
)
print(f"Tìm thấy: {len(results)} khách hàng")

---

IV. Tra cứu batch (Internal)

Endpoint

GET /partner/bizs/{bizAlias}/customers-internal

⚠️ Yêu cầu role: GET_LIST_CUSTOMERS

Endpoint này cho phép tra cứu nhiều khách hàng cùng lúc theo danh sách customer_pids — hữu ích khi bạn đã có sẵn danh sách ID từ threads hoặc đơn hàng.

Query Parameters

Ví dụ

bash
curl -X GET "https://api.smax.ai/partner/bizs/my-shop/customers-internal?customer_pids[]=cust_001&customer_pids[]=cust_002&page_pids[]=page_abc123" \
  -H "Authorization: Bearer <TOKEN>"

python
def get_customers_batch(customer_pids, page_pids):
    url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/customers-internal"
    headers = {"Authorization": f"Bearer {TOKEN}"}
    params = {
        "customer_pids": customer_pids,
        "page_pids": page_pids
    }
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

# Lấy thông tin 3 khách hàng cùng lúc
customers = get_customers_batch(
    customer_pids=["cust_001", "cust_002", "cust_003"],
    page_pids=["page_abc123"]
)

💡 Khi nào dùng **customers-internal** thay vì **customers**?

• Bạn đã có danh sách customer_pid (từ threads, orders, webhook…) và cần lấy thông tin chi tiết
• Cần tra cứu nhanh nhiều KH trong 1 request thay vì gọi GET /customers/{pid} nhiều lần

---

V. Đếm tổng số khách hàng

Endpoint

GET /partner/bizs/{bizAlias}/customers/count

Trả về tổng số khách hàng của Business, hữu ích cho dashboard và báo cáo.

Ví dụ

bash
curl -X GET "https://api.smax.ai/partner/bizs/my-shop/customers/count" \
  -H "Authorization: Bearer <TOKEN>"

python
def count_customers():
    url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/customers/count"
    headers = {"Authorization": f"Bearer {TOKEN}"}
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

total = count_customers()
print(f"Tổng khách hàng: {total}")

---

VI. Lấy danh sách Tag

Endpoint

GET /partner/bizs/{bizAlias}/tags

Tag (nhãn) dùng để phân loại khách hàng trong SmaxAI. Endpoint này trả về toàn bộ danh sách tag đã tạo trong Business.

Ví dụ

bash
curl -X GET "https://api.smax.ai/partner/bizs/my-shop/tags" \
  -H "Authorization: Bearer <TOKEN>"

python
def get_tags():
    url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/tags"
    headers = {"Authorization": f"Bearer {TOKEN}"}
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

tags = get_tags()
for tag in tags:
    print(f"Tag: {tag.get('name')} (ID: {tag.get('id')})")

💡 Ứng dụng thực tế: Dùng danh sách tag ID để lọc khách hàng theo phân nhóm, hoặc hiển thị lên dropdown trong CRM nội bộ.

---

VII. Use Case thực tế: Đồng bộ khách hàng từ Google Sheets qua n8n

Kịch bản: Đội marketing có danh sách khách hàng đăng ký webinar trên Google Sheets. Bạn cần tự động đồng bộ sang SmaxAI để chatbot chăm sóc follow-up.

Luồng hoạt động

Google Sheets         n8n Workflow             SmaxAI
┌──────────┐     ┌───────────────────┐     ┌──────────────┐
│ Dữ liệu  │     │ 1. Trigger:       │     │              │
│ KH mới   │────►│   Sheet Updated   │     │  /customers  │
│           │     │                   │     │  (POST)      │
│ • Tên     │     │ 2. Loop each row  │────►│              │
│ • SĐT    │     │                   │     │  Tạo KH +    │
│ • Email   │     │ 3. HTTP Request   │     │  attrs       │
│ • Nguồn   │     │   POST /customers │     │              │
└──────────┘     │                   │     │  /customers   │
                  │ 4. Check response │◄────│  (Response)   │
                  │   → Log kết quả   │     │              │
                  └───────────────────┘     └──────────────┘

Cấu hình n8n Workflow

Node 1: Google Sheets Trigger

• Trigger on: Row Added
• Spreadsheet: Webinar Registrations
• Sheet: Sheet1

Node 2: HTTP Request (Tạo KH trên SmaxAI)

Body JSON:

json
{
  "platform": "zalo",
  "phone": "{{ $json['SĐT'] }}",
  "page_pid": "{{ $env.SMAX_PAGE_PID }}",
  "name": "{{ $json['Họ và tên'] }}",
  "attrs": [
    { "name": "email", "value": "{{ $json['Email'] }}" },
    { "name": "source", "value": "webinar_registration" },
    { "name": "campaign", "value": "{{ $json['Chiến dịch'] }}" },
    { "name": "registered_at", "value": "{{ $now.toISO() }}" }
  ]
}

Node 3: IF (Kiểm tra kết quả)

• Condition: {{ $json.statusCode }} equals 201
• True branch: Tiếp tục (hoặc log thành công)
• False branch: Gửi thông báo lỗi qua Slack/Email

Mở rộng: Đồng bộ 2 chiều

Để đồng bộ ngược từ SmaxAI về Google Sheets (ví dụ: cập nhật trạng thái sau khi chatbot tương tác), bạn thêm 1 workflow riêng:

SmaxAI Webhook          n8n Workflow              Google Sheets
┌──────────────┐    ┌────────────────────┐    ┌──────────────┐
│ KH tương tác │    │ 1. Webhook Trigger │    │              │
│ với chatbot  │───►│                    │    │ Cập nhật     │
│              │    │ 2. GET /customers  │    │ cột "Trạng   │
│ (Webhook)    │    │    ?phone=...      │───►│  thái" =     │
│              │    │                    │    │ "Đã tương    │
│              │    │ 3. Update Sheet    │    │  tác bot"    │
└──────────────┘    └────────────────────┘    └──────────────┘

---

VIII. Use Case thực tế: CRM Dashboard với Metabase

Kịch bản: Bạn muốn xây dựng dashboard theo dõi số lượng khách hàng theo thời gian, phân theo kênh và nguồn.

Script thu thập dữ liệu định kỳ (Python)

python
import requests
import json
from datetime import datetime, timedelta
import os

BASE_URL = "https://api.smax.ai"
TOKEN = os.environ["SMAX_API_TOKEN"]
BIZ_ALIAS = os.environ["SMAX_BIZ_ALIAS"]

def collect_customer_stats():
    headers = {"Authorization": f"Bearer {TOKEN}"}

    # 1. Đếm tổng KH
    count_url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/customers/count"
    total = requests.get(count_url, headers=headers).json()

    # 2. Đếm KH có SĐT
    has_phone_url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/customers?exists_phone=true&limit=1"
    # Dùng response metadata để lấy total count

    # 3. Đếm KH theo từng platform
    platforms = ["messenger", "zalo", "web"]
    by_platform = {}
    for platform in platforms:
        url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/customers?platform={platform}&limit=1"
        resp = requests.get(url, headers=headers).json()
        by_platform[platform] = resp.get("total", 0)

    # 4. Lấy danh sách tags
    tags_url = f"{BASE_URL}/partner/bizs/{BIZ_ALIAS}/tags"
    tags = requests.get(tags_url, headers=headers).json()

    stats = {
        "timestamp": datetime.now().isoformat(),
        "total_customers": total,
        "by_platform": by_platform,
        "total_tags": len(tags) if isinstance(tags, list) else 0
    }

    return stats

# Chạy và lưu kết quả
stats = collect_customer_stats()
print(json.dumps(stats, indent=2, ensure_ascii=False))

# Lưu vào file hoặc push vào NocoDB / database để Metabase đọc
with open(f"stats_{datetime.now().strftime('%Y%m%d')}.json", "w") as f:
    json.dump(stats, f, ensure_ascii=False, indent=2)

Lịch chạy gợi ý (cron / n8n Schedule)

---

IX. Xử lý lỗi thường gặp

Lỗi 401 Unauthorized

json
{ "statusCode": 401, "message": "Unauthorized" }

Nguyên nhân: Token không hợp lệ, hết hạn, hoặc thiếu header Authorization.

Giải pháp: Kiểm tra lại token, đảm bảo format Bearer <token> (có khoảng trắng sau "Bearer").

Lỗi 403 Forbidden

json
{ "statusCode": 403, "message": "Forbidden resource" }

Nguyên nhân: Token không có role GET_LIST_CUSTOMERS.

Giải pháp: Liên hệ admin SmaxAI để cấp thêm quyền cho API token.

Lỗi 400 Bad Request khi tạo KH

json
{ "statusCode": 400, "message": ["phone must be a string", "page_pid should not be empty"] }

Nguyên nhân: Thiếu trường bắt buộc (platform, phone, page_pid) hoặc sai kiểu dữ liệu.

Giải pháp: Kiểm tra body JSON đúng schema CreateCustomerByPhoneDto. Cả 3 trường platform, phone, page_pid đều bắt buộc.

Số điện thoại trùng

Khi POST một SĐT đã tồn tại trên cùng Business, API sẽ không tạo bản ghi trùng. Hành vi cụ thể (cập nhật hay bỏ qua) phụ thuộc vào cấu hình Business. Khuyến nghị: luôn kiểm tra KH tồn tại bằng GET /customers?phone=... trước khi tạo mới nếu bạn cần kiểm soát chặt chẽ.

---

X. Checklist triển khai

Trước khi đưa vào production, hãy kiểm tra:

• Token đã được lưu trong environment variable, không hardcode trong source
• Đã xác định đúng bizAlias và page_pid cho Business cần tích hợp
• Token có đủ role (GET_LIST_CUSTOMERS) cho các endpoint cần dùng
• Đã xử lý lỗi (try/catch hoặc check HTTP status) cho mọi API call
• Đã test trên Swagger UI trước khi viết code
• Format SĐT nhất quán (ví dụ: luôn dùng 0901234567, không dùng +84901234567)
• Đã thiết lập retry logic cho lỗi 429 (rate limit) và 5xx (server error)
• Nếu đồng bộ batch, giãn cách request ít nhất 100ms để tránh rate limit

---