API User

Các endpoint tích hợp dành cho User. 1 user = 1 API Key — dùng API Key cho mọi endpoint (không dùng JWT). Header: Authorization: Bearer <your-api-key>. Base URL: https://api.zca.vn/api.

Lấy API Key tại Portal → User → Developers (API Key). Client secret chỉ hiển thị một lần khi tạo, vui lòng lưu lại.

Lưu ý: Trang này chỉ dành cho User. Nếu bạn là Agency, xem tài liệu đầy đủ tại API Agency.

Hướng dẫn gửi tin ZBS (ZNS) qua API Key

Gửi một tin ZBS (ZNS) từ n8n, script hoặc app: dùng API Key trong header, gọi POST /api/zns/send.

Lấy API Key — Portal → User → Developers → tạo/lấy API Key (client_secret).
Gửi 1 tin ZNS — POST /api/zns/send, header Authorization: Bearer <api-key>, body: template_id, phone, template_data. oa_id tùy chọn.
Ví dụ (curl) — Xem bên dưới.

curl -X POST "https://api.zca.vn/api/zns/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"365511","phone":"84912345678","template_data":{"ten_khach_hang":"Nguyễn A","ma_du_an":"INV-001"}}'

template_data có thể là object hoặc mảng [{ "name": "ten_bien", "value": "..." }].

Gửi tin ZNS (ZBS)

Method	Path	Mô tả
POST	/api/zns/send	Gửi 1 tin ZNS. Body: `template_id`, `phone`, `template_data`, `oa_id?` (tùy chọn).
POST	/api/zns/bulk-send	Gửi nhiều tin ZNS. Body: `template_id`, `campaign_data: [{ phone, template_data }]`, `oa_id?`, `campaign_name?`.

Zalo OA & Template

Method	Path	Mô tả
GET	/api/zalo/access-token	Lấy access_token Zalo OA. Query: `oa_id?` (optional).
GET	/api/zalo/templates	Danh sách templates ZNS. Query: `oa_id`, `offset`, `limit`, `status`.
GET	/api/zalo/template-detail	Chi tiết 1 template ZBS. Query: `template_id` (bắt buộc), `oa_id?` (tùy chọn — 1 user 1 OA thì không cần).
GET	/api/zalo/oa-info	Thông tin OA (verified, package, expiry). Query: `oa_id?`.

Lấy chi tiết 1 template ZBS (ZNS)

Dùng GET /api/zalo/template-detail để lấy thông tin một template: tên, danh sách biến (list_params), giá tin, trạng thái. Chỉ cần truyền template_id (query). oa_id tùy chọn — 1 user 1 OA thì không cần.

Lấy API Key tại Portal → User → Developers.
Gọi GET .../zalo/template-detail?template_id=TEMPLATE_ID với header Authorization: Bearer <api-key>.

curl -X GET "https://api.zca.vn/api/zalo/template-detail?template_id=365511" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response thường chứa template_name, list_params (mảng biến dùng trong template_data khi gửi tin), price, status, v.v.

Ví dụ body gửi tin: { "template_id": "365511", "phone": "84912345678", "template_data": { "ten_khach_hang": "Nguyễn A", "ma_du_an": "INV-001" } }

Các endpoint dưới đây dùng khi đăng nhập Portal (JWT), không gọi bằng API Key.

Ví & Giao dịch (Portal)

Method	Path	Mô tả
GET	/user/wallet	Số dư ví (dùng JWT trên Portal)
POST	/user/wallet/topup	Nạp tiền (Main). Body: { amount, description? }. Có thể kích hoạt thưởng Referral 5M+5M nếu đủ điều kiện.
GET	/user/ledger	Lịch sử giao dịch. Query: limit=50, offset=0

Zalo OA

Method	Path	Mô tả
GET	/user/zalo/token	Token Zalo OA đã lưu (connected, oa_id, expires_at). Dùng để gọi Zalo API gửi tin.

Giới thiệu (Referrals)

Method	Path	Mô tả
GET	/user/referrals	Danh sách người được giới thiệu. Query: status=PENDING\|COMPLETED

Phân tích & Báo cáo

Method	Path	Mô tả
GET	/user/analytics	Phân tích User. Query: from, to (ISO date). Mặc định tháng hiện tại.
GET	/user/analytics/by-day	Thống kê theo ngày. Query: from, to
GET	/user/analytics/campaigns	Báo cáo theo chiến dịch. Query: from, to

Thanh toán & Hóa đơn

Method	Path	Mô tả
GET	/user/payment-info	Thông tin chuyển khoản + QR. Query: oa_id, amount, request_invoice=1
GET	/user/invoice-info	Lấy thông tin hóa đơn đã lưu
PUT	/user/invoice-info	Lưu thông tin hóa đơn (company name, tax code, address, ...)