庫内温度 API

庫内温度 （ app=fridge ）の点検結果を扱う API の仕様です。
共通の認証・ベースURLは 基本情報・認証仕様 を参照してください。

1. 🗺️ エンドポイント一覧

⚠️ 非対応スコープ（制限事項）
以下の操作およびデータ連携には対応していません。

• 送信後の修正、データの削除
• 確認・承認フローの実行
• 特記事項（コメント）の登録
• 本部点検票の紐づけ設定
• 位置情報の登録
• NG 時のメール通知
• 冷蔵庫マスタの取得・更新

2. 📥 POST: 点検結果の登録

登録リクエストは、複数件の一括処理（バッチ処理）を考慮し、 常に data 配列で統一 します。
1件のみ登録する場合であっても、要素数が1の配列として送信してください。

2.1 リクエストデータ構造

2.2 リクエストJSONサンプル

🔹 1件のみ登録する場合（配列の要素数が1）

{
  "data": [
    {
      "fridgeName": "厨房冷蔵庫A",
      "sender": "点検太郎",
      "settingTemperature": 4,
      "allowableMin": 0,
      "allowableMax": 6,
      "temperature": 4.5,
      "checkTime": "09:15"
    }
  ]
}

🔹 複数件を一括登録する場合（配列の要素数が2以上）

{
  "data": [
    {
      "fridgeName": "厨房冷蔵庫A",
      "sender": "点検太郎",
      "settingTemperature": 4,
      "allowableMin": 0,
      "allowableMax": 6,
      "temperature": 4.5,
      "checkTime": "09:15"
    },
    {
      "fridgeName": "厨房冷蔵庫B",
      "sender": "点検太郎",
      "settingTemperature": -20,
      "allowableMin": "",
      "allowableMax": -15,
      "temperature": "DF",
      "checkTime": "09:20"
    }
  ]
}

2.3 入力バリデーションルール

本送信登録時、以下のいずれかに該当した場合は不整合データとみなされ、対象レコードの登録が拒否されます。

1. 基本構造の不備: リクエスト JSON 全体に data 配列が存在しない、または空配列である。
2. 必須項目の欠落: 配列内の各オブジェクトにおいて、fridgeName または sender が指定されていない、もしくは空文字（スペースのみ含む）である。

📋 バリデーションエラーメッセージ例 ( results[].error )

失敗時は、原因特定を容易にするため JSONパス付き のメッセージが返却されます。

• data must be a non-empty array
• data[0]: fridgeName is required
• data[0]: sender is required
• data[1]: fridgeName is required

💡 点検結果が NG になる場合について
庫内温度が管理限界（許容範囲）を外れると、登録される点検結果は NG（異常あり） 扱いになります。 データの登録自体は成功しますが、点検結果上では異常ありとして扱われます。 1件でも NG 判定の項目があれば、そのレコード全体が NG 扱いになります。

2.4 POST レスポンス仕様

HTTPステータスコードは全体成功を示す 200 、または一部成功・一部失敗が混在することを示す 207 Multi-Status を返却します。

レスポンスボディ JSON例 (200 の場合)

{
  "status": "success",
  "shopUID": "xxxxxxxxxxxxxxxxxxxx",
  "summary": {
    "requested": 2,
    "created": 2,
    "failed": 0
  },
  "results": [
    {
      "index": 0,
      "status": "success",
      "docId": "fridge_doc_id_11111"
    },
    {
      "index": 1,
      "status": "success",
      "docId": "fridge_doc_id_22222"
    }
  ]
}

レスポンスボディ JSON例 (207 Multi-Status の場合)

{
  "status": "partial_success",
  "shopUID": "xxxxxxxxxxxxxxxxxxxx",
  "summary": {
    "requested": 2,
    "created": 1,
    "failed": 1
  },
  "results": [
    {
      "index": 0,
      "status": "success",
      "docId": "fridge_doc_id_11111"
    },
    {
      "index": 1,
      "status": "failed",
      "error": "fridgeName is required"
    }
  ]
}

レスポンス JSON（最上位）

summary オブジェクト

results[] 要素

3. 📤 GET: 点検結果の取得

取得系APIにおいて、レスポンスに含まれるすべての日付・時刻フィールドは、 YYYY/MM/DD HH:mm の文字列形式に統一されて返却されます（例: "2026/05/27 09:15" ）。

3.1 単一取得（docId 指定）

• Request: GET {baseUrl}?app=fridge&docId=fridge_doc_id_11111
• Response (200 OK):

{
  "data": [
    {
      "id": "fridge_doc_id_11111",
      "fridgeName": "厨房冷蔵庫A",
      "userUID": "API_COMMON_USER",
      "shopUID": "xxxxxxxxxxxxxxxxxxxx",
      "settingTemperature": 4,
      "allowableMin": 0,
      "allowableMax": 6,
      "temperature": 4.5,
      "checkTime": "09:15",
      "isNormalForReport": true,
      "sender": "点検太郎",
      "registeredAt": "2026/06/24 00:00",
      "sentAt": "2026/06/24 09:16",
      "confirmedAt": "",
      "confirmerName": "",
      "approvedAt": "",
      "approverName": "",
      "createdAt": "2026/06/24 09:16",
      "updatedAt": "2026/06/24 09:16"
    }
  ]
}

3.2 一覧取得（date 指定）

一覧取得では日付範囲で絞り込むため、docId 未指定時は date パラメータの指定が必須です。

• Request:
• GET {baseUrl}?app=fridge&date=2026-06 (月次一覧取得)
• GET {baseUrl}?app=fridge&date=2026-06-24 (日次一覧取得)
• Response (200 OK):

/* 3.1と同じ内容のため割愛 */

💡 サーバー側での自動フィルタリング・ソート規則

• 認証されたAPIキーに紐づく shopUID のデータのみに自動制限されます。他店舗の docId を指定してリクエストを送信した場合、403 Forbidden が返却されます。
• データは 営業日順（registeredAt の昇順）、 同じ営業日内においては 冷蔵庫名順（fridgeName の昇順） でソートして返却されます。

3.3 🗂️ 点検結果オブジェクト詳細定義（GETレスポンス）

単一取得のレスポンス、および一覧取得の data[] 配列に含まれる各点検結果オブジェクトの完全なフィールド仕様です。