機械 API

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

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

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

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

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

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

2.1 リクエストデータ構造

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

2.3 リクエストJSONサンプル

{
    "data": [
      {
        "facilityName": "ミキサ",
        "sender": "山田太郎",
        "checkItems": [
          {
            "checkPoint1": "給油箇所",
            "checkPoint2": "",
            "checkContent": "給油グリス",
            "checkResult": "OK"
          },
          {
            "checkPoint1": "温度",
            "checkContent": "運転温度",
            "inputType": "number",
            "checkResult": 25,
            "allowableMin": 20,
            "allowableMax": 30,
            "unit": "℃"
          }
        ]
      }
    ]
  }

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

1. 基本構造の不備 : リクエスト JSON 全体に data 配列が存在しない、または空配列である。
2. 必須項目の欠落 : facilityName / sender が未指定または空文字、 checkItems が配列でない、または空配列である。
3. 必須点検項目の未入力 : required: true の項目で checkResult が空の場合は登録不可。
4. inputType の指定ミス : 数値項目で inputType が未指定、または "number" / "OKNG" 以外の値が指定されている。
5. 数値範囲設定の不整合 : inputType: "number" の項目で allowableMin と allowableMax の両方を指定する場合、 allowableMin <= allowableMax である必要があります。

💡 点検結果が NG になる場合について
checkResult が "NG" 、または数値が許容範囲外の場合、登録される点検結果は NG（異常あり） 扱いになります。 "未稼働" は正常扱いです。 データの登録自体は成功しますが、点検結果上では異常ありとして扱われます。 1件でも NG 判定の項目があれば、そのレコード全体が NG 扱いになります。

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": "facility_doc_id_11111"
      }
    ]
  }

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

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

3.1 単一取得（docId 指定）

• Request: GET {baseUrl}?app=facility&docId=facility_doc_id_11111

{
    "data": [
      {
        "id": "facility_doc_id_11111",
        "userUID": "API_COMMON_USER",
        "shopUID": "xxxxxxxxxxxxxxxxxxxx",
        "facilityName": "ミキサ",
        "sender": "山田太郎",
        "checkItems": [
          {
            "checkPoint1": "給油箇所",
            "checkPoint2": "",
            "checkContent": "給油グリス",
            "checkResult": "OK"
          },
          {
            "checkPoint1": "温度",
            "checkPoint2": "",
            "checkContent": "運転温度",
            "inputType": "number",
            "checkResult": 25,
            "allowableMin": 20,
            "allowableMax": 30,
            "unit": "℃"
          }
        ],
        "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=facility&date=2026-07（月次一覧取得）
• GET {baseUrl}?app=facility&date=2026-07-15（日次一覧取得）

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

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

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

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