メインコンテンツへ
BlueAI
BlueAIBlueAI API
JAEN
ホーム/ガイド/レスポンス形式

レスポンス形式

API レスポンスの標準エンベロープ構造。

|

概要

BlueAI API はすべてのエンドポイントで一貫したレスポンス形式を使用します。単一オブジェクト、リスト、エラーのそれぞれに標準エンベロープが定義されており、クライアント側で統一的に処理できます。すべてのフィールド名は snake_case で返されます。

単一オブジェクトのレスポンス

単一リソースを返すエンドポイント（GET /resource/:id、POST /resource など）は、リソースオブジェクトをそのまま返します。各オブジェクトには id と object フィールドが含まれます。

{
  "id": "deal_11111111111111111111111111111111",
  "object": "deal",
  "name": "Enterprise Contract",
  "amount": 1500000,
  "status": "open",
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-02-10T14:30:00Z"
}
FieldTypeDescription
idstringリソースの一意な識別子。プレフィックス付き（例: deal_xxxx, inv_xxxx）。
objectstringリソースの種類を示す文字列（例: "deal", "invoice"）。
created_atstringリソースの作成日時（ISO 8601 形式）。
updated_atstringリソースの最終更新日時（ISO 8601 形式）。

リストレスポンス

一覧を返すエンドポイントは、data 配列とページネーション情報を含む標準エンベロープで返します。

{
  "object": "list",
  "data": [
    {
      "id": "deal_11111111111111111111111111111111",
      "object": "deal",
      "name": "Enterprise Contract",
      "amount": 1500000,
      "status": "open"
    },
    {
      "id": "deal_22222222222222222222222222222222",
      "object": "deal",
      "name": "Starter Plan",
      "amount": 300000,
      "status": "won"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 142,
    "total_pages": 3
  }
}
FieldTypeDescription
objectstring常に "list" が設定されます。
dataarrayリソースオブジェクトの配列。
paginationobjectページネーションのメタ情報（page, per_page, total, total_pages）を含むオブジェクト。

エラーレスポンス

エラー発生時は error オブジェクトを含むレスポンスが返されます。すべてのエラーは一貫した構造に従います。

{
  "error": {
    "type": "invalid_request_error",
    "code": "required",
    "message": "name is required",
    "param": "name"
  }
}

422 Unprocessable Entity:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameters",
    "message": "One or more parameters are invalid",
    "errors": [
      {
        "field": "email",
        "code": "invalid_format",
        "message": "must be a valid email address"
      },
      {
        "field": "amount",
        "code": "out_of_range",
        "message": "must be greater than 0"
      }
    ]
  }
}
FieldTypeDescription
error.typestringエラーの分類（例: invalid_request_error, authentication_error）。
error.codestring機械可読なエラーコード（例: required, invalid_format）。
error.messagestring人間が読めるエラーの説明。
error.paramstring | nullエラーに関連するパラメータ名（該当する場合）。
error.errorsarray | nullバリデーションエラーの詳細配列（422 エラー時）。各要素は field, code, message を含みます。

HTTP ステータスコード

API は標準的な HTTP ステータスコードを使用して、リクエストの成否を示します。

ステータス意味説明
200OKリクエストが成功しました。レスポンスボディにリソースが含まれます。
201Createdリソースが正常に作成されました。レスポンスボディに作成されたリソースが含まれます。
204No Contentリクエストが成功しましたが、返すコンテンツがありません（DELETE 操作など）。
400Bad Requestリクエストボディまたはパラメータが無効です。
401Unauthorized有効なセッションまたは API キーが提供されていません。
403Forbidden認証済みですが、この操作を実行する権限がありません。
404Not Foundリクエストされたリソースが存在しません。
409Conflictリクエストが現在の状態と競合しています（例: 重複エントリ）。
422Unprocessable Entityリクエストは正しい形式ですが、セマンティックエラーを含んでいます。errors 配列にフィールドごとの詳細が含まれます。
429Too Many Requestsレートリミットを超過しました。レートリミットガイドを参照してください。
500Internal Server Errorサーバーで予期しないエラーが発生しました。しばらく時間をおいてから再試行してください。

命名規約

すべてのレスポンスフィールドは snake_case で返されます。リクエストボディも snake_case で送信してください。camelCase や PascalCase は使用しないでください。

Correct (snake_case)

{
  "company_name": "Acme Corp",
  "created_at": "2025-01-15T09:00:00Z",
  "total_amount": 1500000,
  "is_active": true
}

Incorrect (camelCase)

{
  "companyName": "Acme Corp",
  "createdAt": "2025-01-15T09:00:00Z",
  "totalAmount": 1500000,
  "isActive": true
}

使用例

# Fetch a single deal
curl https://api.blueai.jp/api/v1/crm/deals/deal_11111111111111111111111111111111 \
  -b cookies.txt
const res = await fetch(
  "https://api.blueai.jp/api/v1/crm/deals",
  { credentials: "include" },
);
const json = await res.json();

if (json.error) {
  // Error envelope
  console.error(json.error.type, json.error.message);
} else if (json.object === "list") {
  // List envelope
  for (const deal of json.data) {
    console.log(deal.id, deal.name);
  }
  console.log(`Total: ${json.pagination.total}`);
} else {
  // Single object
  console.log(json.id, json.name);
}