List Templates

API

API dùng để lấy danh sách các mẫu (template) đã có từ hệ thống Zalo.

POST $BASE_URL/api/vendor/v1/zalo/list-templates

Lưu ý

• API-KEY: là duy nhất
• Các bước lấy API-KEY:
  1. Doanh nghiệp đăng nhập
  2. Di chuyển đến trang Key (hoặc License)
  3. Lấy 1 API-KEY thỏa mãn điều kiện hoạt động

Thông tin Request

• Method: POST

• URL: /api/vendor/v1/zalo/list-templates

• Headers:

  • accept: */*
  • Content-Type: application/json
  • API-KEY: {API_KEY}

• Parameters:

  • API-KEY: Key License

• Body:

  • filter: (Mô tả dữ liệu filter)
  • paging: (Mô tả dữ liệu paging)

• Cấu trúc request

Key	Type Value	Required	Description
API-KEY header	string	true	Key License
filter body	object	false	date_from với kiểu dữ liệu là string: Ngày bắt đầu (VD: "2024-03-17T03:21:52.408936Z") date_to với kiểu dữ liệu là string: Ngày kết thúc (VD: "2025-12-04T04:37:24.687187Z") oa_id với kiểu dữ liệu là string: ID của OA template_id với kiểu dữ liệu là number: ID của mẫu tin template_name với kiểu dữ liệu là string: Tên mẫu tin type với kiểu dữ liệu là enum: unknown text otp table rating

• Ví dụ Request

curl --location 'https://cpaas.interits.com:8080/api/vendor/v1/zalo/list-templates' \
--header 'API-KEY: EImADVLv3tjE0ExErTkhTbKxBWeWwhY' \
--header 'Content-Type: application/json' \
--data '{
  "filter": {
    "date_from": "2025-03-28T03:16:58.682536Z",
    "date_to": "2026-03-28T03:16:58.682536Z",
    "oa_id": "94900466102472689",
    "template_id": 419951,
    "template_name": "Đánh giá chất lượng dịch vụ",
    "type": "rating"
  }
}'

Thông tin Response

Mô tả: Mô tả dữ liệu trả về dùng làm gì

• Cấu trúc data của response

Key	Type	Description
templates	array	apply_template_quota với kiểu dữ liệu là boolean: True False created_at với kiểu dữ liệu là string: Thời gian tạo preview_url với kiểu dữ liệu là string: Url để em trước template price với kiểu dữ liệu là number: Đơn giá của mẫu tin template_daily_quota với kiểu dữ liệu là number: Số lượng tin ZNS có thể gửi trong 1 ngày template_id với kiểu dữ liệu là number: ID của mẫu tin template_name với kiểu dữ liệu là string: Tên của mẫu tin template_params với kiểu dữ liệu là string: Các giá trị params của template template_quality với kiểu dữ liệu là string: unknown: Không xác định UNDEFINED: Mức độ chất lượng OA chưa được xác định (trường hợp OA không gửi thông báo ZNS nào trong khung thời gian đánh giá) LOW: Mức độ chất lượng kém MEDIUM: Mức độ chất lượng trung bình HIGH: Mức độ chất lượng cao template_remaining_quota với kiểu dữ liệu là number: Số lượng tin ZNS có thể gửi còn lại trong 1 ngày template_status với kiểu dữ liệu là string: Trạng thái mẫu tin: Unkown: Không xác định PENDING_REVIEW: Đang duyệt DISABLE: Bị khóa ENABLE: Đã duyệt REJECT: Bị từ chối template_tag với kiểu dữ liệu là string: Cấp độ mẫu tin: Unkown: Không xác định OTP: Tin OTP (tag 0) IN_TRANSACTION: Xác nhận/Cập nhật thông tin giao dịch (Tag 1) POST_TRANSACTION: Hỗ trợ dịch vụ liên quan sau giao dịch (Tag 2) ACCOUNT_UPDATE: Cập nhật thông tin tài khoản (Tag 3) GENERAL_UPDATE: Thay đổi thông tin dịch vụ (Tag 4) FOLLOW_UP: Thông báo ưu đãi đến khách hàng cũ (Tag 5) timeout với kiểu dữ liệu là number: Thời gian tính phí của mẫu tin type với kiểu dữ liệu là number: Loại template updated_at với kiểu dữ liệu là string: Thời gian cập nhật
paging	object	Bỏ qua, không quan tâm

• Ví dụ Response

{
    "code": 200,
    "data": {
        "paging": {
            "after": ".",
            "before": "",
            "limit": 100,
            "next": "AAAAAAAGaG8BAAYxXoDZaKj7",
            "prev": "AAAAAAAGaG8BAAYxXoDZaKj7",
            "sort": ""
        },
        "templates": [
            {
                "apply_template_quota": false,
                "created_at": "2025-03-28T03:16:58.682536Z",
                "preview_url": "https://account.zalo.cloud/znspreview/Wp5ZAYcfR6_A3HUCJPoCPQ==",
                "price": 200,
                "template_daily_quota": 0,
                "template_id": 419951,
                "template_name": "Đánh giá chất lượng dịch vụ",
                "template_params": [
                    {
                        "accept_null": false,
                        "max_length": 50,
                        "min_length": 0,
                        "name": "Ten_khach_hang",
                        "require": true,
                        "type": "STRING"
                    },
                    {
                        "accept_null": false,
                        "max_length": 30,
                        "min_length": 0,
                        "name": "bill_id",
                        "require": true,
                        "type": "STRING"
                    },
                    {
                        "accept_null": false,
                        "max_length": 30,
                        "min_length": 0,
                        "name": "date",
                        "require": true,
                        "type": "STRING"
                    }
                ],
                "template_quality": "UNDEFINED",
                "template_remaining_quota": 0,
                "template_status": "ENABLE",
                "template_tag": "unknown",
                "timeout": 7200,
                "type": "rating",
                "is_journey": false,
                "token_type": "unknown",
                "updated_at": "2025-04-01T03:47:11.954222Z"
            }
        ]
    }
}

Bảng Status Response

Status Code	Status Message	Description
200	OK	Yêu cầu đã thành công và server trả về kết quả.
201	Created	Yêu cầu đã thành công và server đã tạo ra tài nguyên mới.
204	No Content	Yêu cầu đã thành công nhưng không có nội dung trả về.
400	Bad Request	Server không thể hiểu yêu cầu do cú pháp không hợp lệ message: Success: Gửi thành công Unknown error: Xảy ra lỗi không xác định, vui lòng thử lại sau Appllication invalid: Ứng dụng gửi ZNS không hợp lệ Application not existed: Ứng dụng gửi ZNS không tồn tại Application not activated: Ứng dụng chưa được kích hoạt App secret key invalid: Secret key của ứng dụng không hợp lệ Application not link to any OA: Ứng dụng gửi ZNS chưa đươc liên kết với OA nào Method unsupported: Phương thức không được hỗ trợ Message ID invalid: ID thông báo không hợp lệ Phone number invalid: Số điện thoại không hợp lệ Template ID invalid: ID mẫu ZNS không hợp lệ Can not edit this type of template: Template không có trạng thái Reject hoặc Template được tạo từ Admin tool Zalo version unsupported: Phiên bản Zalo app không được hỗ trợ. Người dùng cần cập nhật phiên bản mới nhất Template data empty: Mẫu ZNS không có dữ liệu template data type is not define: Dữ liệu mẫu ZNS không hợp lệ parameter_name data breaks max length: Dữ liệu tham số vượt quá giới hạn ký tự template data is missing a parameter parameter_name: Dữ liệu mẫu ZNS thiếu tham số QR code cannot be generated: Không thể tạo QR code, vui lòng kiểm tra lại parameter_name has invalid format: Dữ liệu tham số không đúng format Button invalid: Button không hợp lệ Invalid button content format: Đường dẫn liên kết không đúng định dạng User is inactive, or reject the message, or using an outdated Zalo version, or other internal errors: Người dùng không nhận được ZNS vì các lý do: Trạng thái tài khoản, Tùy chọn nhận ZNS, Sử dụng Zalo phiên bản cũ, hoặc các lỗi nội bộ khác Out of quota: Tài khoản ZNS không đủ số dư Text invalid: Nội dung tham số không hợp lệ OA or App does not have permission to access this template: OA hoặc ứng dụng gửi ZNS chưa được cấp quyền sử dụng mẫu ZNS này Zalo account not existed: Tài khoản Zalo không tồn tại hoặc đã bị vô hiệu hoá Account can not receive message: Tài khoản không thể nhận ZNS OA does not have permission to use this feature: OA chưa được cấp quyền sử dụng tính năng này OA does not have permission to create this type of template: OA chưa có quyền tạo template tag 3 OA does not have permission to use this resource: OA không có quyền sử dụng media resources (image/logo) Body data empty: Mẫu ZNS không có nội dung Body format invalid: Body request không đúng định dạng JSON RSA message decoded failed: Giải mã nội dung thông báo RSA thất bại Access token invalid: Mã truy cập không hợp lệ Invalid appsecret_proof provided in the API argument: appsecret_proof không hợp lệ Official Account ID invalid: ID Official Account không hợp lệ Out of quota (development mode): Ví (development mode) không đủ số dư Test template messages can only be sent to admin: Template test chỉ có thể được gửi cho quản trị viên Encoding key not existed: Mã encoding key không tồn tại RSA key cannot be generated: Không thể tạo RSA key, vui lòng thử lại sau Maximum character limit exceeded: Nội dung mẫu ZNS vượt quá giới hạn kí tự ZNS template not approved: Mẫu ZNS chưa được phê duyệt Parameter invalid: Tham số không hợp lệ This template cannot be sent at night (10PM-6AM): Mẫu ZNS này không được phép gửi vào ban đêm (từ 22h-6h) User has not responded to opt-in inquiry: Người dùng chưa phản hồi gợi ý nhận ZNS từ OA No permission to send ZNS (not verified, in free subscription plan): OA chưa có quyền gửi ZNS (chưa được xác thực, đang sử dụng gói miễn phí) OA has no permission to send ZNS (The system blocks due to violation detection): OA không có quyền gửi ZNS (Hệ thống chặn do phát hiện vi phạm) ZCA association required: Cần kết nối với ZCA để sử dụng tính năng này ZCA charge failure: Thanh toán ZCA thất bại (ví không đủ số dư, ...) App does not have permission to access this feature: Ứng dụng gửi ZNS chưa có quyền sử dụng tính năng này Extension does not have permission to access ZCA of OA: OA chưa cấp quyền cho Extension về quyền sử dụng ZCA của OA User refused to receive this type of ZNS: Người dùng từ chối nhận loại ZNS này User not eligible to receive this ZNS type based on current delivery policy: Người dùng không đủ điều kiện để nhận loại ZNS này dựa trên chính sách gửi tin hiện tại User refused to receive ZNS: Người dùng từ chối nhận ZNS từ Official Account RSA key not exist: RSA key không tồn tại, vui lòng gọi API tạo RSA key RSA key already existed: RSA key đã tồn tại, vui lòng gọi API lấy RSA key ZNS daily quota exceeded: OA đã vượt giới hạn gửi ZNS trong ngày OA exceeded the monthly promotion quota: OA request gửi vượt ngưỡng monthly promotion quota OA does not have permission to send this type of ZNS: OA không được phép gửi loại nội dung ZNS này Template disabled due to low quality: Mẫu ZNS này đã bị vô hiệu hoá do chất lượng gửi thấp Tempalate daily quota exceeded: Mẫu ZNS đã vượt giới hạn gửi trong ngày OA exceeded the limit of sending ZNS follow-ups to this user for the month.: OA đã vượt giới hạn gửi tin ZNS hậu mãi cho người dùng này trong tháng. ZNS journey token missing: Không tìm thấy ZNS journey token ZNS journey token invalid: ZNS journey token không hợp lệ ZNS journey token type invalid: ZNS journey token type không tương thích với template ZNS journey token expired: ZNS journey token đã hết hạn Not an E2EE template: Không phải mẫu ZNS E2EE Get E2EE key failed: Lấy E2EE key thất bại Data is invalid or detail_reason: Dữ liệu truyền vào sai quy định The uploaded file exceeds the allowed size: Dung lượng file vượt qua dung lượng cho phép The uploaded file does not meet the required format specifications: Định dạng file upload không được cho phép Out of quota: Số lượng tạo/edit template hoặc upload attachment vượt quá daily quota sending_mode has invalid value: sending_mode truyền sai giá trị cho phép Can not send this type of ZNS on this endpoint: Chế độ Gửi vượt hạn mức (sending_mode = 3) không hỗ trợ để gửi tin tag 1, 2
401	Unauthorized	Cần xác thực để truy cập tài nguyên.
403	Forbidden	Server từ chối thực hiện yêu cầu, mặc dù người dùng đã xác thực.
404	Not Found	Tài nguyên yêu cầu không tồn tại trên server.
405	Method Not Allowed	Phương thức HTTP không được phép cho tài nguyên yêu cầu.
500	Internal Server Error	Lỗi không xác định trong server.
502	Bad Gateway	Server là một gateway hoặc proxy và nhận được phản hồi không hợp lệ từ server khác.
503	Service Unavailable	Server không thể xử lý yêu cầu do quá tải hoặc bảo trì.
504	Gateway Timeout	Server không nhận được phản hồi kịp thời từ server phụ trợ.