API Agency

Trang này dành cho Agency: gồm API User (dùng chung) và API Agency (dashboard). Yêu cầu header Authorization: Bearer <token>. Base URL: https://api.zca.vn/api.

Phần 1 — API User (API Key, 1 user = 1 API Key)

User dùng một API Key để gọi mọi endpoint tích hợp (gửi tin, template, access-token, oa-info). Header: Authorization: Bearer <api-key>. Base URL: https://api.zca.vn/api.

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.

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"}}'

Gửi tin ZNS (ZBS) & Zalo / Template

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?.
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. Chỉ cần template_id (query). oa_id tùy chọn — 1 user 1 OA thì không cần.

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

Response: template_name, list_params (biến dùng trong template_data khi gửi tin), price, status.

Ví & Giao dịch

Method	Path	Mô tả
GET	/user/wallet	Số dư ví: main_balance, credit_balance, total
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, ...)

Phần 2 — API Agency (Dashboard)

Các endpoint riêng cho Agency (role RESELLER hoặc ADMIN): ví, tier, cấu hình thanh toán, sub-users, rút tiền, developer.

Ví & Tier

Method	Path	Mô tả
GET	/dashboard/wallet	Số dư ví (main_balance, credit_balance, total)
GET	/dashboard/tier/stats	Thống kê Tier: totalVolume, currentTier, nextTier, volumeToNextTier, progressPercent
GET	/dashboard/tier/tiers	Danh sách Commission Tiers (bảng hạng chiết khấu)

Cấu hình thanh toán

Method	Path	Mô tả
GET	/dashboard/payment-config	Lấy cấu hình TK nhận tiền (bank, account, transfer_prefix, delegate_payment, ...)
PUT	/dashboard/payment-config	Lưu cấu hình. Body: bank, account, account_name, transfer_prefix?, delegate_payment?, agency_participates_referral?
GET	/dashboard/payment-info	Thông tin chuyển khoản + QR. Query: amount=xxx
GET	/dashboard/auto-withdraw-config	Lấy cấu hình rút tiền tự động
PUT	/dashboard/auto-withdraw-config	Cập nhật cấu hình rút tự động

Quản lý User con (Sub-users)

Method	Path	Mô tả
GET	/dashboard/sub-users	Danh sách User thuộc Agency (id, email)
GET	/dashboard/oa-list	Danh sách OA (sub-users + OA + ví). Query: sort=email
POST	/dashboard/transfer-credit	Chuyển Credit sang User. Body: { user_id, amount }
POST	/dashboard/adjust-balance	Điều chỉnh ví User (cộng/trừ Cash hoặc Credit). Body: { user_id, amount, balance_type: "MAIN"\|"CREDIT", description? }. Chỉ Agency không ủy thác.

Rút tiền

Method	Path	Mô tả
POST	/dashboard/withdraw	Tạo yêu cầu rút tiền. Body: { amount, bank_name?, bank_account?, bank_holder? }. Admin duyệt sau.

Developer & Webhook

Method	Path	Mô tả
GET	/dashboard/developer-config	Lấy cấu hình Developer (webhook_url, API key masked)
PUT	/dashboard/developer-config	Cập nhật webhook_url
POST	/dashboard/developer-config/create-api-key	Tạo API Key mới (dùng cho webhook nạp tiền Sepay)

Referral & Khác

Method	Path	Mô tả
GET	/dashboard/referrals	Danh sách referral. Query: status
GET	/dashboard/referral-campaigns	Danh sách chiến dịch mời bạn bè (PENDING)
POST	/dashboard/referral-campaigns/:id/approve	Duyệt ref (thưởng cho referrer + referee)
POST	/dashboard/referral-campaigns/:id/reject	Từ chối ref
GET	/dashboard/business-info	Thông tin kinh doanh đã lưu
PUT	/dashboard/business-info	Lưu thông tin kinh doanh