# Gửi tin Zalo ZNS - Deprecated

{% hint style="warning" %}

* **Chú ý**: Zalo đã đổi tên ZNS thành ZBS. API này đã ngừng phát triển và sẽ ngừng hỗ trợ sau 2026-08-31.

* Bạn nên chuyển sang dùng API mới [Gửi Zalo ZBS](https://apidocs.nhanh.vn/v3/zalo/zbs).
  {% endhint %}

* API này dùng để gửi tin nhắn Zalo ZNS. **Chú ý**:
  * Các hành động [cài đặt gửi Zalo trên nhanh.vn](https://nhanh.vn/setting/zalo/index) 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.
  * 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ự nối thêm < >
  * Zalo chỉ cho phép gửi tin ZBS trong khoảng từ 6-22h. Nếu mẫu tin là loại gửi OTP thì không bị giới hạn này, bạn có thể gửi được 24/7.

## Request

* Xem [common request params](https://apidocs.nhanh.vn/v3/readme#request-params).
* Xem [Postman sample](https://apidocs.nhanh.vn/v3/zalo/zns).

```curl
curl --location --globoff 'https://pos.open.nhanh.vn/v3.0/zalo/sendzns?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "zaloOaId": 365897,
    "znsTemplateId": 365,
    "mobile": "0966669999",
    "keywords": {
        "TU_KHOA_1": "Giá trị 1",
        "TU_KHOA_2": "Giá trị 2"
    }'
```

### Data

| Key           | Type                          | Description                                                                                                                                             |
| ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| znsTemplateId | int $$^{{\color{red}\*}}$$    | Các mẫu tin đã được Zalo duyệt sẽ có ZBS 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) |
| mobile        | string $$^{{\color{red}\*}}$$ | Số điện thoại cần gửi                                                                                                                                   |
| zaloOaId      | int $$^{{\color{red}\*}}$$    | ID Zalo OA                                                                                                                                              |
| keywords      | string $$^{{\color{red}\*}}$$ | Mẩng Từ khóa, giá trị {"KEYWORD\_1": "VALUE\_1", "KEYWORD\_2": "VALUE\_2"}                                                                              |

## Response

* Xem cấu trúc chung [tại đây](https://apidocs.nhanh.vn/v3/readme#response).

### Failed response

* Xem các mã lỗi chung [tại đây](https://apidocs.nhanh.vn/v3/readme#failed-response).
* Danh sách **errorCode** của riêng API này:

| 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 (UTC+7)                                                                                          |
| ERR\_ZNS\_REQUIRED\_KEYWORDS          | Từ khóa và giá trị không đúng định dạng hoặc null                                                                                                       |
| ERR\_ZNS\_KEYWORDS\_NOT\_MATCH        | <p>Từ khóa sai hoặc thừa với so từ khóa trong mẫu<br>ví dụ: { "invalidKeyword": \["KEYWORD\_1 is required", "KEYWORD\_2 not existed in template"] }</p> |
| 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ệ                                                                                                               |

### Successful response

```json
{
    "code": 1,
    "data": {
        "oaBalance": "(int) Số dư sau khi gửi",
        "quota": {
          "remainingQuota": "(int) Số tin nhắn còn được gửi trong ngày",
          "dailyQuota": "(int) Hạn mức tin nhắn được gửi trong ngày"
        }
    }
}
```