API 參考

面向開發者嘅介面:公開端點、聊天 Widget、登入,以及帶 API 金鑰嘅 REST API。

API 參考文件說明咗 Zentor App 嘅介面,您可以喺自己嘅網站同程式入面呼叫佢哋:用於表單、產品配置工具同內容嘅公開端點、聊天 Widget、示範聊天機械人,以及包括單一登入嘅登入功能。每個端點頁面都列出方法、路徑、身份驗證方式、參數、請求同回應範例,以及文件記錄嘅錯誤代碼。

身份驗證:表單、產品配置工具同內容嘅端點可以喺唔登入嘅情況下呼叫。聊天 Widget 嘅端點要求喺`X-Widget-Token`標頭提供您 Widget 嘅嵌入權杖,並且只接受嚟自呢個 Widget 已經批准域名嘅呼叫。登入端點會為使用者工作階段發出存取權杖(JWT)同刷新權杖。

透過 API 金鑰進行 API 存取:對於您自己嘅程式同伺服器之間嘅整合,REST API 可以喺基礎 URL `https://zentor-app.de/api/v1` 使用。Zentor 會按要求為您嘅帳戶開通 API 存取權限。之後,管理員可以喺儀表板嘅「API 金鑰」下建立自己嘅金鑰,並設定佢嘅權限(scope)——涉及預約同預訂、聊天機械人、通訊、檔案、知識庫、報告,以及網頁資料。每個領域都有一個唯讀 scope(`<領域>.read`,只限 GET)同一個寫入 scope(`<領域>.write`,包括讀取權限),例如`appointments.read`或者`knowledge.write`。請喺`Authorization: Bearer <API 金鑰>`標頭傳送金鑰,或者改用`X-API-Key`標頭。可以用`GET /api/v1/me`查看某個金鑰屬於邊個帳戶同佢嘅 scope。

完整金鑰只喺生成嗰陣顯示一次。請妥善保管,並只喺伺服器端保存——千祈唔好寫入瀏覽器代碼或者移動應用程式。金鑰可以設定過期時間、進行輪換同撤銷。透過 REST API 只可以存取您套餐入面包含嘅功能,所有資料都限定喺您嘅帳戶範圍內。常見錯誤:401 `API_KEY_INVALID`、`API_KEY_EXPIRED`或者`API_KEY_REVOKED`(金鑰缺失、錯誤、已過期或者已經被撤銷)、403 `API_ACCESS_NOT_ENABLED`(帳戶仲未開通 API 存取)、403 `API_SCOPE_MISSING`(金鑰缺少所需 scope)、403 `TENANT_NOT_ACTIVE`或者`TENANT_LOCKED`(帳戶未啟用或者已經被鎖定),以及404 `API_ENDPOINT_NOT_AVAILABLE`(呢個端點冇辦法透過 REST API 存取)。

回應同限制:所有端點都以 JSON 回應。成功回應嘅狀態碼係2xx,並帶有`"ok": true`;錯誤回應包含機器可讀嘅錯誤代碼(喺`error`或者`error.code`欄位)同一個訊息。每個 IP 地址喺15分鐘內最多可以發出2,000次請求;表單、驗證同登入端點適用更嚴格嘅限制,具體說明見各自頁面。超出限制嗰陣,伺服器就會以429 `RATE_LIMIT_EXCEEDED`回應。標記為非冪等嘅端點,喺連接中斷之後唔應該自動重試,否則可能產生重複嘅請求或者訊息。

請只透過 HTTPS 喺請求體或者標頭傳送密碼、權杖、API 金鑰同驗證碼——千祈唔好放喺 URL、記錄或者支援請求入面。

身份驗證 (5)登入、權杖刷新、密碼重設、SSO完成——以及透過 API 金鑰進行嘅 API 存取。公開表單 (11)聯絡、咨詢請求、存取申請、付款同帳戶啟用。產品配置工具 (5)套餐目錄、價格預覽、電郵確認同設定提交。公開內容 (6)法律文件、營銷頁面、網站主題同文字顏色。聊天 Widget (9)嵌入您網站嘅聊天 Widget 所使用嘅所有端點。示範聊天機械人同 SSO (13)公開示範聊天機械人同單一登入端點(SAML/OIDC)。
← 返回概覽