Hướng dẫn cấu hình Zalo Ads Lead Form (qua file `.env`)

Tài liệu này hướng dẫn cấu hình bằng biến môi trường (.env) để bật tính năng Zalo Ads Lead Form — tự động kéo lead từ quảng cáo Zalo Form về CRM.

Có 2 cách cấu hình App ID/Secret/Redirect:

Qua UI (khuyến nghị cho nhiều tổ chức): Cài đặt → Zalo Ads Lead Form → ⚙ Cấu hình → lưu DB per-org. Xem user-guide/07h-zalo-ads-lead-form.md.

Qua .env (tài liệu này): đặt mặc định toàn hệ thống (fallback khi org chưa cấu hình UI).

Code đọc theo thứ tự: DB per-org (UI) → biến .env.

1. Các biến `.env` cần thiết

Biến	Bắt buộc	Mô tả & cách lấy
`TOKEN_ENCRYPTION_KEY`	✅ Bắt buộc	Khoá AES-256-GCM mã hoá token OA at-rest (DÙNG CHUNG với Facebook). 64 ký tự hex. Tạo: `openssl rand -hex 32`. App THROW nếu thiếu/không đủ 64 hex khi dùng.
`ZALO_OA_APP_ID`	✅ (hoặc UI)	App ID của Zalo App — xem Mục 2.
`ZALO_OA_APP_SECRET`	✅ (hoặc UI)	Secret Key của Zalo App — xem Mục 2.
`ZALO_OA_OAUTH_REDIRECT_URI`	✅ (hoặc UI)	URL Zalo redirect về sau khi cấp quyền. `<APP_URL>/api/v1/integrations/zalo-ads/oauth/callback` — xem Mục 4.
`ZALO_POLL_CRON`	⬜ Tuỳ chọn	Nhịp poll lead (cron 5 trường). Mặc định `/5 * * *` (5 phút).
`APP_URL`	✅ (đã có)	Tên miền công khai của CRM — dùng dựng redirect. Đã khai sẵn trong `.env`.

2. Tạo Zalo App + lấy App ID / Secret Key

Truy cập https://developers.zalo.me → đăng nhập → Ứng dụng của tôi → Tạo ứng dụng mới.
Mở app vừa tạo → tab Thông tin ứng dụng:
- Copy App ID → đặt vào ZALO_OA_APP_ID.
- Copy Secret Key → đặt vào ZALO_OA_APP_SECRET.
Vào mục Official Account trong app → liên kết OA của bạn.
Xin cấp nhóm quyền "Quản lý Ads" (bắt buộc — để gọi API oa/form/get lấy lead).

3. Xác thực quyền sở hữu tên miền

Zalo yêu cầu chứng minh bạn sở hữu tên miền (APP_URL) trước khi cho dùng OAuth.

Trong Zalo App → mục Xác thực tên miền, Zalo cấp 1 file zalo_verifierXXXX.html (chứa thẻ <meta property="zalo-platform-site-verification" content="XXXX" />).
Đặt file vào frontend/public/ của source (KHÔNG để ở thư mục gốc repo — sẽ không được serve):
```
cp zalo_verifierXXXX.html frontend/public/
```
frontend/public/ được vite copy thẳng vào frontend/dist/ khi build → app serve tại đường dẫn gốc /zalo_verifierXXXX.html. Để ở root repo HOẶC chỉ ở frontend/dist/ đều KHÔNG bền (dist bị xoá mỗi lần build).
Rebuild + restart app (Mục 6) để file vào /app/static. Kiểm tra:
```
curl -s https://<tên-miền>/zalo_verifierXXXX.html | grep zalo-platform-site-verification
# phải in ra: <meta property="zalo-platform-site-verification" content="XXXX" />
```
Nếu chạy sau Cloudflare và vẫn 404/sai nội dung: Purge cache đường dẫn đó trên Cloudflare rồi thử lại.
Bấm Xác thực trên Zalo App.

Tạm thời (không rebuild): copy thẳng vào container đang chạy để có hiệu lực ngay, nhưng vẫn PHẢI copy vào frontend/public/ cho bền:
docker cp zalo_verifierXXXX.html zalo-crm-app:/app/static/zalo_verifierXXXX.html

4. OAuth Redirect URI

Giá trị: <APP_URL>/api/v1/integrations/zalo-ads/oauth/callback
- Ví dụ deployment này: https://ee.locnguyendata.com/api/v1/integrations/zalo-ads/oauth/callback
Đặt vào .env: ZALO_OA_OAUTH_REDIRECT_URI=...
Khai TRÙNG giá trị này trong Zalo App → Đăng nhập (OAuth) → danh sách Redirect URI cho phép. Sai 1 ký tự, Zalo sẽ từ chối khi admin OA cấp quyền.

5. Sinh `TOKEN_ENCRYPTION_KEY`

openssl rand -hex 32
# → dán kết quả (64 ký tự hex) vào TOKEN_ENCRYPTION_KEY

⚠️ Đây là khoá mã hoá token. Đổi khoá = mọi token đã lưu không giải mã được (phải kết nối lại OA). Backup an toàn, KHÔNG commit vào git.

6. Mẫu khối `.env` hoàn chỉnh

Thêm vào file .env (dựa trên .env.example):

# ── Bắt buộc (khoá mã hoá token, dùng chung FB) ──
TOKEN_ENCRYPTION_KEY=<64-ky-tu-hex-tu-openssl-rand-hex-32>

# ── Zalo Ads Lead Form ──
ZALO_OA_APP_ID=3578901234567890
ZALO_OA_APP_SECRET=<secret-key-tu-zalo-app>
ZALO_OA_OAUTH_REDIRECT_URI=https://ee.locnguyendata.com/api/v1/integrations/zalo-ads/oauth/callback
ZALO_POLL_CRON=*/5 * * * *

7. Áp dụng + khởi động lại

cd /root/0project/ZCRM
docker compose up -d app          # nạp lại .env (không cần rebuild nếu chỉ đổi env)
# Nếu vừa thêm file xác thực tên miền vào frontend/public/ → cần rebuild:
# docker compose build app && docker compose up -d app

Kiểm tra cron đã chạy:

docker logs --tail 50 zalo-crm-app | grep -i zalo-poll
# kỳ vọng: [zalo-poll-cron] đã lên lịch (*/5 * * * *)

Kiểm tra route sống (401 = OK, route tồn tại + chặn auth):

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080/api/v1/integrations/zalo-ads/config   # → 401

8. Sau khi cấu hình env

.env chỉ đặt mặc định fallback. Việc còn lại làm trong UI (Cài đặt → Zalo Ads Lead Form):

Bấm Kết nối OA → admin OA cấp quyền.
Thêm form (dán Form ID từ Zalo Ads → Lead Center) → Tải câu hỏi → map câu hỏi → Lưu & đồng bộ.

Chi tiết từng bước (kèm ảnh): user-guide/07h-zalo-ads-lead-form.md.

Multi-tenant: nếu hệ thống phục vụ nhiều tổ chức, không nên dùng .env (chung toàn hệ thống) — hãy để mỗi org tự cấu hình App ID/Secret/Redirect qua UI ⚙ (lưu DB per-org, secret mã hoá). .env chỉ phù hợp khi 1 deployment = 1 tổ chức.

9. Lỗi thường gặp

Hiện tượng	Xử lý
App khởi động lỗi/throw khi lưu config	`TOKEN_ENCRYPTION_KEY` thiếu hoặc không đủ 64 hex → tạo lại bằng `openssl rand -hex 32`.
File `zalo_verifier...html` trả về giao diện app (không có thẻ meta)	File chưa nằm trong `frontend/public/` + chưa rebuild → xem Mục 3.
Zalo từ chối khi cấp quyền OA	`ZALO_OA_OAUTH_REDIRECT_URI` không khớp Redirect URI khai trong Zalo App.
"Zalo App chưa được cấu hình" khi bấm Kết nối OA	Thiếu `ZALO_OA_APP_ID`/`ZALO_OA_APP_SECRET` (env hoặc UI).
Form không ra lead	OA token lỗi (kết nối lại); chưa map câu hỏi vào SĐT; sai Form ID.

1. Các biến .env cần thiết​

2. Tạo Zalo App + lấy App ID / Secret Key​

3. Xác thực quyền sở hữu tên miền​

4. OAuth Redirect URI​

5. Sinh TOKEN_ENCRYPTION_KEY​

6. Mẫu khối .env hoàn chỉnh​

7. Áp dụng + khởi động lại​

8. Sau khi cấu hình env​

9. Lỗi thường gặp​