← API 參考
認證POST

檢查掃碼狀態

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

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

請求標頭

X-Api-Key
string必填

工作區 API Key，工作區會由此標頭解析得到。

Content-Type
string必填

傳送 JSON 請求內容時請使用 application/json。

路徑參數

account_id
string必填

用於該 authentication 路由的識別字。

請求內容

此介面接收空 JSON 物件；請依請求範例傳送 {}。

回應內容

provider
string

處理此執行階段操作的渠道。

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 時顯示的 QR Code 內容。

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
上游閘道錯誤

渠道轉接器或上游渠道未能完成此操作。

請求

curl -X POST https://api.unifyport.ai/v1/accounts/{account_id}/auth/qr/check \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

回應

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

回應

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