重要管理 API

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

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

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

• 確認済み結果の更新、データの削除
• 確認・承認フローの実行
• 特記事項（コメント）の取得・登録
• 本部点検票の紐づけ設定
• NG 時のメール通知
• メニューマスタの取得・更新

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

登録リクエストは他 API と同様に 常に data 配列 で送ります。
重要管理 API では data は必ず1件 です（複数日の一括送信は不可）。
店舗・営業日あたり1ドキュメントです。同一営業日へ再送信すると、未確認の結果を洗い替え更新します。 確認済み（ confirmerName が空でない）の結果は更新できません。
営業日（ registeredAt ）は店舗の閉店時刻を加味してサーバーが算出します（リクエストに含めても無視）。

2.1 リクエストデータ構造

2.2 分類（category01 〜 category05）

点検票の上から5枠です。分類名はリクエストに含めません。サーバーが次の固定名称を categoryName として保存します。

2.3 リクエストJSONサンプル

{
  "data": [
    {
      "sender": "山田太郎",
      "category01": {
        "checkResult": "OK",
        "courses": [
          {
            "courseName": "通常メニュー",
            "menus": [
              { "menuName": "サラダミックス", "remarks": "" }
            ]
          }
        ]
      },
      "category02": {
        "checkResult": "OK",
        "courses": [
          {
            "courseName": "通常メニュー",
            "menus": [
              { "menuName": "ハンバーグ", "remarks": "" }
            ]
          }
        ]
      },
      "category03": {
        "checkResult": "OK",
        "courses": [
          {
            "courseName": "通常メニュー",
            "menus": []
          }
        ]
      },
      "category04": {
        "checkResult": "OK",
        "courses": []
      },
      "category05": {
        "checkResult": "OK",
        "courses": []
      }
    }
  ]
}

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

1. 基本構造の不備 : data が無い、空配列、または2件以上。
2. 必須項目の欠落 : sender が未指定または空文字、 category01 〜 category05 のいずれかがオブジェクトでない。
3. checkResult の値不正 : "OK" / "NG" 以外。

💡 日報用正常判定（isNormalForReport）
クライアントからの値は使わず、サーバー側で再計算します。 5分類の checkResult に "NG" が1つでもあれば false 、すべて "OK" なら true です。

2.5 POST レスポンス仕様

HTTPステータスコードは全体成功を示す 200 、全件失敗を示す 400 を返却します。 data は1件のため、一部成功（ 207 ）にはなりません。

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

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

取得系APIにおいて、レスポンスに含まれるすべての日付・時刻フィールドは、 YYYY/MM/DD HH:mm の文字列形式に統一されて返却されます。 未確認・未承認の日時は空文字です。

3.1 単一取得（docId 指定）

• Request: GET {baseUrl}?app=criticalControl&docId=critical_control_doc_id_11111

{
  "data": [
    {
      "id": "critical_control_doc_id_11111",
      "userUID": "API_COMMON_USER",
      "shopUID": "xxxxxxxxxxxxxxxxxxxx",
      "sender": "山田太郎",
      "category01": {
        "categoryName": "非加熱のもの\n(冷蔵品を冷たいまま提供)",
        "checkResult": "OK",
        "courses": [
          {
            "courseName": "通常メニュー",
            "menus": [
              { "menuName": "サラダミックス", "remarks": "" },
              { "menuName": "チョップドサラダ", "remarks": "" }
            ]
          }
        ]
      },
      "category02": {
        "categoryName": "加熱するもの\n(冷蔵品を加熱し熱いまま提供)",
        "checkResult": "NG",
        "courses": [
          {
            "courseName": "通常メニュー",
            "menus": [
              { "menuName": "ハンバーグ", "remarks": "" }
            ]
          }
        ]
      },
      "category03": {
        "categoryName": "常温保管するもの",
        "checkResult": "OK",
        "courses": [
          {
            "courseName": "通常メニュー",
            "menus": [
              { "menuName": "パン", "remarks": "" }
            ]
          }
        ]
      },
      "category04": {
        "categoryName": "加熱後冷却し再加熱するもの",
        "checkResult": "OK",
        "courses": [
          {
            "courseName": "通常メニュー",
            "menus": []
          }
        ]
      },
      "category05": {
        "categoryName": "加熱後冷却するもの",
        "checkResult": "OK",
        "courses": [
          {
            "courseName": "通常メニュー",
            "menus": []
          }
        ]
      },
      "isNormalForReport": false,
      "registeredAt": "2026/08/20 00:00",
      "sentAt": "2026/08/20 09:16",
      "confirmedAt": "",
      "confirmerName": "",
      "approvedAt": "",
      "approverName": "",
      "createdAt": "2026/08/20 09:16",
      "updatedAt": "2026/08/20 09:16"
    }
  ]
}

3.2 一覧取得（date 指定）

• GET {baseUrl}?app=criticalControl&date=2026-08（月次一覧取得）
• GET {baseUrl}?app=criticalControl&date=2026-08-20（日次一覧取得）

date は YYYY/MM 、 YYYY/MM/DD 、ハイフン区切りのいずれも受け付けます。 範囲は管理画面の点検結果一覧と同じく、 registeredAt （点検日の 00:00）です。

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

• 認証されたAPIキーに紐づく shopUID のデータのみに自動制限されます。
• データは 点検日順（registeredAt の昇順） 、同じ点検日内においては 送信日時順（sentAt の昇順） でソートして返却されます。

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

3.4 分類（category01 〜 category05）

点検票と点検結果詳細の分類です。各分類の点検結果は checkResult （ "OK" / "NG" ）です。 コースとメニューは、送信時点のメニュー構成が結果に保存されています。