取消 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 驗證碼與二維碼設定指南。本文增加的是一項控制:只有目前有效的嘗試,才可以更新畫面或繼續提交請求。
同一帳戶的授權操作應按次序執行
以下是應用程式設計建議,不是伺服器端交易保證:
- 將畫面綁定至已核對的工作空間和
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 接收端應保持運作;延遲送達的授權事件應觸發狀態核對,而不是自動重新開啟舊二維碼視窗。
提交取消,再查目前狀態
以下是未實際執行的示例。變數應來自受保護的後端設定及已核對的帳戶選擇:
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。
令訊息接入變成一條穩定嘅產品管線。
先用統一嘅 API 跑通發送,再用標準事件將所有入站訊息接返去業務系統。