← 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_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
上游网关错误

渠道适配器或上游渠道未能完成该操作。

请求

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>"
      }
    }
  }
}