Tài liệu tham khảo API
API công khai dành cho nhà phát triển: Biểu mẫu, Widget, cấu hình sản phẩm và nhiều hơn nữa.
Tài liệu tham khảo này chỉ mô tả các endpoint JSON thực sự có thể sử dụng công khai -- phương thức, đường dẫn, loại xác thực, tham số bắt buộc, request và response mẫu cũng như các mã lỗi đã được tài liệu hóa cho từng endpoint. Zentor không có hệ thống khóa API chung dành cho nhà phát triển; tùy theo route, việc truy cập diễn ra hoặc không cần xác thực, hoặc thông qua Widget-Embed-Token kèm kiểm tra Origin. Các route nội bộ của bảng điều khiển và endpoint Master Admin được cố ý loại khỏi tài liệu tham khảo công khai này, vì chúng chỉ có thể truy cập thông qua phiên đăng nhập thông thường.
Mỗi mục endpoint đều có một ghi chú kiểm thử trực tiếp, cho biết thông tin đến từ schema của Registry, từ một kiểm thử tự động hay từ quan sát thực tế trực tiếp -- chỉ sự tương tự với một đường dẫn mã đang hoạt động không được coi là bằng chứng đầy đủ. Ngoài ra, một lệnh gọi thành công về mặt kỹ thuật luôn chỉ xác nhận việc xử lý chính request đó, chứ không tự động xác nhận các quy trình tiếp theo như gửi email, hoàn tất thanh toán hoặc đăng nhập SSO đã hoàn tất.
Cơ chế bảo vệ phụ thuộc vào từng nhóm. Các endpoint công khai về pháp lý, marketing và biểu mẫu không cần phiên bảng điều khiển. Ngược lại, widget chat sử dụng header `X-Widget-Token` và một Origin-Allowlist. Đăng nhập bảng điều khiển cung cấp một Session-JWT có thời hạn mười hai giờ và một Refresh-Token có hiệu lực bảy ngày. Các endpoint SSO hoạt động với mã dùng một lần và quy trình callback riêng.
Hãy đọc mỗi trang endpoint như một hợp đồng độc lập. Điều quyết định là phương thức HTTP, đường dẫn, tham số bắt buộc, kiểu dữ liệu, request body, cấu trúc response, mã lỗi và tính idempotent. Một ví dụ cho thấy một định dạng có thể có, nhưng không thay thế việc kiểm tra phản hồi thực tế. Trạng thái cấu hình, kiểm tra hợp lệ, quyền hạn và nhà cung cấp bên ngoài có thể làm thay đổi kết quả.
Giới hạn tần suất đã được xác nhận trên toàn nền tảng là 2.000 request trong vòng 15 phút. Giới hạn riêng cho từng endpoint không được tài liệu hóa đầy đủ. Vì vậy, client không nên sử dụng các vòng lặp polling dày đặc không cần thiết. Với các thao tác không idempotent, việc tự động thử lại có thể tạo ra bản ghi hoặc tin nhắn trùng lặp.
Các giá trị nhạy cảm không được đưa vào nhật ký. Chúng bao gồm mật khẩu, Reset-Token, mã xác minh, Widget-Token, Session-ID và dữ liệu mẫu cá nhân thực. Hãy sử dụng giá trị đã được ẩn danh trong tài liệu và kiểm thử. Các ghi chú kiểm thử trực tiếp phải phản ánh chính xác bằng chứng thực tế.