異物探知 API

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

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

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

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

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

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

2.1 リクエストデータ構造

2.2 checkItems[]（作動確認項目）の構造

2.3 リクエストJSONサンプル

{
    "data": [
      {
        "productName": "黒蜜かわらけ８０ｇ",
        "machineName": "金属探知機１",
        "timing": "開始",
        "sender": "山田太郎",
        "detectionResult": "OK",
        "checkItems": [
          {
            "testPieceName": "Fe（鉄）",
            "testPieceSize": 1.5,
            "checkResult": "OK"
          },
          {
            "testPieceName": "SUS（ステンレス）",
            "testPieceSize": 2.0,
            "checkResult": "OK"
          }
        ]
      }
    ]
  }

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

1. 基本構造の不備 : リクエスト JSON 全体に data 配列が存在しない、または空配列である。
2. 必須項目の欠落 : productName / machineName / timing / sender / detectionResult が未指定または空文字、 checkItems が配列でない、または空配列である。
3. timing の値不正 : "開始" / "経過" / "終了" 以外の値が指定されている。
4. detectionResult / checkResult の値不正 : "OK" / "NG" 以外の値が指定されている。
5. 作動確認項目の不備 : testPieceName が空、 testPieceSize が数値として解釈できない。

💡 日報用正常判定（isNormalForReport）
クライアントからの値は使わず、サーバー側で再計算します。 checkItems のいずれかに "NG" がある、または detectionResult が "NG" の場合は false 、それ以外は true です。

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

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

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

3.1 単一取得（docId 指定）

• Request: GET {baseUrl}?app=metalDetector&docId=metal_detector_doc_id_11111

{
    "data": [
      {
        "id": "metal_detector_doc_id_11111",
        "userUID": "API_COMMON_USER",
        "shopUID": "xxxxxxxxxxxxxxxxxxxx",
        "productName": "黒蜜かわらけ８０ｇ",
        "machineName": "金属探知機１",
        "timing": "開始",
        "sender": "山田太郎",
        "detectionResult": "OK",
        "checkItems": [
          {
            "testPieceName": "Fe（鉄）",
            "testPieceSize": 1.5,
            "checkResult": "OK"
          },
          {
            "testPieceName": "SUS（ステンレス）",
            "testPieceSize": 2,
            "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=metalDetector&date=2026-07（月次一覧取得）
• GET {baseUrl}?app=metalDetector&date=2026-07-15（日次一覧取得）

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

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

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

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