VI | EN
Nhắn Messenger
Dành cho developer

Gửi tin ZNS đến số điện thoại theo mẫu đã duyệt — API Zalo OA

Gửi ZNS · gọi qua Quantri360 bằng một API key cho chính tài khoản / tài sản bạn đã kết nối và ủy quyền — 360 lo việc ký request và làm mới phiên đăng nhập bạn đã cấp.

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: -108 số điện thoại không hợp lệ · -118 số chưa có tài khoản Zalo · -125 / -141 người dùng từ chối nhận tin · -132 mẫu chưa duyệt / không hoạt động · -1121 giá trị vượt maxLength (vd "name data breaks max length") · -1124 template_data sai định dạng (thường do trường giá) · -124 token 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ênVị tríKiểuMẫuMô tả
AuthorizationheaderheaderBearer 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_idquerystring1173478676788457425OA_ID của Zalo OA brand đã nối (GET /v1/platforms). Mỗi brand một OA — có thể bỏ.
dataquerystring (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ênVị tríKiểuBắt buộcMẫuMô tả
phonebodystringCó84901234567Số đ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_idbodystringCó445689Mã mẫu đang ENABLE.
template_databodyobjectCó{"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_idbodystringCó1234567Mã đố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_modebodystringKhông11 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ênKiểuMẫuMô tả
errorint00 = gửi thành công; khác 0 là mã lỗi (HTTP vẫn 200).
messagestringSuccessMô tả lỗi.
dataobjectChỉ có khi thành công.
msg_idstringe94d839c565a15034c4cMã tin — tra trạng thái bằng /zns/message/status.
sent_timestring1793263788176Thời điểm gửi, Unix mili giây (chuỗi).
sending_modestring1
quotaobjectHạn mức sau khi gửi.
dailyQuotastring5000
remainingQuotastring4988

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

  1. Đăng ký tài khoản Partner
  2. Mở loại dữ liệu thuộc nhóm ZNS (Zalo Notification Service) ở trang nền tảng
  3. Tạo API key (tick kênh Zalo OA)
  4. Gọi theo ví dụ ở trên