AIG API Gateway

API Gateway trung gian để đăng bài tự động lên Facebook Page và Zalo OA — hỗ trợ đăng 1 nền tảng hoặc cả 2 cùng lúc.

---

📋 Yêu cầu hệ thống

Phần mềm	Phiên bản tối thiểu
Node.js	>= 18.x
MongoDB	>= 6.x
npm	>= 9.x (đi kèm Node.js)

---

Cài đặt

1. Clone hoặc mở thư mục project

cd api-gateway/server

2. Cài đặt thư viện

npm install

Các thư viện sẽ được cài tự động từ package.json:

Thư viện	Mục đích
express	Web framework
axios	Gọi HTTP đến Facebook / Zalo API
mongoose	Kết nối MongoDB
dotenv	Đọc file .env
cors	Cho phép cross-origin request
form-data	Upload ảnh/video lên Zalo
jsonwebtoken	Xử lý JWT (dự phòng)
bull	Queue xử lý background
redis	Backend cho Bull queue
winston	Logging
nodemon	Tự restart khi code thay đổi (dev)

---

Cấu hình môi trường

1. Tạo file .env

Copy file mẫu:

cp .env.example .env

Hoặc tạo file .env mới trong thư mục server/ với nội dung sau:

# ── Bảo mật Gateway ───────────────────────────────────────────
API_KEY=your_secret_api_key_here

# ── Facebook ──────────────────────────────────────────────────
FB_APP_ID=your_facebook_app_id
FB_APP_SECRET=your_facebook_app_secret
FB_ACCESS_TOKEN=your_user_access_token
FB_PAGE_ID=your_facebook_page_id

# ── Zalo ──────────────────────────────────────────────────────
ZALO_APP_ID=your_zalo_app_id
ZALO_APP_SECRET=your_zalo_app_secret
ZALO_ACCESS_TOKEN=your_zalo_access_token
ZALO_REFRESH_TOKEN=your_zalo_refresh_token

# ── Server ────────────────────────────────────────────────────
PORT=3000
NODE_ENV=development

# ── Database ──────────────────────────────────────────────────
MONGODB_URI=mongodb://localhost:27017/aig_marketing

---

2. Hướng dẫn lấy từng credential

Facebook

Bước 1 — Tạo App Facebook:

1. Vào developers.facebook.com → My Apps → Create App
2. Chọn loại app → điền tên → tạo app
3. Vào Settings → Basic → copy App ID → điền vào FB_APP_ID
4. Copy App Secret → điền vào FB_APP_SECRET

Bước 2 — Lấy User Access Token:

1. Vào Graph API Explorer
2. Chọn app của bạn ở góc phải
3. Thêm các quyền: pages_manage_posts, pages_read_engagement, pages_show_list
4. Nhấn Generate Access Token → copy token → điền vào FB_ACCESS_TOKEN

Bước 3 — Lấy Page ID:

1. Vẫn trong Graph API Explorer, đổi URL thành /me/accounts → nhấn Get
2. Tìm trang muốn đăng → copy giá trị "id" → điền vào FB_PAGE_ID

Lưu ý: Server sẽ tự động đổi User Token → Page Access Token khi khởi động. Không cần điền Page Access Token thủ công.

---

Zalo

Bước 1 — Tạo App Zalo:

1. Vào developers.zalo.me → Ứng dụng của tôi → Tạo ứng dụng mới
2. Copy App ID → điền vào ZALO_APP_ID
3. Copy Secret Key → điền vào ZALO_APP_SECRET

Bước 2 — Lấy Access Token & Refresh Token:

1. Vào Zalo OAuth Tool
2. Đăng nhập bằng tài khoản quản lý OA
3. Cấp quyền → copy access_token → điền vào ZALO_ACCESS_TOKEN
4. Copy refresh_token → điền vào ZALO_REFRESH_TOKEN

Lưu ý: Zalo Access Token hết hạn sau ~1 giờ. Server sẽ tự động làm mới mỗi 50 phút bằng Refresh Token.

---

▶️ Chạy server

Môi trường Development (có auto-restart)

npm run dev

Môi trường Production

npm start

Kiểm tra server đang chạy

curl http://localhost:3000/health

Kết quả mong đợi:

{ "status": "ok", "uptime": 12.34 }

---

API Endpoints

Tất cả các request cần header:

x-api-key: <API_KEY trong .env>

---

POST /api/v1/content/post — Đăng bài (Endpoint chính)

Đăng lên Facebook Page, Zalo OA, hoặc cả hai cùng lúc.

Cấu trúc thư mục

server/
├── src/
│   ├── index.js              # Entry point — khởi động Express server
│   ├── config/
│   │   ├── env.js            # Load biến môi trường từ .env
│   │   └── db.js             # Kết nối MongoDB
│   ├── middlewares/
│   │   └── auth.js           # Xác thực x-api-key
│   ├── routes/
│   │   ├── facebookRoutes.js # Định tuyến Facebook
│   │   ├── zaloRoutes.js     # Định tuyến Zalo
│   │   └── contentRoutes.js  # Định tuyến Content (đăng 2 kênh)
│   ├── controllers/
│   │   ├── facebookController.js  # Xử lý logic Facebook
│   │   ├── zaloController.js      # Xử lý logic Zalo
│   │   └── contentController.js   # Xử lý đăng đa kênh
│   ├── adapters/
│   │   ├── facebookAdapter.js     # Gọi Facebook Graph API
│   │   └── zaloAdapter.js         # Gọi Zalo Open API
│   └── models/
│       ├── PostLog.js        # Lịch sử đăng bài
│       ├── Content.js        # Nội dung bài đăng
│       ├── Campaign.js       # Chiến dịch
│       ├── Schedule.js       # Lịch đăng
│       ├── Automation.js     # Tự động hóa
│       ├── Analytics.js      # Phân tích
│       └── AuditLog.js       # Log kiểm toán
├── .env                      # Biến môi trường (KHÔNG commit lên git)
├── .env.example              # Mẫu file .env
└── package.json

---

🛡️ Giới hạn quota

Nền tảng	Giới hạn	Xử lý khi vượt
Facebook	25 bài/ngày/group	Đẩy vào queue, đăng lúc 00:01 hôm sau
Zalo OA	10 bài/ngày	Đẩy vào queue, đăng lúc 00:01 hôm sau

---

❓ Lỗi thường gặp

Lỗi	Nguyên nhân	Cách xử lý
401 Thiếu API Key	Thiếu header x-api-key	Thêm header vào request
Token khong hop le	FB_ACCESS_TOKEN sai hoặc hết hạn	Tạo token mới trên Graph API Explorer
FB_PAGE_ID chua cau hinh	Thiếu FB_PAGE_ID trong .env	Thêm Page ID vào .env
Khong nhan duoc page access_token	Token thiếu quyền pages_manage_posts	Generate lại token với đủ quyền
MongoDB Kết nối thất bại	MongoDB chưa chạy	Khởi động MongoDB
Zalo error -216	Zalo token hết hạn	Server tự refresh — kiểm tra ZALO_REFRESH_TOKEN