Zalo CRM 360 — Tài liệu API

Base URL https://zalo-crm-360.pages.dev

1. Xác thực

Mọi lời gọi API phải kèm khóa bí mật trong header:

X-API-Key: <API_KEY_ĐƯỢC_CẤP>

Hoặc truyền qua tham số URL ?api_key=... (kém an toàn hơn, chỉ dùng khi thử nhanh). Thiếu hoặc sai khóa sẽ nhận 401 Unauthorized.

2. API — Kéo hồ sơ về

Ví dụ

curl "https://zalo-crm-360.pages.dev/api/crm/profiles?limit=50" \
     -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "count": 50,
  "next_cursor": "1405276800038875490",
  "items": [ { /* ...hồ sơ, xem mục 4... */ } ]
}

Lặp lại với ?cursor=<next_cursor> cho đến khi next_cursor bằng null (hết dữ liệu).

curl "https://zalo-crm-360.pages.dev/api/crm/1405276800038875490" \
     -H "X-API-Key: YOUR_API_KEY"

Đồng bộ định kỳ (gợi ý)

// mỗi 15 phút, lấy hồ sơ mới cập nhật từ lần đồng bộ trước
let since = lastSyncTime;      // ISO, lưu ở CRM của bạn
let cursor = "";
do {
  const r = await fetch(`${BASE}/api/crm/profiles?limit=200&since=${since}&cursor=${cursor}`,
    { headers: { "X-API-Key": API_KEY } });
  const data = await r.json();
  for (const p of data.items) upsertToCRM(p);   // khớp theo phone/uid
  cursor = data.next_cursor;
} while (cursor);
lastSyncTime = new Date().toISOString();

3. Webhook — Nhận hồ sơ tự động

Thay vì tự kéo, bạn cung cấp một URL nhận. Mỗi khi một khách được phân tích/làm giàu mới, hệ thống sẽ POST hồ sơ đó tới URL của bạn.

Xác minh chữ ký (bảo mật)

Tính HMAC-SHA256 của nội dung thô bằng khóa bí mật đã thống nhất, so với header X-ZCRM-Signature:

import crypto from "crypto";
function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret)
                         .update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
// Trong handler:
if (!verify(rawBody, req.headers["x-zcrm-signature"], SECRET))
  return res.status(401).end();
res.status(200).end();   // trả 2xx để báo đã nhận

4. Cấu trúc dữ liệu hồ sơ

{
  "uid": "1405276800038875490",   // ID Zalo (khóa nối)
  "name": "Nguyễn Văn A",
  "phone": "84984xxxxxx",         // khóa nối phụ
  "email": "a@example.com",
  "avatar": "https://...",
  "is_friend": 1,

  "analysis": {                   // Chân dung do AI phân tích
    "summary": "Tóm tắt khách hàng",
    "personality": "Tính cách",
    "disc_type": "D | I | S | C",
    "communication_style": "Cách giao tiếp",
    "interests": ["quan tâm 1", "..."],
    "pain_points": ["nỗi đau 1", "..."],
    "buying_signals": ["tín hiệu mua", "..."],
    "objections": ["băn khoăn/phản đối", "..."],
    "funnel_stage": "Giai đoạn phễu",
    "buying_intent": "cao | trung bình | thấp",
    "lead_score": 85,             // điểm khách tiềm năng 0-100
    "confidence": "Độ tin cậy phân tích",
    "best_time_to_reach": "Thời điểm nên liên hệ",
    "next_action": "Hành động nên làm tiếp",
    "opening_line": "Câu mở đầu gợi ý",
    "products_fit": ["sản phẩm phù hợp", "..."],
    "tags": ["nhãn", "..."],
    "analyzed_at": "2026-09-04T10:00:00+07:00"
  },

  "enrichment": {                 // Làm giàu từ nguồn công khai
    "summary": "Tóm tắt tra cứu",
    "company": "Công ty",
    "role": "Chức vụ",
    "socials": ["https://facebook.com/..."],
    "sources": ["https://nguồn-công-khai/..."],
    "email": "email nếu tìm được",
    "confidence": "Độ tin cậy",
    "enriched_at": "2026-09-04T10:05:00+07:00"
  }
}

5. Mã lỗi