MLHUB API Sandbox v2.0
Cổng API nội bộ — đẩy dữ liệu từ FizaHub vào nền tảng tự động hóa MLHUB Engine. Master List: 186714
1. Sơ đồ kỹ thuật
graph TD
classDef client fill:#ffffff,stroke:#cbd5e1,stroke-width:2px,color:#334155;
classDef gateway fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af;
classDef step fill:#f8fafc,stroke:#94a3b8,stroke-width:1px,stroke-dasharray:4 4,color:#475569;
classDef core fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#14532d;
classDef db fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e;
classDef action fill:#faf5ff,stroke:#a855f7,stroke-width:2px,color:#581c87;
classDef err fill:#fef2f2,stroke:#ef4444,stroke-width:1px,stroke-dasharray:4 4,color:#991b1b;
subgraph L1["1. Application Layer"]
C1(FizaHub Mini App):::client
C2(Hệ thống Đối tác):::client
end
subgraph L2["2. Middleware API v2"]
M1((POST /api/v1/onboard)):::gateway
M2[Auth · x-api-key]:::step
M3[Joi Validation]:::step
M4[Alias Mapping\ngói cước · ngành]:::step
M5[Rate Limiter\n30 req / 15 min]:::step
E1[401 Unauthorized]:::err
E2[400 Bad Request]:::err
E3[429 Too Many]:::err
end
subgraph L3["3. MLHUB Engine"]
B1{createAccount\nSub-account}:::core
B2[(Master Contact\nList 186714)]:::db
end
subgraph L4["4. Automation"]
A1[Lead Scoring]:::action
A2[Workflow Trigger]:::action
A3[Sales Pipeline]:::action
end
C1 -->|POST + x-api-key| M1
C2 -->|POST + x-api-key| M1
M1 --> M5
M5 -->|OK| M2
M5 -.->|Exceeded| E3
M2 -->|Valid| M3
M2 -.->|Rejected| E1
M3 -->|Pass| M4
M3 -.->|Fail| E2
M4 --> B1
B1 -->|200 OK| B2
B2 -->|Trigger| A1
A1 --> A2
A2 --> A3
2. Mô hình Hoạt động
- Stateless: Middleware không lưu database nội bộ — mọi dữ liệu đi thẳng vào MLHUB Engine.
- Xác thực tĩnh: Mỗi đối tác nhận một
x-api-keyriêng — gửi kèm mọi request. - Rate limiting: 30 request / 15 phút / IP để bảo vệ MLHUB quota.
- Đồng bộ 1 chiều: FizaHub → Middleware → MLHUB (không có chiều ngược lại qua API này).
3. Health Check
GET
https://api-sandbox.mlhub.vn/health
Không yêu cầu xác thực. Dùng để kiểm tra server đang hoạt động bình thường.
Response 200:
{ "status": "ok", "timestamp": "2026-04-15T10:00:00.000Z" }
4. Khởi tạo Tài khoản — /api/v1/onboard
POST
https://api-sandbox.mlhub.vn/api/v1/onboard
Endpoint một chạm: tạo Sub-account trên MLHUB Engine và đồng bộ hồ sơ vào Master Contact List
186714 chỉ trong một lần gọi duy nhất.
4.1 Request Headers
| Header | Giá trị | Mô tả |
|---|---|---|
| x-api-key * | <YOUR_API_KEY> |
Mã xác thực cấp riêng cho đối tác. Liên hệ MLHUB để nhận. |
| Content-Type | application/json |
Bắt buộc khi gửi JSON body. |
4.2 Request Body — Bảng tham số đầy đủ
Dữ liệu ánh xạ theo 5 nhóm tương ứng với form FizaMLHUB Form (List 186714).
| Tham số | Kiểu | MLHUB Field ID | Mô tả / Ví dụ |
|---|---|---|---|
| Nhóm 1 — Định danh & Kết nối | |||
| fiza_id * | String | 499281 | Mã định danh khách hàng trên FizaHub. VD: FZ-0071 |
| email * | String (email) | 499283 | Email — khóa chính tạo Sub-account. VD: user@example.com |
| contact_name | String | 499280 | Họ & Tên người đại diện. VD: Nguyễn Văn K071 |
| phone | String | 499284 | Số điện thoại. VD: 0609121271 |
| Nhóm 2 — Hoạt động kinh doanh | |||
| business_name | String | 499304 | Tên cửa hàng / Hộ kinh doanh. VD: Quán Cơm Nhà Bé |
| industry | String (alias) | 499292 |
Mã ngành — tự động map sang tiếng Việt:
|
| district | String | 1000067 | Quận / Huyện. VD: Quận Hải Châu |
| address | String | 499286 | Địa chỉ chi tiết. VD: 123 Nguyễn Văn Linh |
| Nhóm 3 — Tài chính & Gói dịch vụ | |||
| package_id | String (alias) | 1168449 |
Gói cước — alias được tự động map sang Plan ID:
|
| payment_method | String | 1168988 | Hình thức thanh toán. VD: GTELPAY, Tiền mặt, Chuyển khoản |
| business_password | String (min 8) | Engine only | Mật khẩu đăng nhập MLHUB. Nếu bỏ trống, hệ thống tự sinh 8 ký tự ngẫu nhiên. |
| subscription_status | String | 1168450 | Tự động: Luôn được đặt thành ACTIVE khi onboard. |
| registration_date | Date | 1168452 | Tự động: Ngày hiện tại lúc gọi API (định dạng YYYY-MM-DD). |
| expiry_date | Date | 1168453 | Tự động: registration_date + 3 tháng dùng thử. |
| Nhóm 4 — Chăm sóc & Chấm điểm (nội bộ CSKH — không truyền từ FizaHub) | |||
| pic | String | 1168989 | Nội bộ: Nhân viên CSKH phụ trách hộ kinh doanh này. |
| lead_score | Number | 1168454 | Nội bộ: Điểm tiềm năng dựa trên mức độ sử dụng app. |
| support_note | String | 1168455 | Nội bộ: Ghi chú từ team CSKH (Biên bản Know-how). |
| onboarding_step | String | 1168456 | Nội bộ: Bước onboarding HKD đã hoàn thành. Khởi tạo = 1. |
| Nhóm 5 — Liên kết bên ngoài | |||
| website | String (URL) | 499293 | VD: https://restaurant.app |
| String (URL) | 499299 | VD: https://fb.com/restaurant |
|
| tiktok | String (URL) | 1169778 | VD: https://tiktok.com/@restaurant |
| maps | String (URL) | 499303 | VD: https://maps.app.goo.gl/xyz |
Lưu ý: Các trường Nhóm 4 (
pic, lead_score, support_note, onboarding_step) được cập nhật thủ công bởi team CSKH trực tiếp trên MLHUB — không gửi từ FizaHub qua endpoint này.
4.3 Ví dụ Request Body (đầy đủ)
{
"fiza_id": "FZ-0071",
"email": "vankhoa.lqd+k071@gmail.com",
"contact_name": "Nguyễn Văn K071",
"phone": "0609121271",
"business_name": "Tên doanh nghiệp K071",
"industry": "sop02",
"district": "Quận Hải Châu",
"address": "123 Nguyễn Văn Linh",
"package_id": "coban",
"payment_method": "GTELPAY",
"business_password": "Demo@Pass123!",
"website": "https://restaurant.app",
"facebook": "https://fb.com/restaurant",
"tiktok": "https://tiktok.com/@restaurant",
"maps": "https://maps.app.goo.gl/123"
}
4.4 Response Codes
| HTTP Status | Trường hợp | Response body mẫu |
|---|---|---|
| 200 OK | Tạo tài khoản và sync thành công | {
"success": true,
"message": "Account created and contact synced successfully.",
"data": { "mlhub_account_id": "98765", "email": "..." }
} |
| 207 Multi-Status | Tạo tài khoản OK — sync Master List thất bại, cần retry | {
"success": true,
"warning": "Account created but contact sync failed.",
"data": { "mlhub_account_id": "98765", "email": "..." }
} |
| 400 Bad Request | Thiếu fiza_id / email hoặc sai định dạng |
{
"success": false,
"error": "Validation failed",
"details": ["\"fiza_id\" là bắt buộc"]
} |
| 401 Unauthorized | Header x-api-key sai hoặc thiếu |
{
"success": false,
"error": "Unauthorized: Invalid or missing API Key"
} |
| 429 Too Many Requests | Vượt ngưỡng 30 request / 15 phút / IP | {
"success": false,
"error": "Too many requests. Please try again after 15 minutes."
} |
| 502 Bad Gateway | MLHUB Engine lỗi — không trả về account ID hoặc từ chối tạo tài khoản | {
"success": false,
"error": "Failed to create account on the engine.",
"code": "ENGINE_CREATE_FAILED"
} |
5. Bảng tra cứu MLHUB Field ID — List 186714
Nguồn gốc: Live embed code từ MLHUB List Builder (app.mlhub.vn/Lists/ListBuilder/186714). Verified ngày 15/04/2026.
| # | Tên trường (payload key) | MLHUB Field ID | Nhóm | Loại input |
|---|---|---|---|---|
| 1 | fullname (= contact_name) | 499280 | Nhóm 1 | Text |
| 2 | 499283 | Nhóm 1 | Email · Bắt buộc | |
| 3 | phone | 499284 | Nhóm 1 | Tel |
| 4 | fiza_id | 499281 | Nhóm 1 | Text |
| 5 | mlhub_id (API-only) | 499282 | Nhóm 1 | Text |
| 6 | business_name | 499304 | Nhóm 2 | Text |
| 7 | industry | 499292 | Nhóm 2 | Text |
| 8 | district | 1000067 | Nhóm 2 | Text |
| 9 | address | 499286 | Nhóm 2 | Text |
| 10 | package_id | 1168449 | Nhóm 3 | Text |
| 11 | subscription_status | 1168450 | Nhóm 3 | Text |
| 12 | payment_method | 1168988 | Nhóm 3 | Text |
| 13 | registration_date | 1168452 | Nhóm 3 | Date (d-m-Y) |
| 14 | expiry_date | 1168453 | Nhóm 3 | Date (d-m-Y) |
| 15 | pic | 1168989 | Nhóm 4 | Text · Nội bộ |
| 16 | lead_score | 1168454 | Nhóm 4 | Number · Nội bộ |
| 17 | support_note | 1168455 | Nhóm 4 | Textarea · Nội bộ |
| 18 | onboarding_step | 1168456 | Nhóm 4 | Textarea · Nội bộ |
| 19 | website | 499293 | Nhóm 5 | URL |
| 20 | 499299 | Nhóm 5 | URL | |
| 21 | tiktok | 1169778 | Nhóm 5 | URL |
| 22 | maps | 499303 | Nhóm 5 | URL |