個人衛生 API

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

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

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

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

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

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

2.1 リクエストデータ構造

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

入力タイプとパラメータの対応

体温（formType: "temperature"）の abnormalValue 登録値

数値で送信した NG 閾値は 35.0 〜 37.5 の範囲で変換して登録されます（GET レスポンスでも同じ数値が返ります）。

体温（formType: "temperature"）の checkResult 登録値

数値で送信した体温は、次のルールに従って登録されます（GET レスポンスでも同じ文字列が返ります）。

💡 点検結果が NG になる場合について
OK/NG が "NG" 、体温が閾値以上などで、登録される点検結果は NG（異常あり） 扱いになります（上記の判定表を参照）。 データの登録自体は成功しますが、点検結果上では異常ありとして扱われます。 1件でも NG 判定の項目があれば、そのレコード全体が NG 扱いになります。

2.3 リクエストJSONサンプル

{
  "data": [
    {
      "position": "キッチン",
      "name": "山田太郎",
      "isHelp": false,
      "checkItems": [
        {
          "content": "下痢、嘔吐、発熱などの症状はないか",
          "formType": "okng",
          "checkResult": "OK"
        },
        {
          "content": "手指や顔面に化膿創はないか",
          "formType": "okng",
          "checkResult": "OK"
        },
        {
          "content": "体温",
          "formType": "temperature",
          "abnormalValue": 37.5,
          "checkResult": 36.5
        },
        {
          "content": "手洗いを正しく実施しましたか？",
          "formType": "checkbox",
          "checkResult": true
        }
      ]
    }
  ]
}

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

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

1. 基本構造の不備 : リクエスト JSON 全体に data 配列が存在しない、または空配列である。
2. 必須項目の欠落 : position / name が未指定または空文字、 isHelp が未指定である。
3. 型の不正 : isHelp が boolean 以外である。
4. checkItems の不備 : checkItems が配列でない、空配列、要素がオブジェクトでない、 content / formType が不正である。
5. 体温項目の不正 : abnormalValue 未指定・数値型でない、または checkResult が未指定・数値型でない・有効な体温範囲外である。

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

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

• data must not be empty
• data[0]: position is required
• data[0]: name is required
• data[0]: isHelp is required
• data[0]: checkItems must be an array
• data[0]: checkItems must not be empty
• data[0]: checkItems[0] must be an object
• data[0]: checkItems[0].content must be a string
• data[0]: checkItems[0].formType must be "okng", "temperature", or "checkbox"
• data[0]: checkItems[0].abnormalValue is required when checkItems[0].formType is "temperature"
• data[0]: checkItems[0].abnormalValue must be a number when checkItems[0].formType is "temperature"
• data[0]: checkItems[0].checkResult must not be empty when checkItems[0].formType is "temperature"
• data[0]: checkItems[0].checkResult must be a number when checkItems[0].formType is "temperature"
• data[0]: checkItems[0].checkResult must be a valid temperature value (e.g. 36.5)

2.5 POST レスポンス仕様

HTTPステータスは全件成功 200 、全件失敗 400 、混在時 207 Multi-Status です。

レスポンスボディ JSON例 (200)

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

レスポンスボディ JSON例 (207)

{
  "status": "partial_success",
  "shopUID": "xxxxxxxxxxxxxxxxxxxx",
  "summary": {
    "requested": 2,
    "created": 1,
    "failed": 1
  },
  "results": [
    {
      "index": 0,
      "status": "success",
      "docId": "hygiene_doc_id_11111"
    },
    {
      "index": 1,
      "status": "failed",
      "error": "name is required"
    }
  ]
}

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

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

3.1 単一取得（docId 指定）

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

{
  "data": [
    {
      "id": "hygiene_doc_id_11111",
      "userUID": "API_COMMON_USER",
      "shopUID": "xxxxxxxxxxxxxxxxxxxx",
      "position": "キッチン",
      "name": "山田太郎",
      "employeeNumber": "API",
      "isHelp": false,
      "checkItems": [
        {
          "content": "下痢、嘔吐、発熱などの症状はないか",
          "formType": "okng",
          "checkResult": "OK"
        },
        {
          "content": "手指や顔面に化膿創はないか",
          "formType": "okng",
          "checkResult": "OK"
        },
        {
          "content": "体温",
          "formType": "temperature",
          "abnormalValue": 37.5,
          "checkResult": "36.5"
        },
        {
          "content": "手洗いを正しく実施しましたか？",
          "formType": "checkbox",
          "checkResult": true
        }
      ],
      "isNormalForReport": true,
      "registeredAt": "2026/07/15 00:00",
      "answeredAt": "2026/07/15 09:16",
      "confirmedAt": "",
      "confirmerName": "",
      "approvedAt": "",
      "approverName": "",
      "createdAt": "2026/07/15 09:16",
      "updatedAt": "2026/07/15 09:16"
    }
  ]
}

3.2 一覧取得（date 指定）

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

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

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

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

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

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

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