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