清掃 API

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

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

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

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

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

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

2.1 リクエストデータ構造

2.2 checkItems[]（点検項目）の構造

2.3 リクエストJSONサンプル

{
    "data": [
      {
        "place": "漬魚",
        "sender": "山田太郎",
        "checkItems": [
          {
            "checkPoint1": "清掃手順",
            "checkPoint2": "",
            "checkContent": "使用器具の洗浄",
            "checkResult": "OK"
          },
          {
            "checkPoint1": "床面",
            "checkContent": "水洗い後の乾燥確認",
            "checkResult": "OK"
          }
        ]
      }
    ]
  }

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

1. 基本構造の不備 : リクエスト JSON 全体に data 配列が存在しない、または空配列である。
2. 必須項目の欠落 : place / sender が未指定または空文字、 checkItems が配列でない、または空配列である。
3. 必須点検項目の未入力 : required: true の項目で checkResult が空の場合は登録不可。
4. checkResult の値不正 : "OK" / "NG" / "" 以外の値が指定されている。

💡 日報用正常判定（isNormalForReport）
クライアントからの値は使わず、サーバー側で再計算します。 checkResult が "NG" の項目が1つでもあれば false 、それ以外（ "OK" / "" ）は正常扱いです。

2.5 POST レスポンス仕様

HTTPステータスコードは全体成功を示す 200 、一部成功を示す 207 Multi-Status 、全件失敗を示す 400 を返却します。

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

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

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

3.1 単一取得（docId 指定）

• Request: GET {baseUrl}?app=cleaning&docId=cleaning_doc_id_11111

{
    "data": [
      {
        "id": "cleaning_doc_id_11111",
        "userUID": "API_COMMON_USER",
        "shopUID": "xxxxxxxxxxxxxxxxxxxx",
        "place": "漬魚",
        "sender": "山田太郎",
        "checkItems": [
          {
            "checkPoint1": "清掃手順",
            "checkPoint2": "",
            "checkContent": "使用器具の洗浄",
            "checkResult": "OK"
          },
          {
            "checkPoint1": "床面",
            "checkPoint2": "",
            "checkContent": "水洗い後の乾燥確認",
            "checkResult": "OK"
          }
        ],
        "isNormalForReport": true,
        "registeredAt": "2026/07/15 00:00",
        "sentAt": "2026/07/15 09:16",
        "confirmedAt": "",
        "confirmerName": "",
        "approvedAt": "",
        "approverName": "",
        "createdAt": "2026/07/15 09:16",
        "updatedAt": "2026/07/15 09:16"
      }
    ]
  }

3.2 一覧取得（date 指定）

• GET {baseUrl}?app=cleaning&date=2026-07（月次一覧取得）
• GET {baseUrl}?app=cleaning&date=2026-07-15（日次一覧取得）

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

• 認証されたAPIキーに紐づく shopUID のデータのみに自動制限されます。
• データは 営業日順（registeredAt の昇順）、 同じ営業日内においては 清掃場所名順（place の昇順） でソートして返却されます。

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

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