Hướng Dẫn Tích Hợp API Phát Hành Voucher WiFi Tự Động Cho Chuỗi F&B & Bán Lẻ 2026

💡 Tóm tắt chuyên môn: Hướng dẫn toàn diện quy trình kết nối API phát hành mã WiFi Hotspot tự động cho chuỗi F&B và bán lẻ 2026. Phân tích chi tiết danh sách trường bắt buộc, tùy chọn, bảng tham số và các ví dụ request payload từ cơ bản đến nâng cao.

1. Vì Sao Chuỗi F&B Cần Tự Động Hóa Phát Hành Voucher WiFi Qua POS 2026?

Trong kỷ nguyên kinh doanh dịch vụ ăn uống (F&B) và bán lẻ hiện đại, in voucher WiFi bằng giấy hoặc phát mã thủ công bộc lộ nhiều điểm nghẽn: tốn chi phí in ấn, nhân viên quên phát mã, mã bị chia sẻ tràn lan khiến mạng nghẽn tắc.

Tích hợp IWAS Voucher Partner API trực tiếp vào phần mềm bán hàng POS mang lại 4 lợi ích vượt trội:

• Tự động cấp mã WiFi tốc độ cao ngay khi in hóa đơn hoặc khi khách tích điểm thành công.
• Cá nhân hóa theo giá trị đơn: Giảm giá 100% hoặc tặng thêm giờ truy cập tốc độ cao cho khách VIP.
• Bảo mật đa tầng: Kiểm soát chặt chẽ qua API Key định dạng iwas_pk_... với cơ chế chống gian lận Idempotent Replay.
• Tăng tỷ lệ khách quay lại (Customer Retention): Biến mã WiFi thành kênh tương tác và remarketing hiệu quả.

2. Quy Trình Lấy API Key Trên IWAS Admin Console (Dành Cho Quản Trị Viên)

Để cấp quyền cho đơn vị phần mềm POS hoặc đối tác kết nối vào hệ thống, Quản trị viên thực hiện 3 bước:

1. Đăng nhập vào IWAS Admin Console bằng tài khoản Owner hoặc Admin tổ chức.
2. Tại menu bên trái, chọn chuyên mục "Mã giảm giá" (/admin/vouchers).
3. Chuyển sang tab "Đối tác & F&B". Tại đây hiển thị danh sách các tài khoản đối tác đang kết nối.

📸 Ảnh 1: Giao diện Quản lý Đối tác & F&B trên IWAS Console. Giúp theo dõi tên đối tác, tiền tố khóa, trạng thái kích hoạt và các thao tác quản trị nhanh.

1. Bấm nút "+ Tạo đối tác mới" ở góc trên bên phải bảng danh sách.
2. Nhập tên định danh đối tác (ví dụ: "KiotViet POS - Chi nhánh Cầu Giấy" hoặc "App Loyalty Cà Phê") rồi bấm "Tạo & Sinh Key".

📸 Ảnh 2: Hộp thoại Tạo tài khoản đối tác mới. Hệ thống sẽ lập tức mã hóa và sinh mã API Key bảo mật.

1. Sao chép và bàn giao khóa bí mật: Hệ thống hiển thị mã khóa dạng iwas_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Bạn hãy sao chép và chuyển giao an toàn cho đơn vị kỹ thuật tích hợp.

⚠️ Nguyên tắc bảo mật Zero-Knowledge: IWAS chỉ lưu trữ mã băm SHA-256 của API Key. Khóa nguyên bản chỉ hiển thị duy nhất 1 lần khi tạo. Nếu vô tình làm mất khóa, hãy bấm nút "Đổi Key (Rotate Key)" để hệ thống sinh mã mới thay thế ngay tức thì.

3. Đặc Tả Kỹ Thuật API & Xác Thực (Dành Cho Nhà Phát Triển)

• Production Endpoint: https://<domain-he-thong>/api/partner/vouchers/issue
• Phương thức HTTP: POST
• Header xác thực: x-partner-api-key: iwas_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (hoặc Authorization: Bearer <key>)
• Content-Type: application/json
• Cơ chế an toàn: Xử lý giao dịch mức Serializable Isolation, chống xung đột Race Condition khi hàng loạt bill phát sinh cùng thời điểm.

4. Chi Tiết Payload Request: Phân Loại Trường Bắt Buộc & Tùy Chọn

Phần quan trọng nhất dành cho lập trình viên: Cấu trúc JSON Request Body được phân chia minh bạch thành 3 nhóm trường:

🔴 Nhóm 1: Các Trường Bắt Buộc (Required Fields)

• externalOrderId (string): BẮT BUỘC. Mã hóa đơn / mã đơn hàng duy nhất từ hệ thống POS. Hệ thống căn cứ vào mã này để đảm bảo Idempotency (gửi lại cùng ID sẽ trả lại voucher cũ, không tạo trùng).
• quantity (number): BẮT BUỘC. Số lượng voucher cần cấp. Số nguyên từ 1 đến 50.
• type (string): BẮT BUỘC. Nhận một trong hai giá trị: "percent" (chiết khấu theo %) hoặc "fixed" (giảm số tiền VND trực tiếp).
• value (number): BẮT BUỘC. Mức giảm giá. Nếu type = "percent", giá trị từ 1 đến 100. Nếu type = "fixed", giá trị là số tiền cụ thể >= 0.

🟡 Nhóm 2: Các Trường Tùy Chọn (Optional Fields)

• maxDiscount (number | null): TÙY CHỌN. Giới hạn số tiền giảm tối đa (VNĐ) khi sử dụng type = "percent". Mặc định: null (không giới hạn).
• scope (string): TÙY CHỌN. Nhận giá trị "all" (mặc định - áp dụng mọi gói cước) hoặc "specific" (chỉ áp dụng cho các gói chỉ định).
• validFrom (string ISO 8601): TÙY CHỌN. Thời điểm bắt đầu có hiệu lực (UTC). Mặc định: Có hiệu lực ngay lập tức.
• validTo (string ISO 8601): TÙY CHỌN. Thời điểm hết hạn voucher (UTC). Mặc định: Không giới hạn thời gian.
• codes (string[]): TÙY CHỌN. Danh sách mã voucher do đối tác tự đặt trước. Nếu truyền thì độ dài mảng phải bằng quantity. Nếu không truyền (khuyến nghị), IWAS tự sinh mã chuẩn XXXX-XXXX.

🔵 Nhóm 3: Trường Điều Kiện (Conditional Field)

• packageIds (number[]): ĐIỀU KIỆN. BẮT BUỘC PHẢI CÓ khi scope = "specific". Không cần truyền khi scope = "all". Chứa danh sách ID các gói cước WiFi được áp dụng.

Bảng ma trận tra cứu nhanh toàn bộ tham số:

5. Hai Mẫu Payload Thực Tế Dành Cho Lập Trình Viên

Ví dụ 1: Payload Tối Giản (Chỉ Sử Dụng Các Trường Bắt Buộc)

Phù hợp cho 90% trường hợp: Quán tặng voucher miễn phí 100% WiFi cho khách có hóa đơn mua hàng:

{
  "externalOrderId": "POS-BILL-2026-10023",
  "quantity": 1,
  "type": "percent",
  "value": 100
}

Ví dụ 2: Payload Đầy Đủ Nâng Cao (Giới Hạn Gói, Thời Gian & Trần Giảm Giá)

Phù hợp cho chương trình khuyến mãi đặc thù: Giảm 50% tối đa 30.000đ cho gói 1 Ngày và 4 Giờ, hiệu lực trong tuần lễ khai trương:

{
  "externalOrderId": "POS-BILL-2026-10024",
  "quantity": 2,
  "type": "percent",
  "value": 50,
  "maxDiscount": 30000,
  "scope": "specific",
  "packageIds": [
    1,
    3
  ],
  "validFrom": "2026-09-12T00:00:00Z",
  "validTo": "2026-09-19T23:59:59Z"
}

6. Mẫu Lệnh cURL Thử Nghiệm Nhanh

Lập trình viên có thể copy lệnh bên dưới để kiểm thử ngay trên Terminal hoặc Postman:

curl -X POST "https://wifi.example.com/api/partner/vouchers/issue" \
  -H "Content-Type: application/json" \
  -H "x-partner-api-key: iwas_pk_your_partner_api_key_here" \
  -d '{
    "externalOrderId": "POS-BILL-2026-10023",
    "quantity": 1,
    "type": "percent",
    "value": 100
  }'

7. Kết Quả Trả Về & Cơ Chế Chống Trùng Giao Dịch (Idempotent Replay)

Khi xử lý thành công, IWAS trả về HTTP 201 Created kèm mảng các mã voucher đã kích hoạt:

{
  "issuanceId": 48,
  "externalOrderId": "POS-BILL-2026-10023",
  "quantity": 1,
  "type": "percent",
  "value": 100,
  "codes": [
    "K7HN-8PX2"
  ],
  "createdAt": "2026-09-12T15:35:10.000Z",
  "idempotentReplay": false
}

🛡️ Đặc tính Idempotency tối quan trọng: Trong môi trường bán lẻ giờ cao điểm, mạng chập chờn có thể khiến POS retry gửi lại cùng externalOrderId. IWAS tự động nhận diện đơn cũ và trả về ngay kết quả ban đầu kèm cờ "idempotentReplay": true, tuyệt đối không tạo thêm mã hay làm sai lệch doanh thu.

8. Trải Nghiệm Khách Hàng Tại Điểm Bán (Captive Portal Flow)

Sau khi nhận mã voucher in trên hóa đơn bán hàng hoặc qua tin nhắn ZNS:

1. Khách hàng kết nối vào mạng WiFi của quán (SSID).
2. Trang Captive Portal tự động mở lên trong chưa đầy 300ms.
3. Khách hàng chọn gói cước và nhập mã Voucher (ví dụ: K7HN-8PX2) vào ô mã giảm giá.
4. Hệ thống IWAS Cloud RADIUS kiểm tra và mở luồng Internet tốc độ cao ngay lập tức qua lệnh RADIUS CoA.

9. Bảng Mã Lỗi Thường Gặp (Error Reference)

• 401 PARTNER_API_KEY_MISSING: Thiếu header x-partner-api-key.
• 401 PARTNER_API_KEY_INVALID: API Key không chính xác hoặc sai hash.
• 403 PARTNER_DISABLED: Tài khoản đối tác đang ở trạng thái Tạm dừng (Disabled).
• 403 INSUFFICIENT_PERMISSIONS: Tổ chức chưa kích hoạt tính năng feature.partner_tools.
• 429 PARTNER_RATE_LIMIT: Vượt quá giới hạn 60 req/phút hoặc 5.000 voucher/ngày.
• 400 QUANTITY_OUT_OF_RANGE: Số lượng voucher nằm ngoài khoảng 1 đến 50.
• 400 INVALID_SCOPE: Chọn scope: "specific" nhưng không truyền mảng packageIds.

10. Lời Kết & Liên Hệ Hỗ Trợ

Tự động hóa phát hành Voucher WiFi qua API giúp loại bỏ hoàn toàn chi phí in ấn và rủi ro thất thoát, đồng thời đem lại trải nghiệm mượt mà cho khách hàng ghé quán. Đây là vũ khí đắc lực giúp chuỗi F&B tối ưu vận hành trong năm 2026.

🚀 Cần hỗ trợ kỹ thuật hoặc cấp môi trường Sandbox thử nghiệm? Liên hệ ngay với đội ngũ kỹ sư 9xLayer Engineering qua cổng hỗ trợ tích hợp để được hỗ trợ 24/7.