API 參考

帳戶授權

檢查掃碼狀態

查詢掃碼登入嘅進度，直至渠道回傳成功或者失敗。QR 待掃時會回傳最新嘅 auth_payload.qr_code；WhatsApp 亦可能改為回傳 passkey_required 同下一步 WebAuthn 所需嘅 auth_payload.public_key。

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/auth/qr/check

呼叫前準備

在伺服器端使用資源所屬工作區的 X-Api-Key，執行範例前替換所有預留位置。

參數從哪裡取得
account_id
從建立或查詢帳號的回應取得 data.id。帳號屬於 X-Api-Key 對應的工作區。 攞帳號

請求參數

請求標頭

X-Api-Key
string必填

工作區 API Key，工作區會由呢個標頭解析得出嚟。

Content-Type
string必填

發送 JSON 請求內容嘅時候請用 application/json。

路徑參數

account_id
string必填

用嚟識別嗰條 authentication 路由嘅 ID。

請求內容

呢個介面接收空 JSON 物件；請跟請求例子傳送 {}。

如何理解結果

依文件解讀回應欄位與 HTTP 狀態。204 成功沒有回應本文，排查時使用 X-Request-Id。下一步請參閱相關操作。

回應 awaiting_qr_scan

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "check_qr_auth",
    "status": "awaiting_qr_scan",
    "auth_status": "awaiting_qr_scan",
    "auth_payload": {
      "qr_code": "<QR_CODE>"
    }
  }
}

回應 passkey_required

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "check_qr_auth",
    "status": "passkey_required",
    "auth_status": "passkey_required",
    "auth_payload": {
      "type": "passkey",
      "public_key": {
        "challenge": "<BASE64URL_CHALLENGE>"
      }
    }
  }
}

回應內容

provider
string

管道識別碼。呼叫其他介面時原樣使用 API 回傳的值；此介面的回傳範圍請看下方列舉。

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol

action
string

今次要求嘅運行操作。

status
string

目前授權流程狀態，例如 pending_auth、awaiting_qr_scan、awaiting_code、pending、passkey_required、passkey_pending、passkey_confirmation、passkey_confirmation_sent、authorized 或 failed。

auth_status
string

Passkey 動作回傳嘅標準認證狀態。

auth_payload
object

目前步驟所需嘅標準載荷。普通 QR 用 qr_code；驗證碼步驟用 type=code；Passkey 用 type=passkey 同 public_key。互斥步驟嘅載荷唔會同時出現。

type
string

目前載荷類型；驗證碼步驟係 code，Passkey 步驟係 passkey。

qr_code
string

只可以喺 auth_status 為 awaiting_qr_scan 時顯示嘅二維碼內容。

public_key
object

auth_status 為 passkey_required 時傳畀瀏覽器 credentials API 嘅 WebAuthn PublicKeyCredentialRequestOptions。

account_id
string

呢個回應所指嘅渠道帳號。

expires_at
string

RFC3339 時間戳，過咗呢個時間之後而家個 auth_payload 就唔再有效。

回應

200

200 OK

請求成功，回應內容嘅例子如上。

400

請求錯誤

請求內容、路徑或者參數無效。

401

未授權

X-Api-Key 請求標頭缺少或者無效。

409

衝突

目前操作同現有嘅渠道帳號或者資源衝突。

500

伺服器錯誤

服務遇到咗未預期嘅錯誤。

502

上游閘道錯誤

渠道轉接器或者上游渠道未能完成呢個操作。

失敗後如何處理

檢查 HTTP 狀態和 error.code/numeric_code，保留 request_id。依原因修正參數、繼續授權或檢查狀態。重試傳送及寫入前確認上次結果，避免重複操作。 錯誤碼參考

invalid_request · 10000 · 400
檢查必填欄位、格式與渠道條件，修正請求後再呼叫。
invalid_api_key · 11001 · 401
檢查 X-Api-Key 與工作區是否有效。