Tổng quan plugin zalo sandbox
Back to zalo sandboxZalo Sandbox là một plugin dành cho EzyPlatform, cung cấp môi trường mô phỏng một phần Zalo Official Account (OA) OpenAPI ngay trên hệ thống phát triển. Thay vì gửi yêu cầu đến hạ tầng Zalo thật, ứng dụng có thể trỏ sang sandbox để thử luồng cấp quyền, lấy access token, gửi tin nhắn, tải ảnh, truy vấn người dùng và nhận webhook.
Plugin phù hợp cho phát triển cục bộ, kiểm thử tích hợp và trình diễn những luồng liên quan đến Zalo OA mà không phụ thuộc vào tài khoản OA thật. Dữ liệu thử nghiệm được dùng chung với hệ thống người dùng, media và chat của EzyPlatform, nhờ đó lập trình viên có thể quan sát kết quả ngay trong trang quản trị.
Kiến trúc tổng quát
Dự án được chia thành ba thành phần có trách nhiệm rõ ràng:
- SDK dùng chung định nghĩa cấu hình, loại tin nhắn, tên sự kiện webhook, mã lỗi và tiện ích xác minh PKCE.
- Plugin web cung cấp các HTTP API mô phỏng Zalo OA cho ứng dụng cần tích hợp.
- Plugin admin cung cấp giao diện cấu hình, quản lý người dùng OA, xem tin nhắn và chủ động phát webhook thử nghiệm.
Plugin web và plugin admin cùng đọc, ghi một nguồn cấu hình của EzyPlatform. Cách tổ chức này giúp giá trị như App ID, secret key, access token, thời hạn token và danh sách URL được quản lý ở một nơi nhưng sử dụng nhất quán ở cả hai runtime.
Khi plugin admin khởi động, hệ thống bảo đảm tồn tại một vai trò dành cho người dùng OA sandbox và một kênh chat loại OA đang hoạt động. Mã định danh của kênh được lưu vào cấu hình để plugin web đưa các tin nhắn mô phỏng vào đúng nơi.
flowchart LR
A[Ứng dụng tích hợp] -->|OAuth và OA API| W[Plugin web]
W --> S[Cấu hình dùng chung]
W --> U[Người dùng EzyPlatform]
W --> M[Kho media]
W --> C[Kênh chat OA]
Q[Quản trị viên] --> P[Plugin admin]
P --> S
P --> U
P --> C
P -->|Webhook có chữ ký| H[Webhook của ứng dụng]
Các khả năng chính
Mô phỏng OAuth và access token
Sandbox triển khai luồng cấp quyền theo phong cách Zalo OA v4, có sử dụng PKCE:
- Ứng dụng mở endpoint cấp quyền với App ID, callback URL và
code_challenge. - Sandbox kiểm tra App ID, đối chiếu callback URL với danh sách cho phép và lưu challenge.
- Trình duyệt được chuyển về callback URL cùng authorization code.
- Ứng dụng đổi code lấy token bằng secret key và
code_verifiertương ứng. - Sandbox trả về access token, refresh token và thời gian hiệu lực đã cấu hình.
Luồng refresh token cũng được hỗ trợ. Khi yêu cầu dùng grant type
refresh_token, sandbox kiểm tra refresh token và application secret trước khi trả kết quả.
Access token được kiểm tra ở các API người dùng, tin nhắn và media. Ngoài việc so sánh giá trị token, hệ thống còn kiểm tra mốc hết hạn được ghi lại tại thời điểm cấp token. Token sai hoặc hết hạn được chuyển thành response mang mã lỗi theo định dạng OA thay vì làm lộ exception nội bộ.
Token và authorization code có thể được sinh tự động khi chưa có giá trị. Tuy nhiên, sandbox hiện tái sử dụng các giá trị đã lưu; việc cấp token chủ yếu cập nhật thời điểm hết hạn chứ không xoay vòng token sau mỗi lần gọi.
Gửi tin nhắn OA
API gửi tin chăm sóc khách hàng nhận người nhận và nội dung văn bản, đồng thời chấp nhận attachment trong payload. Sandbox kiểm tra access token, cấu trúc tin nhắn và sự tồn tại của người dùng trước khi ghi một message vào kênh chat OA.
Tin nhắn được lưu dưới dạng JSON và được phân loại thành tin văn bản hoặc văn bản kèm attachment. Nếu người nhận không tồn tại, response mô phỏng lỗi người dùng chưa theo dõi OA. Quản trị viên có thể cấu hình trước một mã lỗi Zalo OA để buộc request hợp lệ trả về thất bại, rất hữu ích khi kiểm thử retry, cảnh báo và xử lý lỗi ở phía ứng dụng.
Sandbox còn hỗ trợ tin nhắn template với ba dữ liệu chính: số điện thoại, template ID và tập tham số. Người dùng được tìm theo số điện thoại; số bắt đầu bằng mã quốc gia
84 cũng được thử chuyển sang định dạng nội địa. Tin nhắn hợp lệ được lưu vào cùng kênh chat dưới loại template. Mã lỗi giả lập cho tin nhắn thường và tin nhắn template được cấu hình độc lập.Người dùng OA
Người dùng OA sandbox không nằm trong một kho dữ liệu tách biệt. Họ là người dùng EzyPlatform được gán vai trò OA sandbox. API danh sách chỉ truy vấn những người có vai trò này và hỗ trợ phân trang bằng
offset cùng count.API chi tiết trả về định danh UUID, tên hiển thị, bí danh và URL ảnh đại diện. Cách ánh xạ này cho phép tận dụng sẵn hồ sơ người dùng và kho media của nền tảng trong các kịch bản thử nghiệm.
Tải ảnh
Endpoint upload nhận multipart file, xác thực access token và áp dụng quy tắc kiểm tra media của EzyPlatform. File hợp lệ được lưu vào kho media ở chế độ không công khai; response trả về
attachment_id để đưa vào payload tin nhắn tiếp theo.Chức năng này phụ thuộc vào việc upload tài nguyên đã được bật trong web runtime. Nếu bộ tải file chưa được cấu hình, endpoint không thể lưu ảnh.
Phát webhook thử nghiệm
Từ trang quản trị, người dùng có quyền phù hợp có thể chọn người nhận, loại sự kiện, nội dung và URL đích để gửi webhook. Payload gồm tên sự kiện, timestamp, thông tin sender và message.
Trước khi gửi, sandbox tạo chữ ký SHA-256 từ App ID, JSON payload, timestamp và webhook secret, sau đó đặt chữ ký vào header
X-ZEvent-Signature với tiền tố mac=. Phía nhận có thể dùng đúng cơ chế xác minh dự kiến trong tích hợp thực tế.Các nhóm sự kiện được mô hình hóa gồm tin nhắn từ OA, tin nhắn từ người dùng, follow, unfollow, tham gia nhóm và rời nhóm. Danh sách webhook URL có thể được cấu hình để thao tác thử nghiệm thuận tiện hơn; URL đích vẫn được chọn khi phát từng webhook.
Các API được mô phỏng
Phiên bản hiện tại tập trung vào một tập endpoint thường dùng:
| Nhóm | Endpoint | Mục đích |
|---|---|---|
| Xác thực | GET /v4/oa/permission | Cấp authorization code và chuyển hướng về callback |
| Xác thực | POST /v4/oa/access_token | Đổi code hoặc refresh token lấy bộ token OA |
| Tin nhắn | POST /v3.0/oa/message/cs | Gửi tin chăm sóc khách hàng |
| Tin nhắn | POST /message/template | Gửi tin nhắn template theo số điện thoại |
| Người dùng | GET /v3.0/oa/user/getlist | Lấy danh sách người dùng OA theo offset/count |
| Người dùng | GET /v3.0/oa/user/detail | Lấy hồ sơ một người dùng OA |
| Media | POST /v2.0/oa/upload/image | Tải ảnh và nhận attachment ID |
Các API yêu cầu token chấp nhận access token qua những cách đặt tên header/tham số phổ biến như
access_token, access-token hoặc accessToken. Plugin cũng cung cấp trang Swagger và tài liệu OpenAPI để khám phá request/response của các endpoint hiện có.Quản trị và cấu hình
Khu vực admin được bảo vệ bằng cơ chế đăng nhập và feature permission của EzyPlatform. Quyền quản lý cấu hình được tách khỏi quyền quản lý OA, giúp giới hạn người có thể đọc hoặc thay đổi secret và token.
Trang cấu hình quản lý các nhóm giá trị sau:
- thông tin ứng dụng: App ID, application secret và webhook secret;
- access token, refresh token, thời gian hiệu lực và thời điểm hết hạn;
- PKCE code challenge và danh sách callback URL được phép;
- danh sách webhook URL phục vụ thử nghiệm;
- mã lỗi cần giả lập cho từng loại gửi tin.
Các trường bắt buộc như App ID, application secret, token, thời gian hiệu lực và callback URL được xác thực trước khi lưu. Ngoài trang cấu hình, admin còn có màn hình lọc người dùng OA, xem chi tiết người dùng, xem lịch sử tin nhắn trong kênh OA và gửi webhook thủ công.
Một luồng kiểm thử điển hình
Một ứng dụng có thể tích hợp với sandbox theo quy trình sau:
- Cấu hình App ID, secret, token lifetime, callback URL và webhook URL trong admin.
- Tạo hoặc chọn người dùng EzyPlatform, sau đó gán vai trò OA sandbox.
- Thực hiện luồng permission và đổi authorization code lấy token.
- Dùng access token để lấy danh sách hoặc chi tiết người dùng.
- Gửi tin OA hoặc template và kiểm tra message xuất hiện trong trang quản trị.
- Từ admin, phát webhook về ứng dụng và xác minh chữ ký nhận được.
- Chọn một mã lỗi giả lập rồi gửi lại request để kiểm tra nhánh thất bại.
Quy trình này bao phủ cả hai chiều giao tiếp: ứng dụng gọi OA API và OA gửi sự kiện ngược về webhook của ứng dụng.
Giới hạn cần lưu ý
Zalo Sandbox mô phỏng có chọn lọc hành vi cần cho phát triển, không phải bản sao đầy đủ của nền tảng Zalo OA. Một số điểm cần lưu ý:
- Chỉ các endpoint nêu trên được triển khai; các API OA khác không tự động được hỗ trợ.
- Dữ liệu người dùng, tin nhắn và media tuân theo mô hình của EzyPlatform, không phải hạ tầng lưu trữ của Zalo.
- Token, authorization code và refresh token là dữ liệu cấu hình cục bộ; sandbox không liên hệ máy chủ Zalo để xác minh chúng.
- Response lỗi được mô phỏng theo một tập mã lỗi định sẵn, không tái tạo mọi quy tắc nghiệp vụ như rate limit, cửa sổ nhắn tin hay trạng thái OA. Các lỗi này chỉ xuất hiện khi validation cục bộ thất bại hoặc khi quản trị viên cấu hình kết quả giả lập.
- Attachment trong tin nhắn được lưu như một phần JSON của message; sandbox không thực hiện toàn bộ vòng đời xử lý attachment như dịch vụ Zalo thật.
- Việc phát webhook thực hiện HTTP request đến URL được chọn. Vì vậy môi trường chạy sandbox phải có khả năng kết nối đến webhook đích.
Kết luận
Zalo Sandbox tạo một ranh giới thử nghiệm thực dụng giữa ứng dụng và Zalo OA: đủ gần về endpoint, payload, token, mã lỗi và chữ ký webhook để kiểm tra tích hợp, nhưng vẫn hoàn toàn nằm trong môi trường EzyPlatform. Sự kết hợp giữa API mô phỏng, dữ liệu user/chat/media dùng chung và công cụ quản trị giúp đội phát triển kiểm thử nhanh cả luồng thành công lẫn thất bại mà không cần thao tác trên OA thật.