Hướng dẫn kết nối sử dụng – API Connect (v1) trên nền tảng Zozo Website

Hướng dẫn sử dụng Zozo Website – API Connect (v1) cho các ứng dụng

Tổng quan

API Connect (v1) giúp website trở thành trung tâm kết nối dữ liệu: mở API an toàn, tạo/khóa/luân phiên token, phân quyền chi tiết theo nhóm chức năng, giới hạn IP và tốc độ, theo dõi lịch sử và phân tích lưu lượng. Phù hợp kết nối CRM, n8n, App, ERP/Kế toán, Marketing.

Thực hiện (mấu chốt):

Bật API và cấu hình an toàn (IP + rate limit).
Tạo token cho từng mục đích (CRM, n8n, App…).
Gán quyền (Scopes) đúng nhu cầu.
Tích hợp client qua header api_token.
Theo dõi History (lọc, biểu đồ, xuất CSV) và log file viewer.

1) Bật tính năng API (Settings)

Bật/tắt kênh API ở cấp hệ thống và dựng “vòng bảo vệ” bằng IP allowlist + rate limit để tránh lạm dụng.

Thực hiện:

Vào Admin → Extensions → Channels → API Connect (v1).
Tab Settings:
- Status → Enabled.
- Allowed IPs → mỗi IP một dòng (IP máy chủ n8n/CRM/App).
- Global Rate Limit → limit (số request) và window (giây), ví dụ: 1000 trong 3600.
Nhấn Save.

2) Quản lý Token (tạo, khóa, luân phiên, phân quyền)

Token là “chìa khóa” cho ứng dụng bên ngoài. Mỗi token gắn một mục tiêu (CRM Sync, n8n AutoPost, Mobile App…). Có Create (hiện plaintext 1 lần), Revoke (khóa ngay), Rotate (secret mới), và phân quyền theo nhóm (Scopes).

Thực hiện:

Tab Tokens → Generate Token → đặt tên (VD: CRM_Orders, n8n_News).
Sao chép plaintext token dạng token_key.secret ngay khi hiện (chỉ hiển thị 1 lần).
Roles/Scopes → chọn nhóm và quyền cần (VD: news::list, news::create, news::update).
Revoke khi cần khóa (hàng sẽ hiển thị Revoked, vô hiệu các nút sử dụng).
Rotate để tạo secret mới (hiển thị 1 lần) khi nghi lộ hoặc theo chu kỳ.

Quy ước đặt tên: Mục đích_Hệ thống (VD: CRM_Getfly, n8n_AutoPost, App_Android, ERP_Odoo).
Nguyên tắc quyền tối thiểu: chỉ tick đúng endpoints cần dùng.

3) Giới hạn IP & Rate Limiting

Giới hạn IP quyết định “ai được vào”; Rate limit quyết định “vào rồi bao nhiêu là đủ”. Giảm nguy cơ lạm dụng API, brute-force và lỗi cấu hình.

Thực hiện:

Điền Allowed IPs (IP cố định phía tích hợp).
Đặt Rate Limit phù hợp (VD: 3000 requests trong 3600 giây).
Lưu lượng lớn có thể dùng Redis limiter (nếu hạ tầng cho phép), vẫn giữ DB logs để phân tích.

4) Lịch sử & Phân tích (History)

Ghi lại toàn bộ request: endpoint, IP, status code, thời gian phản hồi… Có lọc, xuất CSV, biểu đồ 30 ngày và xem file log theo ngày để debug.

Thực hiện:

Tab History → lọc theo Token / Endpoint / IP / Status / Date → Search.
Export CSV để phân tích ngoài (Excel/BI).
Xem biểu đồ Usage (30 days) để nắm xu hướng.
Log file viewer: chọn file api_YYYY-MM-DD.log → xem nội dung.

5) Ứng dụng phổ biến tại Việt Nam

Một token cho một mục đích, phân quyền đúng nhu cầu. Dưới đây là các tích hợp thường gặp.

CRM (Getfly, OnlineCRM, Bitrix24, Zoho): đồng bộ khách hàng & đơn hàng (scopes ví dụ: order::create, customer::create).
n8n (Automation): đăng tin/sản phẩm tự động, gửi thông báo Zalo OA, đồng bộ Google Sheet (scopes nhóm news/product).
App di động: hiển thị sản phẩm, đơn hàng, hồ sơ khách hàng (scopes ví dụ: product::list, order::list).
ERP/Kế toán (MISA, FAST, Odoo): đồng bộ tồn kho, doanh thu, công nợ (scopes: order::list, product::stock, invoice::create).
Marketing (Zozo EMA, Mailchimp, Zalo OA): đồng bộ subscriber, kích hoạt chiến dịch remarketing.

6) Cách gọi API (mẫu chung)

Client thực hiện gọi API có bao gồm token qua header với tên api_key. Một số endpoint yêu cầu role cụ thể; thiếu quyền sẽ bị từ chối báo lỗi.

Với tất cả các kết nối, URL API chính là tên miền của quý khách hàng đang sử dụng trên hệ thống của Zozo, ví dụ: https://yourdomain.com, vui lòng sử dụng url này kết với URL path của mỗi API cụ thể.

Thực hiện:

Header: api_key: token_key.secret

curl -s -H "api_token: a1b2c3d4e5f6.9f8e7d6..." \
"/api/v1/news/list"

{
  "success": true,
  "data": [
    { "news_id": 1, "title": "Tin A", "date_added": "2025-09-01" },
    { "news_id": 2, "title": "Tin B", "date_added": "2025-09-03" }
  ]
}

Lỗi chuẩn:

401 {"error":"Missing API token"}
401 {"error":"Invalid API token"}
403 {"error":"Token does not have required permission"}
429 {"error":"Rate limit exceeded"}

7) Ví dụ nhóm News (xem, thêm, sửa)

Nhóm “News” thường dùng cho kịch bản n8n đăng bài tự động hoặc biên tập nội dung.

Thực hiện:

List (news::list)

GET /api/v1/news/list
Header: api_token

{
  "success": true,
  "data": [
    { "news_id": 12, "title": "Hướng dẫn API A", "date_added": "2025-09-07" },
    { "news_id": 11, "title": "Cập nhật sản phẩm B", "date_added": "2025-09-05" }
  ],
  "paging": { "page": 1, "limit": 20, "total": 128 }
}

Create (news::create)

POST /api/v1/news/create
Header: api_key
Body (JSON)
{
  "title": "Bài viết API demo",
  "description": "Nội dung...",
  "status": 1
}

{ "success": true, "news_id": 13 }

Update (news::update)

POST /api/v1/news/update&news_id=13
Header: api_key
Body (JSON)
{
  "title": "Bài viết API demo (cập nhật)",
  "status": 1
}

{ "success": true }

8) Vận hành & An toàn (khuyến nghị)

Mô tả: Vận hành tốt giúp ổn định, an toàn lâu dài. Ba nguyên tắc: giới hạn, giám sát và luân phiên.

Thực hiện:

Một token – một mục đích; phân quyền tối thiểu.
Luôn có IP allowlist và rate limit hợp lý.
Rotate định kỳ; Revoke ngay khi nghi lộ.
Theo dõi History hàng tuần; xuất CSV khi đối soát.
Quy trình sự cố: Revoke → rà soát logs → Rotate → khôi phục.

9) Checklist triển khai nhanh

Status = Enabled.
Nhập Allowed IPs.
Thiết lập Global Rate Limit.
Tạo token cho từng hệ tích hợp và đặt tên rõ ràng.
Gán Scopes đúng nhu cầu.
Lưu plaintext token an toàn (secret hiển thị 1 lần).
Tích hợp client qua api_token.
Kiểm thử 1–2 request thực tế.
Kiểm tra History & Usage Chart.
Lên lịch Rotate định kỳ và quy trình Revoke khẩn cấp.

10) FAQ ngắn

Quên lưu plaintext token? Dùng Rotate để tạo secret mới, cập nhật client.
401/403? Kiểm tra api_token, trạng thái token (Revoked?), IP allowlist và Scopes.
429? Tăng giới hạn hoặc tối ưu client (batching, caching).
Tạm ngắt API? Settings → Status = Disabled.

Biểu đồ mô tả kết nối tường minh

+---------------------------+          +---------------------+
|    n8n (Automation)      |  HTTP    |   CRM (Getfly/...)   |
|  - Auto post News        | <------> | - Create Leads/Deals |
+------------+--------------+          +----------+----------+
             |                                  |
             |                                  |
             v                                  v
      +------+-----------------------------------+----------------------+
      |                           Zozo Website                          |
      |                        API Connect (v1)                         |
      |                                                                 |
      |  [Settings]  Status | Allowed IPs | Global Rate Limit           |
      |  [Tokens]    Create | Rotate | Revoke | Roles/Scopes | Last used|
      |  [History]   Filter | Export CSV | Usage (30d) | Log Viewer     |
      |                                                                 |
      |  Request Flow:                                                  |
      |  1) Client sends api_token                                      |
      |  2) Verify token (hash), check IP allowlist                     |
      |  3) Check Scopes & Rate Limit                                   |
      |  4) Dispatch to Controller (e.g., api/v1/news/*)                |
      |  5) Log to DB (endpoint, ip, status, time), update last_used    |
      |  6) JSON Response                                               |
      +---+--------------------+---------------------+------------------+
          |                    |                     |
          |                    |                     |
          v                    v                     v
+---------+--------+   +-------+---------+   +-------+---------+
|   Mobile App     |   | ERP/Kế toán     |   | Marketing       |
| - Product List   |   | - Orders/Stock  |   | - Zozo EMA/Zalo |
| - Order Status   |   | - Invoices      |   | - Mailchimp     |
+------------------+   +-----------------+   +-----------------+

Ghi chú: Thương hiệu nền tảng: Zozo Website. Tất cả ví dụ API trả JSON, dùng header api_token. Nhóm News là ưu tiên phổ biến cho n8n đăng bài tự động.

Tag: