Dữ liệu khi truyền vào tham số (param) được hệ thống cài đặt với một số định dạng nhất định. Bài viết này sẽ liệt kê chi tiết các dạng dữ liệu truyền vào tham số và cách hiển thị trên tin nhắn ZBS Template, nhằm giúp đối tác lập trình hiểu rõ cách định dạng dữ liệu trước khi gọi API gửi tin đến người dùng cuối.
1. Hướng dẫn cài đặt kỹ thuật tham số
Trong quá trình tạo mẫu tin, tại bước “Tạo nội dung” sẽ có phần cài đặt kỹ thuật cho tham số. Mỗi tham số sẽ có các yêu cầu kỹ thuật khác nhau, người dùng cần lưu ý chọn đúng loại cài đặt và truyền đúng định dạng, độ dài ký tự vào param.
Ví dụ:
- Doanh nghiệp chọn tham số
<customer_name>với cài đặt kỹ thuật là Tên khách hàng (30) thì độ dài ký tự tối đa truyền vào API là 30 ký tự. - Đối với các tham số liên quan đến thời gian (ngày/tháng/năm hoặc giờ:phút:giây), bắt buộc chọn đúng định dạng kỹ thuật là Thời gian.
Tương ứng với từng tham số sẽ có các cài đặt kỹ thuật khác nhau
2. Các định dạng của tham số khi tạo mẫu tin
a. Tham số trong nội dung chính
Đối với các tham số được truyền vào ở nội dung chính của template, không cần thực hiện mã hóa, mà có thể giữ nguyên dữ liệu gốc khi truyền vào API gửi ZNS.
| # | Nhãn tham số | Tên tham số | Cài đặt kỹ thuật | Giới hạn | Data type | Dữ liệu truyền vào (Ví dụ) |
|---|---|---|---|---|---|---|
| 1 | Tên khách hàng | customer_name |
Tên khách hàng (30) | 30 | string | Nguyễn Văn A |
| 2 | Điện thoại | phone_number |
Số điện thoại (15) | 15 | string | 096987453x |
| 3 | Địa chỉ | address |
Địa chỉ (80) | 80 | string | 104 Tạ Quang Bửu |
| 4 | Mã số | product_code |
Mã số (30) | 30 | string | TP-34512 |
| 5 | Nhãn tùy chỉnh | custom_field |
Nhãn tùy chỉnh (30) | 30 | string | Mẫu nội dung tuỳ chỉnh |
| 6 | Trạng thái giao dịch | transaction_status |
Trạng thái giao dịch (30) | 30 | string | Giao dịch thành công |
| 7 | Thông tin liên hệ | contact |
Thông tin liên hệ (50) | 50 | string | 096987453x |
| 8 | Giới tính / Danh xưng | personal_title |
Giới tính / Danh xưng (5) | 5 | string | Chị |
| 9 | Tên sản phẩm | product_name |
Tên sản phẩm / Thương hiệu (100) | 100 | string | Bàn phím Razer |
| 10 | Số lượng / Số tiền | amount_vn_standard |
Số lượng / Số tiền (20) | 20 | number |
– Truyền số nguyên: 1000 → Hiển thị: 1.000– Truyền thập phân: 0.3 → Hiển thị: 0,3
|
| 11 | Thời gian | time |
Thời gian (20) | 20 | datetime |
Các định dạng hợp lệ: hh:mm:ss, hh:mm hh:mm:ss dd/mm/yyyy hh:mm dd/mm/yyyy dd/mm/yyyy, mm/yyyy |
| 12 | Bank Transfer Note | bank_transfer_note |
Bank Transfer Note (90) | 90 | Bank Transfer |
Không cho phép các ký tự đặc biệt:@[]^_!"•#$%¥&'()*+,€-./:;{|<}=~>?
|
b. Tham số tại nút thao tác (CTA đường dẫn liên kết)
*Lưu ý quan trọng: Doanh nghiệp NÊN mã hóa các tham số truyền vào ở đường liên kết CTA. Không mã hóa toàn bộ đường liên kết vì sẽ ảnh hưởng đến chất lượng template và gây lỗi.
Khi thiết lập CTA Đường dẫn liên kết, cần đảm bảo:
- Nên mã hóa các dữ liệu truyền vào tham số ở đường liên kết CTA (dù không bắt buộc nhưng được khuyến nghị để tránh lỗi parse URL).
- Các tham số trong CTA phải có tên khác với các tham số đã được định nghĩa trong phần nội dung chính & tiêu đề của Template.
Việc mã hóa dữ liệu truyền vào tham số sẽ giúp hệ thống giải mã các tham số một cách chính xác và hoàn chỉnh liên kết mà Doanh nghiệp đã sử dụng.
VD: Dữ liệu cần truyền vào tham số tại nút thao tác là “Nguyễn Văn A”, dữ liệu truyền vào cần được mã hóa trước theo chuẩn UTF-8 như sau:
| Tên tham số | Cài đặt kỹ thuật | Data type | Dữ liệu truyền vào (Đã mã hóa) | Dữ liệu hiển thị |
|---|---|---|---|---|
customer_name |
URL (200) | string | Nguy%E1%BB%85n+V%C4%83n+A | Giữ nguyên |
Sau khi định dạng các tham số, Liên kết (URL) truyền vào CTA sẽ có dạng là:
https://example.com/param?customer_name=<param1>&URL=<param2>
3. Các định dạng dữ liệu khác (Trường hợp đặc biệt)
Dành cho các tài khoản có template được tạo qua yêu cầu đặc biệt từ Zalo.
| # | Data type | Quy định dữ liệu truyền vào |
|---|---|---|
| 1 | Number |
Cho phép ký tự số. Bao gồm số dương, số âm và số thập phân (phần nguyên và thập phân ngăn cách bởi dấu “.”). Ví dụ: 123 | 100000 | -100 | -100.2
|
| 2 | DateTime |
Các format cho phép:hh:mm:ss | hh:mmhh:mm:ss dd/mm/yyyy | hh:mm dd/mm/yyyydd/mm/yyyy | mm/yyyy
|
| 3 | Currency | Chỉ cho phép các ký tự số 0 → 9. Chỉ cho phép số dương. |
| 4 | QR Code | Cho phép các ký tự trong bảng mã ASCII: Chữ cái, Số, Các ký tự đặc biệt (@, #, $, %, &, *, +, -, …). |
| 5 | Bank Transfer Note |
Không cho phép truyền các ký tự đặc biệt trên bàn phím di động:@[]^_!"•#$%¥&'()*+,€-./:;{|<}=~>?
|
| 6 | BIN Code | Mã 6 số theo bảng BIN Code tiêu chuẩn của hệ thống. |
4. Hướng dẫn xử lý mã lỗi liên quan
Nếu trong quá trình truyền dữ liệu tham số thông qua API trả về lỗi, Quý khách vui lòng kiểm tra lại cấu trúc mã hóa URL hoặc đối chiếu với tài liệu xử lý mã lỗi kỹ thuật ZBS API để được hướng dẫn chi tiết.
