Send Zns

API

API dùng để gửi thông báo Zalo (ZNS - Zalo Notification Service).

POST $BASE_URL/api/vendor/v1/zalo/send-zns

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/send-zns

• Headers:

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

• Parameters:

  • API-KEY: Key License

• Body:

  • oa_id: ID của OA
  • phone: Số điện thoại người nhận
  • template_data: Các thuộc tính của mẫu tin mà bạn đã đăng ký với Zalo
  • template_id: ID của mẫu tin
  • tracking_id: Mã số đánh dấu lần gọi API của bạn, do bạn định nghĩa

• Cấu trúc request

Key	Type Value	Required	Description
API-KEY header	string	true	Key License
oa_id body	string	true	ID của OA
phone body	string	true	Số điện thoại người nhận
template_data body	object	false	Các thuộc tính của mẫu tin mà bạn đã đăng ký với Zalo Lưu ý: Cấu trúc template_data được quy định riêng ứng với từng mẫu tin
template_id body	number	true	ID của mẫu tin
tracking_id body	string	false	Không quan tâm.

• Ví dụ Request

curl --location 'https://cpaas.interits.com:8080/api/vendor/v1/zalo/send-zns' \
--header 'API-KEY: EImADVLv3tjE0ExErTkhTbKxBWeWwhY' \
--header 'Content-Type: application/json' \
--data '{
    "oa_id": "94900466102472689",
    "phone": "0961793135",
    "template_id": 419951,
    "template_data": {
        "ten_khach_hang": "Đông Dương 123",
        "mkh": "177",
        "day": "23/04/2025",
        "Ten_khach_hang": "Vũ Đình Đông Dương",
        "bill_id": "256989",
        "date": "21/5/2025"
    }
}'

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
id	number	ID tin nhắn trên hệ thống của ITS
shop_id	number	ID cửa hàng trên hệ thống của ITS
user_id	number	ID người gửi tin trên hệ thống của ITS
campaign_id	number	ID của chiến dịch
delivery_status	string	Unkown: Không xác định Received: Đã nhận Seen: Đã xem
delivery_time	string	Thời gian thiết bị của người dùng nhận được thông báo ZNS
error_code	number	Mã lỗi
error_message	string	Thông báo lỗi
fee_main	number	Phí chính
fee_token	number	Phí khởi tạo token
is_charged	boolean	True: Tin ZNS được tính phí False: Tin ZNS không được tính phí
journey_id	string	ID của journey
msg_id	string	ID của thông báo ZNS
type	string	template: ZNS thường journey: ZNS journey
status	string	Trạng thái Z: Mới tạo P: Enable N: Disable
template_data	object	Các thuộc tính của mẫu tin mà bạn đã đăng ký với Zalo Lưu ý: Cấu trúc template_data được quy định riêng ứng với từng mẫu tin
phone	string	Số điện thoại người nhận
sent_time	string	Thời gian gửi thông báo ZNS
template_id	number	ID của mẫu tin
timeout	number	Thời gian tối đa mà hệ thống xử lý yêu cầu
tracking_id	string	Mã số đánh dấu lần gọi API của bạn, do bạn định nghĩa.Bạn có thể dùng tracking_id để đối soát mà không phụ thuộc vào message_id của eTelecom cung cấp.
updated_at	string	Ngày cập nhật
created_at	string	Ngày tạo

• Ví dụ Response

{
    "code": 200,
    "data": {
        "charged": false,
        "campaign_id": "0",
        "created_at": "2025-04-23T10:37:55.148042Z",
        "delivery_status": "unknown",
        "delivery_time": "0001-01-01T00:00:00Z",
        "error_code": 0,
        "error_message": "Success",
        "fee_main": 200,
        "fee_token": 0,
        "feedback": [],
        "id": "1392669521135521747",
        "is_charged": false,
        "journey_id": "0",
        "msg_id": "28a3563f891a9141c80e",
        "note": "",
        "oa_id": "94900466102472689",
        "phone": "0961793135",
        "rate": 0,
        "sent_time": "2025-04-23T10:37:55.14Z",
        "shop_id": "1384546016245602051",
        "status": "P",
        "submit_time": "0001-01-01T00:00:00Z",
        "template_data": {
            "Ten_khach_hang": "Vũ Đình Đông Dương",
            "bill_id": "256989",
            "date": "21/5/2025",
            "day": "23/04/2025",
            "mkh": "177",
            "ten_khach_hang": "Đông Dương 123"
        },
        "template_id": 419951,
        "timeout": 7200,
        "tracking_id": "",
        "type": "template",
        "updated_at": "2025-04-23T10:37:55.238709Z",
        "user_id": "1384546011679036791",
        "zl_user_id": "0"
    },
    "referentId": "28a3563f891a9141c80e"
}

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ợ.