Dành cho lập trình viên

Tài liệu API

Tài liệu tham chiếu đầy đủ của API nằm tại https://docs.webzone.vn/.

API làm được gì

• Tạo hồ sơ từ hệ thống của bạn, đọc danh sách và chi tiết hồ sơ, cập nhật hồ sơ.
• Gửi và đọc tin nhắn trong một hồ sơ.
• Đọc luồng sự kiện để bắt kịp những gì đã xảy ra.
• Tạo, sửa, xoá webhook, đổi khoá ký, xem lịch sử gửi và gửi lại một lần gửi bị lỗi.

Khoá API

• Khoá công khai (pk_…) dùng cho khung chat trên website và chỉ chạy trên tên miền đã khai báo.
• Khoá bí mật đọc được dữ liệu khách hàng, nên chỉ chủ tài khoản tạo hoặc thu hồi được, ở Kênh & tích hợp. Khoá chỉ hiện một lần lúc tạo; hãy lưu ở nơi an toàn.
• Mỗi khoá có phạm vi quyền riêng, ví dụ đọc hồ sơ, ghi hồ sơ, đọc sự kiện, quản lý webhook.

Những điều nên biết khi tích hợp

• Tạo hồ sơ qua API cần header Idempotency-Key, để gửi lại một yêu cầu không tạo hồ sơ trùng.
• Phản hồi có các header RateLimit-*. Khi vượt giới hạn, API trả 429 kèm Retry-After.
• Lỗi trả về dạng application/problem+json, có mã lỗi cố định trong trường code.

Webhook

• Mỗi lần gửi có header Webzone-Signature để bạn kiểm tra đúng là WZ SmartAgent gửi. Chữ ký là HMAC-SHA256 trên thời điểm và nội dung.
• Một sự kiện có thể tới hơn một lần. Hãy bỏ trùng theo id của sự kiện và sắp thứ tự trong một hồ sơ theo case_seq.
• Gửi lỗi thì hệ thống thử lại nhiều lần, giãn dần từ 30 giây tới 12 giờ. Địa chỉ trả 410 Gone sẽ bị tắt.
• Lịch hẹn thuộc một hồ sơ phát sự kiện appointment.created và appointment.updated.
• Webhook do Quản trị kỹ thuật (IT) tạo chờ chủ tài khoản duyệt mới gửi.

Ví dụ kiểm tra nhanh một khoá, với <khoá bí mật> là khoá của bạn:

curl -H "Authorization: Bearer <khoá bí mật>" https://api.webzone.vn/v1/tenant

Gắn khung chat

Cách gắn khung chat và các thuộc tính của đoạn mã nằm ở Gắn khung chat lên website.