API リファレンス

アカウント認可

QR 認証を開始

auth_mode=qrcode のプロバイダ向けに QR ログインフローを開始します。/auth をポーリングするか /auth/qr/check を呼んで QR の内容を取得します。一部のプロバイダでは、QR は同期レスポンスではなく webhook 経由で非同期に届きます。

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

対応チャネル

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 の確認も必要です。

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "status": "awaiting_qr_scan",
    "auth_payload": {
      "qr_code": "https://example.com/qr"
    },
    "expires_at": "2026-01-01T00:00:00Z"
  }
}

レスポンスボディ

account_id
string

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

provider
string

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

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 を使用します。相互排他的なステップのペイロードは同時には現れません。

expires_at
string

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

レスポンス

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

409

Conflict

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

500

Internal Server Error

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

502

Bad Gateway

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

失敗時の対応

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

invalid_request · 10000 · 400
必須項目、形式、チャネルの条件を確認して修正します。
missing_api_key · 11000 · 401
X-Api-Key とワークスペースの有効性を確認します。
invalid_api_key · 11001 · 401
X-Api-Key とワークスペースの有効性を確認します。
account_already_authorized · 20016 · 409
認可済みです。そのアカウントを使うか、新しい認可の前に現在の認可を解除してください。