Skip to content

概觀 ​

本節介紹與 API 操作相關的基本概念,包括 API Token、HTTP 狀態碼、成功與錯誤碼、HTTP 動詞以及 API 主機。

API Token ​

若要驗證 UniFi Access 的 API 請求,您需要使用與帳戶關聯的 API Token。如果請求包含已刪除或過期的 Token,服務將回傳驗證錯誤。Authorization Token 可從 UniFi Portal 取得。

HTTP 狀態碼參考 ​

200OK一切正常運作。
400Bad Request請求不合法,通常是缺少必填參數。
401Unauthorized請求缺少有效的 API Token 進行身份驗證。
402Request Failed請求包含有效參數,但因某些原因失敗。
403Forbidden使用的 API Token 不具備執行此請求所需的權限。
429Too Many Requests在短時間內向 API 傳送了過多請求。
500, 502, 503, 504Server ErrorsUniFi Access 端在處理請求時發生錯誤。

成功碼 ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}
CodeMessage
SUCCESSSuccess

錯誤碼 ​

json
{
  "code": "CODE_PARAMS_INVALID",
  "msg": "Invalid parameters."
}
CodeMessage
CODE_PARAMS_INVALID提供的參數無效。
CODE_SYSTEM_ERROR伺服器端發生錯誤。
CODE_RESOURCE_NOT_FOUND找不到請求的資源。
CODE_OPERATION_FORBIDDEN不允許執行請求的操作。
CODE_AUTH_FAILED驗證失敗。
CODE_ACCESS_TOKEN_INVALID提供的存取 Token 無效。
CODE_UNAUTHORIZED您無權執行此操作。
CODE_NOT_EXISTS請求的項目不存在。
CODE_USER_EMAIL_ERROR提供的電子郵件格式無效。
CODE_USER_ACCOUNT_NOT_EXIST請求的使用者帳戶不存在。
CODE_USER_WORKER_NOT_EXISTS請求的使用者不存在。
CODE_USER_NAME_DUPLICATED提供的名稱已存在。
CODE_USER_CSV_IMPORT_INCOMPLETE_PROP請提供名字和姓氏。
CODE_ACCESS_POLICY_USER_TIMEZONE_NOT_FOUND找不到請求的工作日排程。
CODE_ACCESS_POLICY_HOLIDAY_TIMEZONE_NOT_FOUND找不到請求的假日排程。
CODE_ACCESS_POLICY_HOLIDAY_GROUP_NOT_FOUND找不到請求的假日群組。
CODE_ACCESS_POLICY_HOLIDAY_NOT_FOUND找不到請求的假日。
CODE_ACCESS_POLICY_SCHEDULE_NOT_FOUND找不到請求的排程。
CODE_ACCESS_POLICY_HOLIDAY_NAME_EXIST提供的假日名稱已存在。
CODE_ACCESS_POLICY_HOLIDAY_GROUP_NAME_EXIST提供的假日群組名稱已存在。
CODE_ACCESS_POLICY_SCHEDULE_NAME_EXIST提供的排程名稱已存在。
CODE_ACCESS_POLICY_SCHEDULE_CAN_NOT_DELETE無法刪除此排程。
CODE_ACCESS_POLICY_HOLIDAY_GROUP_CAN_NOT_DELETE無法刪除此假日群組。
CODE_CREDS_NFC_HAS_BIND_USER此 NFC 卡已註冊並指派給其他使用者。
CODE_CREDS_DISABLE_TRANSFER_UID_USER_NFCUniFi Identity Enterprise 使用者的 NFC 卡不可轉移。
CODE_CREDS_NFC_READ_SESSION_NOT_FOUND無法取得 NFC 讀取工作階段。
CODE_CREDS_NFC_READ_POLL_TOKEN_EMPTYNFC Token 為空。
CODE_CREDS_NFC_CARD_IS_PROVISION此 NFC 卡已在其他站點註冊。
CODE_CREDS_NFC_CARD_PROVISION_FAILED請將 NFC 卡靠近讀卡器超過 5 秒。
CODE_CREDS_NFC_CARD_INVALID不支援此卡片類型。請使用 UA Card。
CODE_CREDS_NFC_CARD_CANNOT_BE_DELETE無法刪除此 NFC 卡。
CODE_CREDS_PIN_CODE_CREDS_ALREADY_EXIST此 PIN 碼已存在。
CODE_CREDS_PIN_CODE_CREDS_LENGTH_INVALIDPIN 碼長度不符合預設要求。
CODE_SPACE_DEVICE_BOUND_LOCATION_NOT_FOUND找不到裝置的位置。
CODE_DEVICE_DEVICE_VERSION_NOT_FOUND韌體版本已是最新。
CODE_DEVICE_DEVICE_VERSION_TOO_OLD韌體版本過舊,請更新至最新版本。
CODE_DEVICE_DEVICE_BUSY攝影機目前使用中。
CODE_DEVICE_DEVICE_NOT_FOUND找不到該裝置。
CODE_DEVICE_DEVICE_OFFLINE裝置目前離線。
CODE_OTHERS_UID_ADOPTED_NOT_SUPPORTED升級至 Identity Enterprise 後,API 將無法使用。
CODE_HOLIDAY_GROUP_CAN_NOT_DELETE無法刪除此假日群組。
CODE_HOLIDAY_GROUP_CAN_NOT_EDIT無法編輯此假日群組。
CODE_DEVICE_WEBHOOK_ENDPOINT_DUPLICATED提供的端點已存在。
CODE_DEVICE_API_NOT_SUPPORTED此裝置目前不支援此 API。

HTTP 動詞 ​

HTTP 方法說明
GET用於取得物件。
POST用於建立物件或執行自訂操作。
PUT用於取代物件或集合。
DELETE用於刪除物件。

API 主機 ​

Open API Server 託管於連接埠 12445,可透過 HTTPS 存取:https://console-ip:12445。

伺服器憑證為自行產生且不受信任。

請求標頭 ​

請求的標頭包含以下資訊:

參數必填型別說明範例
AuthorizationTString身份驗證與存取控制所需的 Token。Authorization: Bearer wHFmHRuX4I7sB2oDkD6wHg

回應結構 ​

請求的回應包含以下資訊:

json
{
  "code": "SUCCESS",
  "msg": "success",
  "data": {}
}
  1. code:表示請求處理的結果,指示成功或失敗。
  2. msg:當 code 不等於 1 時,表示錯誤描述。
  3. data:表示 API 請求的資料。