← 所有文章
教程

取消 UnifyPort 授权:避免旧二维码重新出现在登录界面

要取消 UnifyPort 授权流程,应对支持的渠道调用 POST /v1/accounts/{account_id}/auth/cancel,请求体为 {}。关闭二维码弹窗只是本地界面操作。先隐藏旧登录材料,阻止迟到响应重新显示它,再提交取消请求,读取授权状态后决定是否提供新的登录入口。请求超时表示结果待确认,不等于取消失败。

要点

  • 文档列出的取消支持包括 Telegram、WhatsApp 和 TikTok;不能根据支持扫码登录就推断支持取消。
  • 操作响应中的 cancelled 与消息账号当前授权状态是不同的观察结果。
  • 按账号协调开始、取消及凭据提交,包括不同浏览器标签页的请求。
  • 取消授权不是删除账号、调整计费,也不能证明平台上的所有会话都已撤销。

先选对控制操作

用户意图对应操作
暂时隐藏登录界面关闭界面,并明确授权是否继续
放弃当前授权尝试使用受支持的取消授权操作
暂停已有连接停止运行时,不要重置授权
移除 UnifyPort 消息账号资源使用独立的账号删除流程

计划暂停运行时指南处理的是已经连接的账号。本文解决的是操作者不想继续完成的授权尝试。

取消授权参考涵盖验证码、二维码和会话导入流程,但渠道支持限定为 Telegram、WhatsApp、TikTok。LINE、Zalo 支持二维码登录,不代表它们支持这个取消操作。

二维码过期不等于取消整个尝试

Telegram 的官方二维码登录规范说明了登录令牌过期、生成替代二维码,以及由已登录应用接受令牌的过程。因此,旧二维码图片不能作为持久的登录状态。但这份规范不定义 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 跑通发送,再用标准事件把所有入站消息接回业务系统。