Tài liệu mô tả kiến trúc API của Social Tool, bao gồm cách xác thực, các module nghiệp vụ chính và quy trình tự động hóa chiến dịch. Toàn bộ API tuân theo chuẩn RESTful và bảo mật bằng JWT.
1. Thông tin chung#
| |
|---|
| Base URL | http://<domain>:<port>/api |
| Swagger | http://<domain>:<port>/swagger |
| Framework | ElysiaJS (Bun runtime) |
| Database | MySQL + Drizzle ORM |
| Múi giờ lưu trữ | UTC+0 |
Lưu ý múi giờ: Các chuỗi ngày tháng không kèm timezone (ví dụ 2026-03-22 08:48:00) sẽ được hệ thống hiểu mặc định là UTC+7 (giờ Việt Nam) trước khi chuyển đổi và lưu về UTC+0.
2. Xác thực truy cập#
Tất cả endpoint đều yêu cầu Bearer Token, ngoại trừ login và signup.Authorization: Bearer <your_jwt_token>
POST /api/auth/login với thông tin đăng nhập. Token trả về được đính kèm vào header của mọi request tiếp theo.
3. Các chức năng chính#
A. Chiến dịch#
Đây là module cốt lõi, quản lý toàn bộ kịch bản tương tác đa kênh theo ba tầng:Campaign — Chiến dịch chính, bao gồm tên và loại mạng xã hội.
Campaign Platform — Cấu hình chi tiết cho từng hành động (Like, Comment, Share), lưu trữ danh sách link/tài khoản mục tiêu (metadata_json) và quy tắc thực thi (rules_json: thời gian, số lượng, giới hạn).
Campaign Platform Task — Các tác vụ do hệ thống tự sinh ra từ cấu hình Platform và cronjob, mỗi task tương ứng với một hành động cụ thể trên một tài khoản cụ thể.
| Method | Endpoint | Mô tả |
|---|
GET | /api/campaigns | Danh sách chiến dịch |
POST | /api/campaign-platforms | Tạo cấu hình chạy |
GET | /api/campaign-platform-tasks | Theo dõi trạng thái task |
B. Tài khoản & Trang mạng xã hội#
Social Account — Tài khoản mạng xã hội (Facebook, TikTok…) được dùng để thực hiện các thao tác tương tác.
Social Page — Link bài viết, fanpage hoặc profile là đích đến của các hành động tương tác.
Social Content — Nội dung cần post/share/comment trên từng link (Có thể nội dung đã tạo sẵn hoặc do AI tự gen ra)
| Method | Endpoint | Mô tả |
|---|
GET | /api/social-accounts | Quản lý tài khoản theo nhóm hoặc riêng lẻ |
POST | /api/social-pages | Thêm và phân loại link mục tiêu |
C. Hệ thống#
Server — Là những con server chứa tool để thực hiện task.
Proxy — Quản lý xoay vòng proxy tự động, bảo vệ tài khoản khỏi bị phát hiện hoặc khoá.
4. Định dạng dữ liệu#
Request: Sử dụng application/json. Định dạng ngày tháng khuyến nghị: YYYY-MM-DD HH:mm:ss.Response: Mọi phản hồi đều theo cấu trúc thống nhất:{
"data": { ... },
"message": "Success",
"status": 200
}
5. Quy trình tự động hóa#
[1] Người dùng tạo Campaign Platform
metadata_json (links) (thời gian, số lượng)
│
▼
[2] Cron-job quét Platform có trạng thái pending
│
▼
[3] Hệ thống sinh Campaign Platform Tasks
Chia nhỏ theo cấu hình metadata & start_date
│
▼
[4] Tasks được gán → Server + Account + Proxy + Content khả dụng
│
▼
[5] Cập nhật trạng thái thời gian thực
Processing → Completed / Failed
Modified at 2026-03-30 09:47:57
