取消 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 設定指南。本文額外處理的是:哪一次嘗試還能更新畫面或繼續送出請求。
讓同一帳號的授權動作依序執行
以下是應用程式設計建議,不是伺服器端交易保證:
- 將畫面綁定到已核對的工作空間與
account_id,確認操作人員有權管理該訊息帳號。 - 後端每個帳號只保留一個有效的授權控制流程。除了防止按鈕連點,也要協調其他分頁與其他操作人員。
- 使用者按取消時,將本機嘗試標記為失效、隱藏敏感資料、停用驗證碼與密碼提交,停止排定新輪詢。
- 更新本機畫面代次,讓已送出的請求無法在回傳後重新顯示舊畫面。
- 透過後端送出取消;在核對結果前,停用重新開始按鈕。
以下瀏覽器端範例會丟棄過時的讀取回應。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。
讓訊息接入變成一條穩定的產品管線。
先用統一 API 跑通傳送,再用標準事件把所有入站訊息接回業務系統。