← 所有文章
教學

取消 UnifyPort 授權:避免舊 QR Code 重新出現在登入畫面

若要取消 UnifyPort 授權流程,請對支援的管道呼叫 POST /v1/accounts/{account_id}/auth/cancel,請求主體為 {}。關閉 QR Code 視窗只是本機介面操作。先隱藏舊登入資料,防止延遲回應再次顯示它,再送出取消請求,讀取授權狀態後決定是否開放新登入。請求逾時表示結果待確認,不代表取消失敗。

重點

  • 文件列出的取消支援包含 Telegram、WhatsApp、TikTok;支援掃碼登入不代表支援取消操作。
  • 操作回應的 cancelled 與帳號目前的授權狀態,是不同的觀察結果。
  • 依帳號協調開始、取消與憑證提交,也要涵蓋不同瀏覽器分頁。
  • 取消授權不是刪除帳號、變更計費,也不能證明平台上的所有工作階段已撤銷。

依使用者意圖選擇操作

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

規劃執行階段暫停指南處理已連線帳號。本文則處理操作人員已不打算完成的授權嘗試。

取消授權參考文件說明驗證碼、QR Code 與工作階段匯入流程的取消,但支援管道限於 Telegram、WhatsApp、TikTok。LINE 與 Zalo 支援 QR Code 登入,不表示這個取消操作也適用。

QR Code 過期與取消嘗試不同

Telegram 的官方 QR Code 登入規格說明登入權杖過期、產生新 QR Code,以及透過已登入應用程式接受權杖的流程。因此,舊 QR Code 圖片不能當作持久的登入狀態。這份規格不定義 UnifyPort 的取消契約,也不保證關閉瀏覽器視窗會停止授權。

UnifyPort 的取得授權狀態介面回傳 status、auth_fields、auth_payload、expires_at 和 last_error。請使用目前的狀態及資料,不要沿用儲存的螢幕截圖。QR Code、驗證碼、密碼和工作階段資料都不應寫入日誌或分析系統。

首次串接請參考 Telegram 驗證碼與 QR Code 設定指南。本文額外處理的是:哪一次嘗試還能更新畫面或繼續送出請求。

讓同一帳號的授權動作依序執行

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

  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 接收端應保持運作;延遲送達的授權事件應觸發狀態核對,而不是自動重新開啟舊 QR Code 視窗。

送出取消後,讀取目前狀態

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

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。

重新開始必須是新的決定

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

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

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

常見問題

關閉 QR Code 視窗會取消授權嗎?

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

QR Code 過期後要自動取消嗎?

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

逾時後能顯示取消成功嗎?

不能。請顯示結果待確認並核對狀態,不立即啟動新流程,也不要連續送出取消。

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

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

下一步與資料來源

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

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

UnifyPort API

讓訊息接入變成一條穩定的產品管線。

先用統一 API 跑通傳送,再用標準事件把所有入站訊息接回業務系統。