API リファレンス

アカウント認可

QR 認証を確認

QR ログインフローの現在の結果を、プロバイダが成功または失敗を返すまで確認します。QR 待機中は最新の auth_payload.qr_code を返します。WhatsApp では代わりに passkey_required と次の WebAuthn 手順で使う auth_payload.public_key を返す場合があります。

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/auth/qr/check

対応チャネル

TelegramWhatsAppLINEZaloTikTok

呼び出す前に

対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。

パラメーターの取得元
account_id
アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。 アカウント取得

リクエストパラメータ

ヘッダー

X-Api-Key
string必須

ワークスペース API キー。このヘッダーからワークスペースを特定します。

Content-Type
string必須

JSON のリクエストボディを送る場合は application/json を使用します。

パスパラメータ

account_id
string必須

authentication ルートで使用される識別子。

リクエストボディ

このエンドポイントは空の JSON オブジェクトを受け取ります。リクエスト例どおり {} を送信してください。

結果の確認

今回の認証操作について status/auth_status と返された auth_payload を確認します。利用者の操作が必要ならチャネルガイドに従います。authorized は認証完了を意味し、送信前には runtime_status の確認も必要です。

レスポンス awaiting_qr_scan

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "check_qr_auth",
    "status": "awaiting_qr_scan",
    "auth_status": "awaiting_qr_scan",
    "auth_payload": {
      "qr_code": "<QR_CODE>"
    }
  }
}

レスポンス passkey_required

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "check_qr_auth",
    "status": "passkey_required",
    "auth_status": "passkey_required",
    "auth_payload": {
      "type": "passkey",
      "public_key": {
        "challenge": "<BASE64URL_CHALLENGE>"
      }
    }
  }
}

レスポンスボディ

provider
string

チャネルの識別子です。後続の呼び出しでは返された値をそのまま使ってください。この API の値は以下の enum を参照してください。

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol

action
string

このリクエストで要求された操作。

status
string

現在の認可フロー状態。pending_auth、awaiting_qr_scan、awaiting_code、pending、passkey_required、passkey_pending、passkey_confirmation、passkey_confirmation_sent、authorized、failed など。

auth_status
string

現在の標準化された認証状態。例：awaiting_qr_scan、awaiting_code、passkey_required、authorized、failed。この値に応じて対象チャネルの認証フローを続けてください。

auth_payload
object

現在のステップに必要な標準ペイロード。QR は qr_code、認証コードステップは type=code、Passkey は type=passkey と public_key を使用します。相互排他的なステップのペイロードは同時には現れません。

type
string

現在のステップのペイロード種別。code は認証コードステップ、passkey は Passkey ステップを示します。

qr_code
string

auth_status が awaiting_qr_scan の場合にのみ表示する QR コンテンツ。

public_key
object

auth_status が passkey_required のときにブラウザーの credentials API へ渡す WebAuthn PublicKeyCredentialRequestOptions。

account_id
string

このレスポンスが対象とするプロバイダアカウント。

expires_at
string

現在の auth_payload が無効になる時刻の RFC3339 タイムスタンプ。

レスポンス

200

200 OK

リクエスト成功。レスポンスボディの例を参照してください。

400

Bad Request

リクエストボディ、パス、またはパラメータが不正です。

401

Unauthorized

X-Api-Key ヘッダが欠落しているか無効です。

403

Forbidden

リクエストは識別されましたが、この操作は許可されていません。

404

Not Found

要求されたリソースが見つかりません。error.code と現在の操作を合わせて確認してください。

409

Conflict

要求された操作が、既存のプロバイダアカウントまたはリソースと競合しています。

500

Internal Server Error

サービスで予期しないエラーが発生しました。

502

Bad Gateway

プロバイダアダプタまたは上流サービスが操作を完了できませんでした。

失敗時の対応

HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。 エラーリファレンス

HTTP ステータス、error.code、error.numeric_code を現在の操作と合わせて確認します。数値コードは文字列です。request_id は調査用で、冪等性キーやタスク ID ではありません。

invalid_request · 10000 · 400

JSON 本文と必須項目を確認してください。

対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。

JSON の例です。message は実際の原因によって変わります · 400 · 10000
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}
invalid_target_workspace · 11003 · 400

上書き対象のワークスペースが空、または形式が無効です。上書き用ヘッダーを削除し、対象ワークスペースの API Key を使用してください。

発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。

対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。

JSON の例です。message は実際の原因によって変わります · 400 · 11003
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}
provider_invalid_request · 30001 · 400

チャネル固有の項目と形式を確認してください。

対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。

JSON の例です。message は実際の原因によって変わります · 400 · 30001
{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}
unsupported_action · 30005 · 400

認識できないアカウント操作です。文書化された操作を使ってください。

対処と再試行: ドキュメントで対応しているチャネルと操作を選びます。同じリクエストを繰り返しても機能やベータ権限は追加されません。

JSON の例です。message は実際の原因によって変わります · 400 · 30005
{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_action",
    "numeric_code": "30005",
    "message": "Action not supported"
  }
}
invalid_api_key · 11001 · 401

API Key が正しく有効か確認してください。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

JSON の例です。message は実際の原因によって変わります · 401 · 11001
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}
missing_api_key · 11000 · 401

X-Api-Key ヘッダーを追加してください。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

例 · 401 · 11000
{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}
workspace_override_forbidden · 11002 · 403

この API Key に許可されていないワークスペースの上書きを要求しています。上書き用ヘッダーを削除し、対象ワークスペースの API Key を使用してください。

発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

JSON の例です。message は実際の原因によって変わります · 403 · 11002
{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}
target_workspace_not_found · 11004 · 404

上書きで指定したワークスペースが存在しないか利用できません。所有範囲を確認し、上書き用ヘッダーを削除して対象ワークスペースの API Key を使用します。再試行で権限は増えません。

発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。

対処と再試行: 対象の識別子、所有範囲、現在のワークスペースを確認します。不存在やアクセス不可が確認された対象を、一時的なサービス障害として自動再試行しないでください。

JSON の例です。message は実際の原因によって変わります · 404 · 11004
{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}
account_binding_not_found · 30006 · 409

有効なチャネル接続への紐付けがありません。アカウントの状態を確認してください。

対処と再試行: 認証と実行状態を照会し、目的の状態とチャネルの対応範囲に応じて更新・起動・再接続を選びます。接続の問題だけではログアウトしたとは判断できません。接続が必要な業務操作の前に running を確認してください。

JSON の例です。message は実際の原因によって変わります · 409 · 30006
{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}
duplicate_provider_account · 20015 · 409

同じチャネルのアカウントがこのワークスペース内ですでに接続されています。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

JSON の例です。message は実際の原因によって変わります · 409 · 20015
{
  "request_id": "req_example",
  "error": {
    "code": "duplicate_provider_account",
    "numeric_code": "20015",
    "message": "A provider account with the same identity already exists in this workspace"
  }
}
provider_account_mismatch · 20017 · 409

指定したチャネルの識別情報がアカウントの紐付けと一致しません。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

JSON の例です。message は実際の原因によって変わります · 409 · 20017
{
  "request_id": "req_example",
  "error": {
    "code": "provider_account_mismatch",
    "numeric_code": "20017",
    "message": "Authenticated provider account does not match the bound account; re-scan with the original account"
  }
}
provider_not_ready · 30009 · 409

接続が未準備です。認可と runtime_status を確認してから再試行を判断してください。

対処と再試行: 認証と実行状態を照会し、目的の状態とチャネルの対応範囲に応じて更新・起動・再接続を選びます。接続の問題だけではログアウトしたとは判断できません。接続が必要な業務操作の前に running を確認してください。

JSON の例です。message は実際の原因によって変わります · 409 · 30009
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}
provider_not_ready · 30014 · 409

このアカウントに必要なチャネルのインスタンスがありません。実行環境の可用性の問題であり、認証の期限切れを示すものではありません。

対処と再試行: 認証と実行状態を照会し、目的の状態とチャネルの対応範囲に応じて更新・起動・再接続を選びます。接続の問題だけではログアウトしたとは判断できません。接続が必要な業務操作の前に running を確認してください。

対象チャネル: WhatsApp

JSON の例です。message は実際の原因によって変わります · 409 · 30014
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30014",
    "message": "Provider instance is missing"
  }
}
provider_not_ready · 30015 · 409

チャネルの実行プロセスは停止しています。起動前に意図した停止かを確認してください。実行の停止自体はログアウトを意味しません。

対処と再試行: 認証と実行状態を照会し、目的の状態とチャネルの対応範囲に応じて更新・起動・再接続を選びます。接続の問題だけではログアウトしたとは判断できません。接続が必要な業務操作の前に running を確認してください。

対象チャネル: WhatsApp

JSON の例です。message は実際の原因によって変わります · 409 · 30015
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30015",
    "message": "Provider runtime is stopped"
  }
}
run_auth_action_failed · 20010 · 500

認証操作の実行：認証操作に失敗しました。再認証が必要と決めつけず、既存のフローを確認します。

対処と再試行: 現在の認証フローとユーザー操作の要否を確認します。この失敗だけを理由に認証を開始し直したり、期限切れ・終了済みセッションに再送信しないでください。

JSON の例です。message は実際の原因によって変わります · 500 · 20010
{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "20010",
    "message": "Failed to run auth action"
  }
}
run_auth_action_failed · 20020 · 500

account_id を確認し、アカウントが属するワークスペースの X-Api-Key を使います。このワークスペースにないアカウントには現在のキーでアクセスできません。

発生条件: アカウントが見つからない場合、従来の HTTP ステータスと操作の code を維持し、numeric_code でアカウントの不存在を示します。

対処と再試行: 対象の識別子、所有範囲、現在のワークスペースを確認します。不存在やアクセス不可が確認された対象を、一時的なサービス障害として自動再試行しないでください。

JSON の例です。message は実際の原因によって変わります · 500 · 20020
{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}
run_auth_action_failed · 30010 · 500

チャネルが操作を完了できませんでした。message に「Provider operation failed:」以降の元の原因が含まれる場合があります。原因の文面は可変で、安定したプログラムのインターフェースではありません。

発生条件: チャネルがより具体的な失敗分類を返さない場合、現在の操作のエラーを維持します。

対処と再試行: 現在の認証フローとユーザー操作の要否を確認します。この失敗だけを理由に認証を開始し直したり、期限切れ・終了済みセッションに再送信しないでください。

対象チャネル: WhatsApp

JSON の例です。message は実際の原因によって変わります · 500 · 30010
{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}
provider_adapter_not_found · 30004 · 502

チャネルサービスを利用できません。状態を確認するか後で再試行してください。書き込みは前回の結果を先に確認してください。

対処と再試行: 現在の認証フローとユーザー操作の要否を確認します。この失敗だけを理由に認証を開始し直したり、期限切れ・終了済みセッションに再送信しないでください。

JSON の例です。message は実際の原因によって変わります · 502 · 30004
{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}
provider_unavailable · 30002 · 502

チャネルサービスを利用できません。状態を確認するか後で再試行してください。書き込みは前回の結果を先に確認してください。

対処と再試行: 現在の認証フローとユーザー操作の要否を確認します。この失敗だけを理由に認証を開始し直したり、期限切れ・終了済みセッションに再送信しないでください。

例 · 502 · 30002
{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}
provider_unavailable · 30010 · 502

チャネルが操作を完了できませんでした。message に「Provider operation failed:」以降の元の原因が含まれる場合があります。原因の文面は可変で、安定したプログラムのインターフェースではありません。

対処と再試行: 現在の認証フローとユーザー操作の要否を確認します。この失敗だけを理由に認証を開始し直したり、期限切れ・終了済みセッションに再送信しないでください。

対象チャネル: WhatsApp

例 · 502 · 30010
{
  "request_id": "req_example_operation_failed",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30010",
    "message": "Provider operation failed: Example operation could not be completed"
  }
}
provider_unavailable · 30021 · 502

操作時に WhatsApp が接続されていませんでした。元の接続エラーメッセージを保持します。ログアウトや認証失効を示すものではなく、自動再接続・再送信・アカウント状態の更新も行いません。

対処と再試行: 接続が必要な業務操作を停止します。まず POST /v1/accounts/{account_id}/runtime/refresh を呼び、最新状態に従って復旧し、runtime_status=running を確認してから業務 API を実行します。再送前に前回の書き込み結果を確認してください。

対象チャネル: WhatsApp

例 · 502 · 30021
{
  "request_id": "req_example_connection_disconnected",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30021",
    "message": "example operation: websocket not connected"
  }
}