Q-A_test/apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/02-api-integration.md

sidebar_position, title, description

sidebar_position	title	description
2	API統合	ABC User Feedback APIを活用した外部システム統合方法と実際の実装例を案内します。

API統合

ABC User FeedbackはRESTful APIを通じて外部システムと統合できます。プログラムでフィードバックを収集し、イシューを管理し、データを照会できるため、既存のサービスやワークフローに簡単に統合できます。

---

API基本情報

公式APIドキュメント

ABC User Feedbackの完全なAPIドキュメントは次のリンクで確認できます：

🔗 公式APIドキュメント（Redocly）

このドキュメントでは、すべてのエンドポイントの詳細な仕様、リクエスト/レスポンス例、実際にテスト可能なインターフェースを提供します。

Base URL

https://your-domain.com/api

認証方式

すべてのAPIリクエストはAPIキーベースの認証を使用します。

X-API-KEY: your-api-key-here
Content-Type: application/json

:::warning セキュリティ注意事項 APIキーはサーバーサイドでのみ使用し、クライアント（ブラウザ、モバイルアプリ）に公開しないでください。 :::

APIキー発行方法

1. 管理者ページアクセス: ABC User Feedback管理者ページにログイン
2. プロジェクト設定: 該当プロジェクトの設定ページに移動
3. APIキー管理: 「APIキー管理」メニューから新しいAPIキーを生成
4. キーコピー: 生成されたAPIキーを安全な場所に保存

:::info APIキー権限 APIキーはプロジェクトごとに発行され、該当プロジェクトのデータにのみアクセスできます。 :::

---

主要APIエンドポイント例

1. フィードバック作成

基本フィードバック作成

const createFeedback = async (
  projectId,
  channelId,
  message,
  issueNames = []
) => {
  const response = await fetch(
    `/api/projects/${projectId}/channels/${channelId}/feedbacks`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "your-api-key-here",
      },
      body: JSON.stringify({
        message: message,
        issueNames: issueNames,
      }),
    }
  );

  return await response.json();
};

// 使用例
const feedback = await createFeedback(1, 1, "決済エラーが発生しました", [
  "決済",
  "エラー",
]);

2. フィードバック照会

チャネル別フィードバック検索

const searchFeedbacks = async (
  projectId,
  channelId,
  searchText,
  limit = 10,
  page = 1
) => {
  const response = await fetch(
    `/api/projects/${projectId}/channels/${channelId}/feedbacks/search`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "your-api-key-here",
      },
      body: JSON.stringify({
        limit: limit,
        page: page,
        query: {
          searchText: searchText,
          createdAt: {
            gte: "2024-01-01",
            lt: "2024-12-31",
          },
        },
        sort: {
          createdAt: "DESC",
        },
      }),
    }
  );

  return await response.json();
};

// 使用例
const feedbacks = await searchFeedbacks(1, 1, "決済", 20, 1);
console.log(
  `合計${feedbacks.meta.totalItems}件のフィードバック中${feedbacks.items.length}件を照会`
);

単一フィードバック照会

const getFeedbackById = async (projectId, channelId, feedbackId) => {
  const response = await fetch(
    `/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}`,
    {
      method: "GET",
      headers: {
        "X-API-KEY": "your-api-key-here",
      },
    }
  );

  return await response.json();
};

// 使用例
const feedback = await getFeedbackById(1, 1, 123);
console.log("フィードバック詳細:", feedback);

フィードバック更新

const updateFeedback = async (projectId, channelId, feedbackId, updateData) => {
  const response = await fetch(
    `/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}`,
    {
      method: "PUT",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "your-api-key-here",
      },
      body: JSON.stringify(updateData),
    }
  );

  return await response.json();
};

// 使用例
const updatedFeedback = await updateFeedback(1, 1, 123, {
  message: "更新されたフィードバック内容",
  issueNames: ["更新されたイシュー"],
});

フィードバック削除

const deleteFeedbacks = async (projectId, channelId, feedbackIds) => {
  const response = await fetch(
    `/api/projects/${projectId}/channels/${channelId}/feedbacks`,
    {
      method: "DELETE",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "your-api-key-here",
      },
      body: JSON.stringify({
        feedbackIds: feedbackIds,
      }),
    }
  );

  return await response.json();
};

// 使用例
const result = await deleteFeedbacks(1, 1, [123, 124, 125]);
console.log("削除完了:", result);

3. イシュー管理

イシュー作成

const createIssue = async (projectId, name, description) => {
  const response = await fetch(`/api/projects/${projectId}/issues`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "your-api-key-here",
    },
    body: JSON.stringify({
      name: name,
      description: description,
    }),
  });

  return await response.json();
};

// 使用例
const issue = await createIssue(
  1,
  "決済エラー",
  "ユーザーが決済過程でエラーを経験"
);

イシュー検索

const searchIssues = async (projectId, query = {}) => {
  const response = await fetch(`/api/projects/${projectId}/issues/search`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "your-api-key-here",
    },
    body: JSON.stringify({
      limit: 10,
      page: 1,
      query: query,
      sort: {
        createdAt: "DESC",
      },
    }),
  });

  return await response.json();
};

// 使用例
const issues = await searchIssues(1, { name: "決済" });

イシュー照会

const getIssueById = async (projectId, issueId) => {
  const response = await fetch(`/api/projects/${projectId}/issues/${issueId}`, {
    method: "GET",
    headers: {
      "X-API-KEY": "your-api-key-here",
    },
  });

  return await response.json();
};

// 使用例
const issue = await getIssueById(1, 123);
console.log("イシュー詳細:", issue);

イシュー更新

const updateIssue = async (projectId, issueId, updateData) => {
  const response = await fetch(`/api/projects/${projectId}/issues/${issueId}`, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "your-api-key-here",
    },
    body: JSON.stringify(updateData),
  });

  return await response.json();
};

// 使用例
const updatedIssue = await updateIssue(1, 123, {
  name: "更新されたイシュー名",
  description: "更新されたイシュー説明",
});

イシュー削除

const deleteIssues = async (projectId, issueIds) => {
  const response = await fetch(`/api/projects/${projectId}/issues`, {
    method: "DELETE",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "your-api-key-here",
    },
    body: JSON.stringify({
      issueIds: issueIds,
    }),
  });

  return await response.json();
};

// 使用例
const result = await deleteIssues(1, [123, 124, 125]);
console.log("イシュー削除完了:", result);

フィードバックにイシュー追加

const addIssueToFeedback = async (
  projectId,
  channelId,
  feedbackId,
  issueId
) => {
  const response = await fetch(
    `/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}/issues/${issueId}`,
    {
      method: "POST",
      headers: {
        "X-API-KEY": "your-api-key-here",
      },
    }
  );

  return await response.json();
};

// 使用例
const result = await addIssueToFeedback(1, 1, 123, 456);
console.log("イシュー追加完了:", result);

フィードバックからイシュー削除

const removeIssueFromFeedback = async (
  projectId,
  channelId,
  feedbackId,
  issueId
) => {
  const response = await fetch(
    `/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}/issues/${issueId}`,
    {
      method: "DELETE",
      headers: {
        "X-API-KEY": "your-api-key-here",
      },
    }
  );

  return await response.json();
};

// 使用例
const result = await removeIssueFromFeedback(1, 1, 123, 456);
console.log("イシュー削除完了:", result);

4. プロジェクトとチャネル情報

プロジェクト情報照会

const getProjectInfo = async (projectId) => {
  const response = await fetch(`/api/projects/${projectId}`, {
    method: "GET",
    headers: {
      "X-API-KEY": "your-api-key-here",
    },
  });

  return await response.json();
};

// 使用例
const project = await getProjectInfo(1);
console.log("プロジェクト情報:", project);

チャネルフィールド照会

const getChannelFields = async (projectId, channelId) => {
  const response = await fetch(
    `/api/projects/${projectId}/channels/${channelId}/fields`,
    {
      method: "GET",
      headers: {
        "X-API-KEY": "your-api-key-here",
      },
    }
  );

  return await response.json();
};

// 使用例
const fields = await getChannelFields(1, 1);
console.log("チャネルフィールド:", fields);

---

SwaggerによるAPIテスト

ABC User FeedbackはSwagger UIを提供して、APIを簡単にテストし理解できます。

Swaggerアクセス方法

**APIサーバーアドレス + /docs**でアクセスします：

https://your-domain.com/api/docs

またはReDoc形式で：

https://your-domain.com/api/docs/redoc

SwaggerでのAPIキー設定

1. Swagger UI上部の**"Authorize"**ボタンをクリック
2. X-API-KEYフィールドに発行されたAPIキーを入力
3. **"Authorize"**をクリックして認証完了

これ以降、すべてのAPIリクエストで自動的にAPIキーが含まれ、テストできます。

Swagger活用のヒント

• **"Try it out"**ボタンで実際のAPI呼び出しテスト
• Response bodyセクションで実際のレスポンスデータ構造を確認
• Schemaタブでリクエスト/レスポンスデータ形式の詳細を確認
• cURLコマンドを自動生成してCLIテスト可能

---

エラー処理と再試行ロジック

HTTPステータスコード

ステータスコード	意味	処理方法
200	成功	正常処理
400	不正なリクエスト	リクエストデータ検証
401	認証失敗	APIキー確認
403	権限なし	プロジェクトアクセス権限確認
404	リソースなし	ID値確認
429	リクエスト制限超過	しばらくしてから再試行
500	サーバーエラー	再試行またはサポートチームに問い合わせ

レスポンスデータ解析方法

ページネーションレスポンス構造

{
  "meta": {
    "itemCount": 10,
    "totalItems": 100,
    "itemsPerPage": 10,
    "totalPages": 10,
    "currentPage": 1
  },
  "items": [
    {
      "id": 1,
      "message": "フィードバック内容",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "issues": [
        {
          "id": 1,
          "name": "イシュー名"
        }
      ]
    }
  ]
}

セキュリティとパフォーマンス最適化

APIキーセキュリティ

• 環境変数使用: APIキーを環境変数で管理
• サーバーサイドのみ: クライアントにAPIキーを公開しない
• キーローテーション: 定期的なAPIキー交換
• IPホワイトリスト: 可能な場合は特定IPからのみアクセス許可

パフォーマンス最適化

• ページネーション活用: 大量データ照会時に適切なlimit設定
• 必要なフィールドのみリクエスト: クエリ最適化でレスポンス速度改善
• キャッシング戦略: 頻繁に照会するデータはクライアントサイドキャッシング
• バッチ処理: 複数のリクエストをまとめて処理

関連ドキュメント

• APIキー管理 - UIからAPIキーを発行する方法
• 画像設定 - 画像アップロードAPI使用のための設定
• Webhook統合 - APIと一緒に活用できるリアルタイム通知設定