概觀

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

API Token

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

HTTP 狀態碼參考

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

成功碼

{
  "code": "SUCCESS",
  "msg": "success"
}

Code	Message
SUCCESS	Success

錯誤碼

{
  "code": "CODE_PARAMS_INVALID",
  "msg": "Invalid parameters."
}

Code	Message
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_NFC	UniFi Identity Enterprise 使用者的 NFC 卡不可轉移。
CODE_CREDS_NFC_READ_SESSION_NOT_FOUND	無法取得 NFC 讀取工作階段。
CODE_CREDS_NFC_READ_POLL_TOKEN_EMPTY	NFC 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_INVALID	PIN 碼長度不符合預設要求。
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。

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

請求標頭

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

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

回應結構

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

{
  "code": "SUCCESS",
  "msg": "success",
  "data": {}
}

1. code：表示請求處理的結果，指示成功或失敗。
2. msg：當 code 不等於 1 時，表示錯誤描述。
3. data：表示 API 請求的資料。