← 所有文章
教學

取消 UnifyPort 授權:防止舊二維碼再次出現在登入畫面

要取消 UnifyPort 授權流程,請對支援的渠道呼叫 POST /v1/accounts/{account_id}/auth/cancel,請求內容為 {}。關閉二維碼視窗只是本機介面操作。先隱藏舊登入資料,防止延遲回應再次顯示它,再提交取消請求,讀取授權狀態後決定是否提供新的登入入口。請求逾時代表結果有待確認,不等於取消失敗。

重點

  • 文件列出的取消支援包括 Telegram、WhatsApp 和 TikTok;支援掃碼登入不代表支援取消操作。
  • 操作回應中的 cancelled 與帳戶目前的授權狀態,是兩種不同的觀察結果。
  • 按帳戶協調開始、取消及憑證提交,也要處理不同瀏覽器分頁的請求。
  • 取消授權不是刪除帳戶、改變收費,也不能證明平台上的所有工作階段均已撤銷。

按實際意圖選擇控制方式

使用者意圖適合的操作
暫時隱藏登入畫面關閉介面,並明確說明授權是否繼續
放棄目前授權嘗試使用受支援的取消授權操作
暫停現有連線停止 runtime,不要重設授權
移除 UnifyPort 訊息帳戶資源使用獨立的帳戶刪除流程

計劃暫停 runtime 指南處理已連線的帳戶。本文則處理操作人員已不想完成的授權嘗試。

取消授權參考文件涵蓋驗證碼、二維碼及工作階段匯入流程,但渠道支援限於 Telegram、WhatsApp、TikTok。LINE、Zalo 支援二維碼登入,不代表這個取消操作也適用。

二維碼過期不等於取消嘗試

Telegram 的官方二維碼登入規格說明登入 token 過期、產生替代二維碼,以及由已登入應用程式接受 token 的過程。因此,舊二維碼圖片不能當成持久的登入狀態。這份規格並不定義 UnifyPort 的取消契約,也不保證關閉瀏覽器視窗會停止授權。

UnifyPort 的讀取授權狀態介面回傳 status、auth_fields、auth_payload、expires_at 和 last_error。應使用目前的狀態及資料,而不是儲存的截圖。二維碼、驗證碼、密碼和工作階段資料不應寫入日誌或分析系統。

首次接入可參考 Telegram 驗證碼與二維碼設定指南。本文增加的是一項控制:只有目前有效的嘗試,才可以更新畫面或繼續提交請求。

同一帳戶的授權操作應按次序執行

以下是應用程式設計建議,不是伺服器端交易保證:

  1. 將畫面綁定至已核對的工作空間和 account_id,確認操作人員有權管理該訊息帳戶。
  2. 後端按帳戶維持一個有效的授權控制流程。除了防止按鈕連按,也要協調其他分頁及其他操作人員。
  3. 按取消時,將本機嘗試標記為失效、隱藏敏感資料、停用驗證碼及密碼提交,並停止安排新的輪詢。
  4. 更新本機畫面代次,避免已送出的請求在回傳後重新顯示舊畫面。
  5. 經後端提交取消;核對結果前,保持重新開始按鈕停用。

以下瀏覽器端範例會捨棄過時的讀取回應。generation 和 loginVisible 是應用程式自訂變數,不是 UnifyPort 欄位:

let generation = 0;
let loginVisible = true;

async function refreshLogin(readAuth, render) {
  const observedGeneration = generation;
  const auth = await readAuth();
  if (!loginVisible || observedGeneration !== generation) return;
  render(auth);
}

function abandonLocalAttempt(clearSensitiveUi) {
  loginVisible = false;
  generation += 1;
  clearSensitiveUi();
}

這個防護不能取消已送出的 HTTP 請求、撤回平台上的批准,或阻止另一個分頁。後端協調及狀態讀取仍然必要。Webhook 接收端應保持運作;延遲送達的授權事件應觸發狀態核對,而不是自動重新開啟舊二維碼視窗。

提交取消,再查目前狀態

以下是未實際執行的示例。變數應來自受保護的後端設定及已核對的帳戶選擇:

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/${ACCOUNT_ID}/auth/cancel" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

curl \
  "https://api.unifyport.ai/v1/accounts/${ACCOUNT_ID}/auth" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}"

取消介面的示例回傳 HTTP 200,並帶有 data.status: "cancelled"。帳戶生命週期文件則將放棄等待中的流程描述為返回 pending_auth。不要將操作結果複製到每個帳戶狀態欄位。

觀察結果建議處理
取消已確認,目前為 pending_auth保持舊資料隱藏,讓使用者明確開始新嘗試
逾時或無法讀取回應標記結果待確認,再次變更前先讀狀態
仍在等待輸入保持舊畫面失效,繼續核對或升級處理,不啟動競爭流程
目前為 authorized視為目前授權的證據,不顯示已登出,也不自動再次取消

批准與取消同時發生時,公開契約沒有保證哪個操作會以原子方式勝出。保留已遮蔽敏感資料的請求診斷,讓操作人員按實際狀態決定下一步。不要承諾文件未列出的取消 Webhook。

重新開始必須是新的明確決定

生命週期文件指出,已授權時啟動驗證碼、二維碼或工作階段授權會回傳 409 account_already_authorized。這不是自動取消正常帳戶再重試的許可。先確認是否真的需要重新授權。

若放棄的是等待中的嘗試,先核對取消結果,再建立新的本機畫面代次,按帳戶設定的模式啟動流程,只顯示新取得的資料。授權完成後,仍須獨立讀取 runtime_status 才能判斷連線是否就緒。

UnifyPort 提供非官方介面。此取消操作不是平台其他工作階段的通用登出功能,也不會解除平台安全控制。

常見問題

關閉二維碼視窗就取消授權了嗎?

不是。關閉視窗只影響應用程式介面;伺服器端取消需要受支援的 API 操作。

二維碼過期後應自動取消嗎?

不應。過期的是登入資料。除非使用者打算放棄,否則應讀取目前授權狀態,並按渠道流程更新資料。

逾時後可以顯示取消成功嗎?

不可以。應顯示結果待確認並核對狀態,不立即開始新流程,也不要連續提交取消。

取消會停止收費或刪除訊息嗎?

取消契約沒有這些保證。帳戶退役、收費、已存訊息清理與授權控制應分開處理。

下一步與參考資料

對照取消授權參考文件實作。建議測試延遲輪詢回應、兩個分頁、批准與取消同時發生、回應遺失,以及有意重新開始。這些是建議測試,並非已取得的結果。

資料核對日期:2026-11-12。

UnifyPort API

令訊息接入變成一條穩定嘅產品管線。

先用統一嘅 API 跑通發送,再用標準事件將所有入站訊息接返去業務系統。