Tài liệu tham khảo API

Giao diện dành cho nhà phát triển: các endpoint công khai, widget chat, đăng nhập và REST API với khóa API.

Tài liệu tham khảo API mô tả các giao diện của Zentor App mà bạn có thể gọi từ website và chương trình của riêng mình: các endpoint công khai cho biểu mẫu, bộ cấu hình sản phẩm và nội dung, widget chat, chatbot demo, cùng đăng nhập bao gồm cả single sign-on. Mỗi trang endpoint cho biết phương thức, đường dẫn, xác thực, tham số, một ví dụ về yêu cầu và phản hồi, cùng các mã lỗi được ghi lại.

Xác thực: các endpoint cho biểu mẫu, bộ cấu hình sản phẩm và nội dung có thể gọi mà không cần đăng nhập. Các endpoint của widget chat yêu cầu embed token của widget trong header `X-Widget-Token` và chỉ chấp nhận các lệnh gọi từ những miền đã được phê duyệt cho widget đó. Các endpoint đăng nhập cấp một access token (JWT) và một refresh token cho phiên người dùng.

Truy cập API bằng khóa API: dành cho các chương trình riêng và tích hợp server-to-server, REST API có sẵn tại base URL `https://zentor-app.de/api/v1`. Zentor kích hoạt quyền truy cập API cho tài khoản của bạn theo yêu cầu. Sau đó, quản trị viên tạo khóa riêng trong bảng điều khiển tại “Khóa API” và xác định quyền hạn (scope) của chúng – cho lịch hẹn và đặt lịch, chatbot, giao tiếp, tệp, cơ sở tri thức, báo cáo và dữ liệu web. Mỗi lĩnh vực có một scope đọc (`<lĩnh vực>.read`, chỉ GET) và một scope viết (`<lĩnh vực>.write`, bao gồm cả đọc), ví dụ `appointments.read` hoặc `knowledge.write`. Gửi khóa trong header `Authorization: Bearer <khóa API>` hoặc thay vào đó trong header `X-API-Key`. Dùng `GET /api/v1/me` để kiểm tra khóa thuộc tài khoản và scope nào.

Khóa đầy đủ chỉ được hiển thị một lần khi tạo. Hãy lưu trữ an toàn và chỉ ở phía server – không bao giờ trong mã trình duyệt hoặc ứng dụng di động. Khóa có thể được đặt ngày hết hạn, xoay vòng và thu hồi. Qua REST API chỉ có thể truy cập các chức năng có trong gói của bạn, và toàn bộ dữ liệu bị giới hạn trong tài khoản của bạn. Lỗi thường gặp: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` hoặc `API_KEY_REVOKED` (khóa bị thiếu, sai, hết hạn hoặc đã bị thu hồi), 403 `API_ACCESS_NOT_ENABLED` (chưa kích hoạt quyền truy cập API cho tài khoản), 403 `API_SCOPE_MISSING` (khóa thiếu scope cần thiết), 403 `TENANT_NOT_ACTIVE` hoặc `TENANT_LOCKED` (tài khoản không hoạt động hoặc bị khóa) và 404 `API_ENDPOINT_NOT_AVAILABLE` (endpoint không khả dụng qua REST API).

Phản hồi và giới hạn: mọi endpoint đều phản hồi bằng JSON. Phản hồi thành công có trạng thái 2xx và `"ok": true`; phản hồi lỗi chứa một mã lỗi máy có thể đọc được (trong trường `error` hoặc `error.code`) và một thông báo. Mỗi địa chỉ IP có thể thực hiện 2.000 yêu cầu trong 15 phút; các endpoint biểu mẫu, xác minh và đăng nhập áp dụng giới hạn nghiêm ngặt hơn, được nêu trên từng trang. Khi vượt giới hạn, server trả lời bằng 429 `RATE_LIMIT_EXCEEDED`. Các endpoint được đánh dấu không idempotent không nên được tự động thử lại sau khi mất kết nối, vì có thể tạo ra các yêu cầu hoặc tin nhắn trùng lặp.

Chỉ truyền mật khẩu, token, khóa API và mã xác nhận trong request body hoặc header qua HTTPS – không bao giờ trong URL, nhật ký hoặc yêu cầu hỗ trợ.

Xác thực (5)Đăng nhập, làm mới token, đặt lại mật khẩu, hoàn tất SSO – và truy cập API bằng khóa API.Biểu mẫu công khai (11)Liên hệ, yêu cầu tư vấn, yêu cầu truy cập, thanh toán và kích hoạt tài khoản.Bộ cấu hình sản phẩm (5)Danh mục gói, xem trước giá, xác nhận email và gửi cấu hình.Nội dung công khai (6)Văn bản pháp lý, trang marketing, chủ đề và màu chữ của website.Widget chat (9)Tất cả các endpoint mà widget chat được nhúng trên website của bạn sử dụng.Chatbot demo và SSO (13)Chatbot demo công khai và các endpoint single sign-on (SAML/OIDC).
← Quay lại danh sách tổng quan