跳至主要内容

接入指南

請求入口​

服務端 API 的入口為 https://{gateway_host}。請使用 HTTPS，並在服務端設定合理的連線、讀取和整體逾時。

統一回應​

多數開放介面使用以下回應外殼：

{ "code": 200, "msg": "", "data": {} }

code=200 表示成功；code=500 表示業務失敗。鑑權失敗使用 HTTP 狀態碼，例如 401 INVALID_TOKEN 和 403 SCOPE_DENIED。OAuth 令牌和 UserInfo 介面使用 OAuth JSON 外殼，詳見鑑權與簽名。

通用請求規則​

  • 令牌按介面說明放在 Authorization: Bearer、Query 或表單中，同一請求只使用一種方式。
  • Content-Type: application/json 的請求體必須是合法 JSON。
  • 成員 ID、部門 ID、機器人 ID 使用字串傳輸。
  • code 和 access_token 不寫入日誌、URL、埋點或錯誤上報。

錯誤與重試​

類型處理
400 參數錯誤修正請求，不重試
401 令牌無效重新取得令牌後重試一次
403 權限或 IP 不允許檢查權限設定，不重試
5xx 或網路逾時有限次數指數退避，並設定熔斷
機器人業務失敗根據逐項錯誤和冪等鍵決定是否重試

查詢介面天然具備冪等性；機器人發送介面和事件回呼必須由應用側保證冪等。

錯誤碼與限流​

機器人介面同時存在 HTTP 層、請求級業務層和逐項投遞層錯誤。

層級典型錯誤處理方式
HTTP401 INVALID_TOKEN、403 SCOPE_DENIED、503修復鑑權或有限退避
請求級INVALID_REQUEST、PERMISSION_DENIED修正請求，不重試無效參數
逐項結果rejected、failed按使用者和錯誤碼分類處理

日誌與安全​

  • 不記錄 AppSecret、access_token、code、Webhook secret_key 或完整簽名原文。
  • 對外回應只返回必要的業務錯誤，不暴露內部堆疊、資料庫或服務發現資訊。
  • 令牌、冪等鍵和請求 ID 應透過安全的密鑰與可觀測性設定管理。