third-party-integration

サードパーティ統合

目次

• 概要
• 使用する場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

API 呼び出し、エラー処理、認証、データ変換の標準化されたパターンを使用して、外部サービスとの堅牢な統合を構築します。

使用する場面

• 決済処理サービス（Stripe、PayPal）との統合
• メッセージングサービス（SendGrid、Twilio）の利用
• 分析プラットフォーム（Mixpanel、Segment）への接続
• ストレージサービス（AWS S3、Google Cloud）との同期
• CRM システム（Salesforce、HubSpot）との統合
• 複数サービスのアーキテクチャの構築

クイックスタート

最小限の動作例：

const axios = require("axios");

class ThirdPartyClient {
  constructor(config) {
    this.apiKey = config.apiKey;
    this.baseUrl = config.baseUrl;
    this.timeout = config.timeout || 30000;
    this.retryAttempts = config.retryAttempts || 3;
    this.retryDelay = config.retryDelay || 1000;
    this.client = axios.create({
      baseURL: this.baseUrl,
      timeout: this.timeout,
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        "Content-Type": "application/json",
      },
    });
  }

  async request(method, endpoint, data = null, options = {}) {
    let lastError;

    for (let attempt = 0; attempt < this.retryAttempts; attempt++) {
      try {
        const response = await this.client({
// ... (see reference guides for full implementation)

リファレンスガイド

詳細な実装については、references/ ディレクトリを参照してください。

ガイド	内容
サードパーティクライアントラッパー	サードパーティクライアントラッパー
決済処理サービスとの統合（Stripe）	決済処理サービスとの統合（Stripe）
メールサービスとの統合（SendGrid）	メールサービスとの統合（SendGrid）
Python サードパーティ統合	Python サードパーティ統合
データ変換	データ変換

ベストプラクティス

✅ 推奨事項

• 指数バックオフを使用したリトライロジックを実装します
• Webhook の署名を検証します
• すべての API 操作をログに記録します
• シークレットには環境変数を使用します
• API のレスポンスを内部モデルに変換します
• 重要なサービスにはサーキットブレーカーを実装します
• API のクォータとレート制限を監視します
• 適切なエラー処理を追加します
• タイムアウトを適切に設定します
• サンドボックス／テスト用の API キーを使ってテストします

❌ 禁止事項

• API キーをハードコードします
• あらゆるエラーに対して無期限にリトライします
• 機密データをログに記録します
• 検証されていない Webhook データを信頼します
• レート制限を無視します
• 同期的なブロッキング呼び出しを行います
• ベンダー固有の詳細をクライアントに公開します
• エラー処理を省略します
• テストで本番用キーを使用します