受入 API

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

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

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

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

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

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

2.1 リクエストデータ構造

📂 リクエスト JSON（最上位）

💡 checkItems と products の指定ルール

• data[] ごとに、 checkItems と products のいずれか一方は必須です。両方未指定の場合は checkItems or products is required となります。
• products が指定されている場合、 data[] 直下の checkItems を指定して同時に送ってもdata[] 直下の checkItemsは無視され保存されません。

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

業者単位で点検する場合、または製品配列内の点検項目として使用します。 各要素は次のフィールドを持ちます。

2.3 products[]（製品別点検）の構造

製品別点検を行う場合の各要素の構造です。products 指定時の保存・判定ルールは 2.1 を参照してください。

2.4 リクエストJSONサンプル

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

{
  "data": [
    {
      "supplierName": "○○食品",
      "sender": "山田太郎",
      "isWitnessed": true,
      "deliveredAt": "2026/07/08 09:15",
      "checkItems": [
        {
          "content": "外観に異常がないか",
          "checkResult": "OK",
          "required": true
        },
        {
          "content": "包装に破損がないか",
          "checkResult": "OK",
          "required": false
        }
      ]
    }
  ]
}

🔹 製品別点検の場合

{
  "data": [
    {
      "supplierName": "△△物流",
      "sender": "佐藤花子",
      "isWitnessed": true,
      "deliveredAt": "2026/07/08 09:15",
      "products": [
        {
          "name": "鶏もも肉",
          "checkItems": [
            {
              "content": "品温",
              "checkResult": "3",
              "required": true
            }
          ]
        },
        {
          "name": "豚バラ肉",
          "checkItems": [
            {
              "content": "品温",
              "checkResult": "2",
              "required": true
            }
          ]
        }
      ]
    }
  ]
}

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

{
  "data": [
    {
      "supplierName": "○○食品",
      "sender": "山田太郎",
      "isWitnessed": true,
      "deliveredAt": "2026/07/08 09:15",
      "checkItems": [
        {
          "content": "外観に異常がないか",
          "checkResult": "OK",
          "required": true
        }
      ]
    },
    {
      "supplierName": "△△物流",
      "sender": "佐藤花子",
      "isWitnessed": true,
      "deliveredAt": "2026/07/08 09:20",
      "checkItems": [
        {
          "content": "外観に異常がないか",
          "checkResult": "OK",
          "required": true
        }
      ]
    }
  ]
}

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

本送信登録時、以下のいずれかに該当した場合は不整合データとみなされ、登録が拒否されるか件別に failed として返却されます。

1. 基本構造の不備 : リクエスト JSON 全体に data 配列が存在しない、または空配列である。配列要素が JSON オブジェクトでない。バッチ内のすべての要素が failed となった場合（例: すべて sender 未指定）も 400 となる。
2. 必須項目の欠落 : sender / supplierName / isWitnessed / deliveredAt が未指定、または空文字である。
3. 型・形式の不正 : sender / supplierName が string 以外、 isWitnessed が boolean 以外、 deliveredAt が YYYY/MM/DD HH:mm (JST) 形式でない、 checkItems / products が指定されているが配列でない。
4. 点検項目の指定不備 : checkItems と products の両方が未指定である。または required: true の点検項目で checkResult が未入力である（判定対象は 2.1 のとおり。 required: true でない項目の checkResult は空でも可）。
5. 保存失敗 : データベースへの保存処理が失敗した場合。

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

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

• data must not be empty
• data[0]: each item must be a JSON object
• data[0]: sender is required
• data[0]: sender must be a string
• data[0]: supplierName is required
• data[0]: supplierName must be a string
• data[0]: isWitnessed is required
• data[0]: isWitnessed must be a boolean
• data[0]: deliveredAt is required
• data[0]: deliveredAt must be YYYY/MM/DD HH:mm (JST)
• data[0]: checkItems must be an array
• data[0]: products must be an array
• data[0]: checkItems or products is required
• data[0]: required checkItems must have non-empty checkResult
• data[0]: required checkItems in products must have non-empty checkResult

💡 点検結果が NG になる場合について
点検項目の OK/NG が "NG" 、数値が許容範囲外、賞味期限が許容日数を超過するなどで、登録される点検結果は NG（異常あり） 扱いになります。 データの登録自体は成功しますが、点検結果上では異常ありとして扱われます。 1件でも NG 判定の項目があれば、そのレコード全体が NG 扱いになります。

2.6 POST レスポンス仕様

HTTPステータスコードは、全件成功の場合 200 、登録と失敗が混在する場合 207 Multi-Status 、全件失敗の場合 400 を返却します。

レスポンスボディ JSON例 (200 の場合・全件登録成功)

{
  "status": "success",
  "shopUID": "xxxxxxxxxxxxxxxxxxxx",
  "summary": {
    "requested": 2,
    "created": 2,
    "failed": 0
  },
  "results": [
    {
      "index": 0,
      "status": "success",
      "docId": "acceptance_doc_id_11111"
    },
    {
      "index": 1,
      "status": "success",
      "docId": "acceptance_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": "acceptance_doc_id_11111"
    },
    {
      "index": 1,
      "status": "failed",
      "error": "required checkItems must have non-empty checkResult"
    }
  ]
}

レスポンス JSON（最上位）

summary オブジェクト

results[] 要素

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

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

3.1 単一取得（docId 指定）

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

{
  "data": [
    {
      "id": "acceptance_doc_id_11111",
      "supplierName": "○○食品",
      "userUID": "API_COMMON_USER",
      "shopUID": "xxxxxxxxxxxxxxxxxxxx",
      "sender": "山田太郎",
      "isWitnessed": true,
      "isNormalForReport": true,
      "checkItems": [
        {
          "content": "外観に異常がないか",
          "inputType": "okng",
          "checkResult": "OK",
          "required": true
        },
        {
          "content": "品温",
          "inputType": "number",
          "checkResult": "4",
          "required": true
        }
      ],
      "deliveredAt": "2026/07/08 08:45",
      "registeredAt": "2026/07/08 00:00",
      "sentAt": "2026/07/08 09:16",
      "confirmedAt": "",
      "confirmerName": "",
      "approvedAt": "",
      "approverName": "",
      "createdAt": "2026/07/08 09:16",
      "updatedAt": "2026/07/08 09:16"
    }
  ]
}

3.2 一覧取得（date 指定）

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

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

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

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

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

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

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