システム連携

TWPと外部システムを連携する際のポイントを説明します。

連携方式

API連携

TWP公開APIを使用して、コンテンツ・問い合わせを外部システムと連携できます（API概要）。

• RESTful API
• JSON形式
• APIキー認証（X-API-Key）

AIクライアントからプロジェクト・タスク等を操作する場合は MCP連携 を使います。ターミナルやシェルスクリプトから操作する場合は TWP CLI を使います。

SSO連携

既存の認証基盤と連携して、シングルサインオンを実現できます。

• Microsoft 365（Microsoft Entra ID / 旧 Azure AD）
• Google Workspace

API連携のポイント

エラーハンドリング

API呼び出し時は、適切なエラーハンドリングを実装してください。

try {
  // API呼び出し
} catch (error) {
  if (error.status === 403) {
    // APIキー・権限・クレジット残高を確認（リトライしても解消しない）
  } else if (error.status === 429) {
    // 間隔を空けてリトライ
  }
}

エラーの種類ごとのレスポンスは エラーコード を参照してください。

リクエスト数の抑制

API呼び出しはクレジットを消費し、短時間に集中すると 429 が返ることがあります。以下の対策を推奨します。

• リクエストの間隔を空ける
• 必要なデータのみ取得
• キャッシュの活用

べき等性

POST/PUT/DELETEリクエストは、リトライ時に重複処理が発生しないよう考慮してください。

Webhook連携

TWPからのイベント通知を受け取ることができます。

送信先は「組織管理」→「テナント設定」の「Webhook設定」タブで登録します（管理者のみ・https のURLのみ）。

対応イベント

実装のポイント

• 署名検証を実装（X-TWP-Webhook-Signature ヘッダーに、リクエストボディの HMAC-SHA256 が sha256= 付きで入ります。鍵は送信先ごとの署名シークレットです）
• イベント種別は X-TWP-Webhook-Event、配信IDは X-TWP-Webhook-Delivery ヘッダーで判別できます
• 非同期処理を推奨
• 冪等性を考慮（失敗時は再送されるため、同じ配信IDを2回受け取ることがあります）

SSO連携

Microsoft 365

1. Microsoft Entra ID（旧 Azure AD）にアプリケーションを登録
2. TWPの「組織管理」→「テナント設定」→「認証連携」タブを開く
3. Microsoft 365 の欄にテナントID・クライアントID・クライアントシークレット・許可ドメインを入力して保存
4. 接続テストで設定を確認

Google Workspace

1. Google Cloud Consoleでプロジェクトを作成し、OAuth 2.0クライアントを設定
2. TWPの「組織管理」→「テナント設定」→「認証連携」タブを開く
3. Google Workspace の欄にクライアントID・クライアントシークレット・許可ドメインを入力して保存

外部認証を1つ以上有効にすると、パスワード認証を無効にすることもできます。

連携のテスト

開発環境の活用

本番環境に影響を与えないよう、開発環境でテストを行ってください。

テストデータ

テスト用のプロジェクト・タスクを作成し、連携の動作確認を行ってください。