Gửi ZNS
POST/zns/message/templateGọi qua 360: POST https://partner.quantri360.com/v1/zalo/zns/message/template
Endpoint ghi — thay đổi dữ liệu trên Zalo OA. Key phải được tạo với tick "Cho phép gọi API ghi", nếu không sẽ nhận 403 write_not_allowed. Mỗi lần gọi được ghi nhật ký.
Mô tả API
GỬI một tin ZNS tới số điện thoại theo mẫu đã duyệt (xác nhận đơn, OTP, CSKH…). Mỗi tin thành công bị tính phí vào tài khoản ZCA / ZBS của OA theo đơn giá của mẫu.
- Là API GHI — gửi tin thật tới khách và bị TÍNH PHÍ trên Zalo; key cần quyền ghi. Thử nghiệm bằng chính số của bạn.
- Lỗi hay gặp:
-108số điện thoại không hợp lệ ·-118số chưa có tài khoản Zalo ·-125/-141người dùng từ chối nhận tin ·-132mẫu chưa duyệt / không hoạt động ·-1121giá trị vượt maxLength (vd "name data breaks max length") ·-1124template_data sai định dạng (thường do trường giá) ·-124token hết hạn (360 tự làm mới). - Các lỗi -108, -118, -125, -141, -132, -1124 là lỗi cố định — gửi lại không có tác dụng; chỉ thử lại với lỗi tạm thời.
- Gửi hàng loạt: kiểm /zns/message/quota trước, giữ tracking_id duy nhất cho mỗi tin để không gửi trùng.
Request
Địa chỉ
POST https://partner.quantri360.com/v1/zalo/zns/message/template
Xác thực & gian hàng
| Tên | Vị trí | Kiểu | Mẫu | Mô tả |
|---|---|---|---|---|
| Authorization | header | header | Bearer q360_live_ab12cd34_… | Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand. |
| platform_shop_id | query | string | 1173478676788457425 | OA_ID của Zalo OA brand đã nối (GET /v1/platforms). Mỗi brand một OA — có thể bỏ. |
| data | query | string (JSON) | {"offset":0,"count":10} | Nhiều API GET của Zalo nhận tham số gói trong data là chuỗi JSON — gửi nguyên như tài liệu Zalo. |
Tham số request
| Tên | Vị trí | Kiểu | Bắt buộc | Mẫu | Mô tả |
|---|---|---|---|---|---|
| phone | body | string | Có | 84901234567 | Số điện thoại người nhận dạng quốc tế: bỏ số 0 đầu, thêm 84 (0901234567 → 84901234567). Số phải có tài khoản Zalo. |
| template_id | body | string | Có | 445689 | Mã mẫu đang ENABLE. |
| template_data | body | object | Có | {"name":"Nguyễn Văn A","order_code":"1234567","price":"450000","date":"29/10/2026"} | Giá trị cho TỪNG tham số trong listParams của mẫu (xem /zns/template/info/v2); đúng tên, kiểu và độ dài. |
| tracking_id | body | string | Có | 1234567 | Mã đối soát do bạn đặt (vd mã đơn), ≤ 48 ký tự, không ký tự đặc biệt — dùng đối soát độc lập với msg_id. |
| sending_mode | body | string | Không | 1 | 1 gửi thường (mặc định) · 3 gửi vượt hạn mức (chỉ OA được Zalo cho phép). |
Ví dụ request
curl -s -X POST "https://partner.quantri360.com/v1/zalo/zns/message/template" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"84901234567","template_id":"445689","template_data":{"name":"Nguyễn Văn A","order_code":"1234567","price":"450000","date":"29/10/2026"},"tracking_id":"1234567"}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/zalo/zns/message/template",
params={},
json={
"phone": "84901234567",
"template_id": "445689",
"template_data": {
"name": "Nguyễn Văn A",
"order_code": "1234567",
"price": "450000",
"date": "29/10/2026"
},
"tracking_id": "1234567"
},
headers={"Authorization": f"Bearer {KEY}"},
timeout=60,
)
print(r.status_code)
print(r.json())Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/zalo/zns/message/template');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({"phone":"84901234567","template_id":"445689","template_data":{"name":"Nguyễn Văn A","order_code":"1234567","price":"450000","date":"29/10/2026"},"tracking_id":"1234567"}),
});
console.log(r.status, await r.json());PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/zalo/zns/message/template' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"phone":"84901234567","template_id":"445689","template_data":{"name":"Nguyễn Văn A","order_code":"1234567","price":"450000","date":"29/10/2026"},"tracking_id":"1234567"}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;Response
Tham số phản hồi (nguyên của Zalo OA)
| Tên | Kiểu | Mẫu | Mô tả |
|---|---|---|---|
| error | int | 0 | 0 = gửi thành công; khác 0 là mã lỗi (HTTP vẫn 200). |
| message | string | Success | Mô tả lỗi. |
| data | object | Chỉ có khi thành công. | |
| msg_id | string | e94d839c565a15034c4c | Mã tin — tra trạng thái bằng /zns/message/status. |
| sent_time | string | 1793263788176 | Thời điểm gửi, Unix mili giây (chuỗi). |
| sending_mode | string | 1 | |
| quota | object | Hạn mức sau khi gửi. | |
| dailyQuota | string | 5000 | |
| remainingQuota | string | 4988 |
Mẫu phản hồi
{
"error": 0,
"message": "Success",
"data": {
"sent_time": "1793263788176",
"sending_mode": "1",
"quota": {
"remainingQuota": "4988",
"dailyQuota": "5000"
},
"msg_id": "e94d839c565a15034c4c"
}
}
Bắt đầu dùng
- Đăng ký tài khoản Partner
- Mở loại dữ liệu thuộc nhóm ZNS (Zalo Notification Service) ở trang nền tảng
- Tạo API key (tick kênh Zalo OA)
- Gọi theo ví dụ ở trên