← 全記事
チュートリアル

UnifyPortの認証をキャンセルし、古いQRコードの再表示を防ぐ

UnifyPortの認証フローをキャンセルするには、対応プロバイダーで POST /v1/accounts/{account_id}/auth/cancel に {} を送ります。QR画面を閉じるだけでは、ローカルUIが変わるだけです。古い認証情報を非表示にし、遅延応答による再表示を防いでからキャンセルを要求し、認証状態を読み直して次のログインを判断します。タイムアウトは失敗の確定ではなく、結果が未確認であることを意味します。

要点

  • キャンセルの対応対象はTelegram、WhatsApp、TikTokです。QRログイン対応からキャンセル対応を推測しないでください。
  • 操作応答の cancelled と、アカウントの現在の認証状態は別の情報です。
  • 開始、キャンセル、認証情報の送信をアカウント単位で調整し、別タブからの操作も対象にします。
  • 認証のキャンセルは、アカウント削除、課金変更、ネイティブ側の全セッション失効を意味しません。

意図に合う操作を選ぶ

利用者の意図適切な操作
ログイン画面を一時的に隠すUIを閉じ、認証を継続するかどうかを明示する
現在の認証試行を取りやめる対応する認証キャンセル操作を使う
接続済みアカウントの通信を一時停止する認証をリセットせず、ランタイムを停止する
UnifyPortのアカウントリソースを削除する独立したアカウント削除フローを使う

計画的なランタイム停止のガイドは接続済みアカウントを扱います。本記事の対象は、利用者が完了させるつもりのない認証試行です。

認証キャンセルのリファレンスはコード、QR、セッションインポートのキャンセルを説明していますが、対応プロバイダーはTelegram、WhatsApp、TikTokに限られます。LINE連携を含む管理画面でも、LINEやZaloがQRログインに対応しているという理由だけで同じキャンセルボタンを有効にしないでください。

QRの期限切れと試行の中止を分ける

Telegramの公式QRログイン仕様は、ログイントークンの期限、新しいQRの生成、ログイン済みアプリによる承認を説明しています。古いQR画像が永続的なログイン状態ではない理由はここにあります。ただし、この仕様はUnifyPortのキャンセル契約を定義せず、ブラウザーを閉じれば認証が止まるとも保証していません。

UnifyPortの認証状態取得は status、auth_fields、auth_payload、expires_at、last_error を返します。保存したスクリーンショットではなく、現在の状態とペイロードを使ってください。QR、コード、パスワード、セッション情報をログや分析システムに残さないようにします。

初回接続については Telegramのコード・QR設定ガイドを参照してください。ここで追加するのは、どの試行がまだ画面更新やリクエスト送信を行ってよいかという制御です。

同じアカウントの認証操作を直列化する

以下はアプリケーション設計の提案であり、サーバー側のトランザクション保証ではありません。

  1. 画面を確認済みのワークスペースと account_id に紐付け、そのメッセージングアカウントを操作する権限を確認します。
  2. バックエンドでアカウントごとに有効な認証制御を一つにします。ボタンの二重クリックだけでなく、別タブや別担当者の操作も調整します。
  3. キャンセル時にローカル試行を無効化し、機密情報を隠し、コード・パスワード送信と新しいポーリングの予約を止めます。
  4. ローカルUIの世代を進め、すでに送信済みのリクエストが古い画面を復元できないようにします。
  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画面を自動的に開き直す理由にはしません。

キャンセル後に現在の状態を読む

以下は未実行のリクエスト例です。変数にはバックエンドの保護された設定と、確認済みアカウント選択の値を使います。

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、セッション認証を開始すると 409 account_already_authorized になります。これは正常なアカウントを自動キャンセルして再試行してよいという意味ではありません。新しい認証が本当に必要か確認します。

待機中の試行を取りやめた場合は、キャンセル結果の照合後に新しいUI世代を作り、アカウントの設定済み認証モードに対応する開始操作を呼びます。新しく取得した情報だけを表示してください。認証完了後も、接続準備ができているかは別途 runtime_status で確認します。

UnifyPortは非公式インターフェースです。この操作はプロバイダーの他セッションを一括ログアウトさせる機能ではなく、上流のセキュリティ制御を解除するものでもありません。

FAQ

QR画面を閉じれば認証もキャンセルされますか?

それだけではされません。画面を閉じる操作はUIの変更です。サーバー側のキャンセルには対応API操作が必要です。

QRの期限切れで自動キャンセルすべきですか?

いいえ。期限切れは表示中の認証情報に関するものです。利用者が中止したい場合を除き、現在の認証状態を確認し、対応する更新フローに従います。

タイムアウト後にキャンセル成功と表示できますか?

できません。未確認と表示して状態を照合します。すぐに新しいフローを開始したり、キャンセルを繰り返し送ったりしないでください。

キャンセルで課金停止やメッセージ削除も行われますか?

契約はどちらも保証していません。アカウント廃止、課金、保存メッセージの整理、認証制御は分けて扱います。

次のステップと参照資料

認証キャンセルのリファレンスに沿って実装してください。遅延ポーリング応答、二つのタブ、承認とキャンセルの競合、応答消失、意図的な再開始をテスト項目にします。これらは提案であり、実施済みの結果ではありません。

確認日:2026-11-12。

UnifyPort API

メッセージ連携を安定したプロダクトパイプラインへ。

まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。