# Gửi tin Zalo ZNS
* API này dùng để gửi tin nhắn Zalo ZNS.
* Chú ý: Các hành động cài đặt gửi ZNS trên nhanh.vn sẽ do Nhanh.vn tự động gửi, bạn chỉ nên dùng API này cho các hành động phát sinh riêng từ hệ thống của bên bạn.
## Request
* URI: /api/zalo/sendzns. Xem các [common request params](https://apidocs.nhanh.vn/v2/readme#request-params).
* Các key của mảng **data array** dùng để tạo **data** json string:
| Key | Type | Description |
| ------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| zaloOaId | int $$^{{\color{red}\*}}$$ | Zalo OA Id |
| znsTemplateId | int $$^{{\color{red}\*}}$$ | Các mẫu tin đã được Zalo duyệt sẽ có ZNS template Id, xem và tạo mới mẫu tin tại [danh sách template](https://nhanh.vn/setting/zalo/index#zns-templates). **Chú ý**: bạn cần copy cột ZNS template ID chứ không phải cột ID, nếu bạn copy sai, API sẽ báo lỗi ERR\_ZNS\_INVALID\_TEMPLATE |
| mobile | string $$^{{\color{red}\*}}$$ | Số điện thoại cần gửi |
| keywords | array $$^{{\color{red}\*}}$$ | Từ khóa, giá trị |
* **keywords**: mảng các giá trị thay thế các từ khóa trong mẫu tin Zalo ZNS. **Chú ý**:
* Khi cài hành động gửi tin theo các sự kiện trên Nhanh (Thêm hóa đơn bán lẻ, Thêm đơn hàng...) thì bạn mới cần dùng các từ khóa có sẵn của Nhanh.vn, còn nếu chỉ muốn gửi qua API, thì khi tạo mẫu tin, bạn có thể tạo từ khóa bất kì, đợi Zalo duyệt xong, thì bạn có thể lấy được znsTemplateId để gửi API.
* Khi Zalo duyệt mẫu tin, các từ khóa thường có dạng **<\_TEN\_KHACH\_HANG\_>** nhưng gửi qua API cần bỏ qua 2 dấu < > chỉ gửi sang **\_TEN\_KHACH\_HANG\_**, Zalo sẽ tự xử lý nối thêm < >
```javascript
[
'_KEY_1_' : 'value1',
'_KEY_2_' : 'value2',
...
]
```
### Sample request
```curl
curl --location 'https://pos.open.nhanh.vn/api/zalo/sendzns' \
--form 'accessToken="your_accessToken"' \
--form 'businessId="your_businessId"' \
--form 'appId="your_appId"' \
--form 'version="2.0"' \
--form 'data="{\"znsTemplateId\":\"TEMPLATE_ID\",\"mobile\":\"0988999999\",\"zaloOaId\":\"OA_ID\",\"keywords\":{\"TEN_KHACH_HANG\":\"Nguy\\u1ec5n V\\u0103n \\u0110\\u1ee9c\",\"ID_DON_HANG\":\"19837512\",\"TONG_TIEN\":\"190000\"}}"'
```
## Response
* JSON decode the response to get the structure:
| Key | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| code | int | 1 = success or 0 = failed |
| errorCode | string | Xem bảng mã lỗi bên dưới |
| messages | array | Nội dung cảnh báo hoặc chi tiết lỗi |
| data | object | Khi code = 1 API response sẽ trả về:
oaBalance: Số dư tài khoản sau khi gửi tin
remainingQuota: Số tin nhắn còn được gửi trong ngày
dailyQuota: Hạn mức tin nhắn được gửi trong ngày
{ "oaBalance": 10000000, "quota": { "remainingQuota": 4995, "dailyQuota": 5000 } }
|
### errorCode
* Danh sách mã lỗi khi code = 0
| errorCode | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ERR\_ZNS\_OA\_404 | Doanh nghiệp chưa kết nối OA |
| ERR\_ZNS\_INVALID\_OA | Zalo OA Id không hợp lệ |
| ERR\_ZNS\_EXCEEDED\_LIMIT\_IN\_DAY | Vượt quá hạn mức gửi tin trong ngày |
| ERR\_ZNS\_OA\_NOT\_ENOUGH\_BALANCE | Số dư tài khoản không đủ |
| ERR\_ZNS\_INVALID\_PHONE\_NUMBER | Số điện thoại gửi đi không hợp lệ |
| ERR\_ZNS\_ZALO\_ACCOUNT\_NOT\_EXISTED | Số điện thoại không có tài khoản Zalo |
| ERR\_ZNS\_INVALID\_TEMPLATE | ZNS template Id không hợp lệ |
| ERR\_ZNS\_PROHIBITED\_TIMEFRAME | Tin nhắn chỉ được gửi trong khoảng thời gian từ 06-22h |
| ERR\_ZNS\_REQUIRED\_KEYWORDS | Từ khóa và giá trị không đúng định dạng hoặc null |
| ERR\_ZNS\_KEYWORDS\_NOT\_MATCH | Từ khóa sai hoặc thừa với so từ khóa trong mẫu
ví dụ: { "invalidKeyword": \["KEYWORD\_1 is required", "KEYWORD\_2 not existed in template"] }
|
| ERR\_ZNS\_INVALID\_KEYWORD\_VALUES | Giá trị từ khóa không hợp lệ |
| ERR\_ZNS\_CODE\_1121 | Dữ liệu keyword vượt quá độ dài tối đa |
| ERR\_ZNS\_CODE\_1123 | Không thể tạo mã QR |
| ERR\_ZNS\_CODE\_1124 | Dữ liệu keyword có định dạng không hợp lệ |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://apidocs.nhanh.vn/v2/zalo/zns.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.