API 參考

帳戶授權

開始驗證碼認證

使用帳號已儲存的手機號碼啟動授權。WhatsApp 從 data.verify_code 讀取配對碼，在手機端輸入，毋須提交至 /auth/code。Telegram 將用戶收到的驗證碼提交至 /auth/code，需要二次密碼時再呼叫 /auth/password。awaiting_code 不代表授權成功。

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

呼叫前準備

在伺服器端使用資源所屬工作區的 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。下一步請參閱相關操作。

回應 200 · WhatsApp

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "verify_code": "ABCD-EFGH"
  }
}

回應 200 · Telegram

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "telegram",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "auth_payload": {
      "type": "code"
    }
  }
}

回應內容

provider
string

本次授權動作對應的渠道。

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

action
string

請求的授權動作，值為 start_auth。

enum: start_auth

status
string

目前授權狀態；awaiting_code 表示等待用戶操作，authorized 才表示授權完成。

auth_status
string

目前授權步驟的標準狀態，通常與 status 一致。

verify_code
string

WhatsApp 手機號碼配對碼，直接位於 data 下。讓用戶在手機端輸入，毋須提交至 /auth/code；回應不保證提供到期時間。

auth_payload
object

渠道特定的授權提示。Telegram 可回傳 type=code，不包含用戶收到的驗證碼。

type
string

授權提示類型；Telegram 驗證碼步驟為 code。

回應

200

200 · WhatsApp

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

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 與工作區是否有效。