# 姿勢ナビ Company API（β）— 公開用 OpenAPI
# β版です。予告なく仕様を変更する場合があります。
# 出典: posture docs/company_api/openapi.yaml @ 3af5b1e7（lp-new/scripts/sync-company-api.mjs で生成。手で編集しない）
# 人向けの説明: https://shiseinavi.com/docs/api
openapi: 3.0.3
info:
  title: 姿勢ナビ Company API
  version: "1.0.0-beta"
  description: |
    **β版です。予告なく仕様を変更する場合があります。**

    店舗（企業）が事業者設定「API連携」で発行したキーで、自社システムや AI から姿勢ナビを操作する API。
    読み取り（顧客・診断・設定・集計）、顧客・設定・診断（日付）の書き込み、埋め込み URL の発行、
    ヘッドレス分析（POST /v1/examinations。写真 2 枚を送るとサーバーが骨格検出から AI アドバイスまで行う）と
    完了・失敗の Webhook（署名付き）を提供する。

    - 認証: `Authorization: Bearer snv_<8文字>_<64桁>`。テナント（企業）はキーから一意に決まる
    - 実行時の権限 = キーのスコープ ∩ 発行スタッフの現在のロールで許されるスコープ
    - エラーは RFC 9457 `application/problem+json`
    - 流量（認証後に検証済みのキー・企業で数える）: キーごと 120 回/分・5,000 回/日、企業ごと合計 600 回/分。
      集計（/v1/reports/*）は別枠でキーごと 30 回/分。認証前は IP ごと 300 回/分。
      認証失敗は IP ごと 20 回/分（超過後 1 分間はすべて 429）。超過は 429 + `Retry-After`
    - 企業がメンテナンス中は読み取りも含めて 503（`maintenance`）
    - 一覧はカーソル方式: `?limit=`（1〜100、既定 20）と `?cursor=`（前回の `next_cursor` をそのまま）。
      並びは `updated_at` の新しい順（同時刻は id の大きい順）。`next_cursor` が null なら最後
    - 詳細は強い `ETag`（`"<32 桁の hex>"`、`W/` なし）を返す。`If-None-Match` が完全一致すれば 304
    - 日時は ISO 8601（UTC、末尾 `Z`）、日付は `YYYY-MM-DD`
    - 担当店舗が限定されたスタッフが発行したキーは、その店舗のデータだけ扱える（他店舗は 404 / 422）
    - 自由記述（メモ・プロンプト・トークガイド）は返さない
    - 書き込みの作法
      - 作成（POST）: `Idempotency-Key`（任意。最大 255 文字・24 時間保持）。同じキー・同じ本文の再送は保存した応答を
        `Idempotent-Replayed: true` 付きで返す（2xx・4xx のみ保存）。処理中は 409 `operation_in_progress`、
        同じキーで本文が違えば 422 `idempotency_key_reused`。5xx のあとは期限まで 409 のまま（結果不明を未実行とみなさない）
      - 更新（PATCH）: `If-Match` 必須（無ければ 428 `precondition_required`）。値は直前の GET / PATCH の `ETag` を
        そのまま（完全一致。`W/` や `*` は不可）。他で更新されていれば 412 `precondition_failed`
      - 削除（DELETE）: 論理削除。204
      - 本文は JSON（`Content-Type: application/json`）。ここに無い項目は受け取らない（無視）

servers:
  - url: https://posture-api.shiseinavi.com
    description: 本番（パスは /v1/...。/api プレフィックスはない）
security:
  - bearerAuth: []
paths:
  /v1/ping:
    get:
      summary: 疎通確認
      description: キーが有効か、どの企業・スコープ・店舗範囲で動くかを返す。スコープ不要。
      operationId: ping
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Ping" }
              example:
                data:
                  company: { uid: CP12345678, name: 株式会社サンプル }
                  scopes: ["read:clients", "read:examinations"]
                  shop_uids: null
                  key: { uid: AK12345678, name: 会員アプリ連携 }
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/clients:
    get:
      summary: 顧客一覧
      description: スコープ `read:clients`。
      operationId: listClients
      tags: [clients]
      parameters:
        - { name: external_id, in: query, schema: { type: string }, description: 外部システムの顧客 ID（完全一致） }
        - { name: email, in: query, schema: { type: string }, description: 完全一致 }
        - { name: phone_number, in: query, schema: { type: string }, description: 完全一致 }
        - { name: name, in: query, schema: { type: string }, description: 部分一致 }
        - { name: shop_uid, in: query, schema: { type: string }, description: 所属店舗。見えない店舗・存在しない店舗は 422 }
        - $ref: "#/components/parameters/UpdatedSince"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [data, next_cursor]
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/Client" } }
                  next_cursor: { $ref: "#/components/schemas/NextCursor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
    post:
      summary: 顧客の登録
      description: |
        スコープ `write:clients`。`shop_uid` を省くと見える店舗の先頭に登録する。
        `external_id` が既存の顧客と重なれば 409 `conflict`。`Idempotency-Key` で再送を安全にできる。
      operationId: createClient
      tags: [clients]
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ClientInput" }
            example: { name: 山田太郎, email: taro@example.com, external_id: EXT-001, shop_uid: SH12345678 }
      responses:
        "201":
          description: 作成した顧客
          headers:
            Location: { $ref: "#/components/headers/Location" }
            ETag: { $ref: "#/components/headers/ETag" }
            Idempotent-Replayed: { $ref: "#/components/headers/IdempotentReplayed" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Client" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
  /v1/clients/{uid}:
    get:
      summary: 顧客詳細
      description: |
        スコープ `read:clients`。`{uid}` で見つからなければ `?external_id=` で引く
        （external_id だけで引くときは `{uid}` に `-` を置く: `/v1/clients/-?external_id=EXT-001`）。
      operationId: getClient
      tags: [clients]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
        - { name: external_id, in: query, schema: { type: string } }
        - $ref: "#/components/parameters/IfNoneMatch"
      responses:
        "200":
          description: OK
          headers: { ETag: { $ref: "#/components/headers/ETag" } }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Client" }
        "304": { $ref: "#/components/responses/NotModified" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
    patch:
      summary: 顧客の更新
      description: |
        スコープ `write:clients`。渡した項目だけ更新する（`null` を渡せば空にする）。`shop_uid` で店舗を移せる（見える店舗のみ）。
        `If-Match` 必須。
      operationId: updateClient
      tags: [clients]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ClientInput" }
      responses:
        "200":
          description: 更新後の顧客（新しい ETag 付き）
          headers: { ETag: { $ref: "#/components/headers/ETag" } }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Client" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "428": { $ref: "#/components/responses/PreconditionRequired" }
    delete:
      summary: 顧客の削除（論理削除）
      description: スコープ `write:clients`。
      operationId: deleteClient
      tags: [clients]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
      responses:
        "204": { description: 削除した }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/clients/{uid}/embed_tokens:
    post:
      summary: 埋め込み URL の発行
      description: |
        スコープ `embed`。顧客の診断画面（`scan`）・マイページ（`mypage`。閲覧のみで診断の作成・更新はできない）・
        診断結果（`result`。`examination_uid` 必須）を開く 30 分・1 回限りのログイン URL を返す。
        ログイン後の画面は 30 分有効で、発行元キーの失効・発行スタッフの停止・顧客の担当外への移動で止まる。
        埋め込みは新規タブ／リダイレクトを推奨（iframe は検証中）。
      operationId: createEmbedToken
      tags: [embed]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/EmbedTokenRequest" }
            example: { kind: scan }
      responses:
        "201":
          description: 発行した URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/EmbedToken" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
  /v1/clients/{uid}/examinations:
    get:
      summary: 顧客の診断一覧
      description: スコープ `read:examinations`。条件は `/v1/examinations` と同じ（client_uid を除く）。
      operationId: listClientExaminations
      tags: [examinations]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
        - $ref: "#/components/parameters/From"
        - $ref: "#/components/parameters/To"
        - $ref: "#/components/parameters/AnalysisPurpose"
        - $ref: "#/components/parameters/AnalysisStatus"
        - $ref: "#/components/parameters/UpdatedSince"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200": { $ref: "#/components/responses/ExaminationList" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
  /v1/examinations:
    get:
      summary: 診断一覧（企業横断）
      description: スコープ `read:examinations`。from / to は診断日（date）。
      operationId: listExaminations
      tags: [examinations]
      parameters:
        - { name: shop_uid, in: query, schema: { type: string } }
        - { name: client_uid, in: query, schema: { type: string }, description: 見えない顧客・存在しない顧客は 422 }
        - $ref: "#/components/parameters/From"
        - $ref: "#/components/parameters/To"
        - $ref: "#/components/parameters/AnalysisPurpose"
        - $ref: "#/components/parameters/AnalysisStatus"
        - $ref: "#/components/parameters/UpdatedSince"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200": { $ref: "#/components/responses/ExaminationList" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
    post:
      summary: ヘッドレス新規分析（写真 2 枚を送って分析を依頼）
      description: |
        スコープ `write:examinations`。**`Idempotency-Key` 必須**（無ければ 400 `idempotency_key_required`）。
        受け付けると 202 を返し、サーバー側で骨格検出 → 骨格線の描画 → 解析 → 採点 → AI アドバイス（任意）を順に行う。
        進捗は `GET /v1/examinations/{uid}`（`Location` / `poll_url`）の `analysis_status`（pending → processing → completed | failed）で確認する。
        `analysis_checkpoint` は完了した工程（predict_front / predict_side / render / analyze / score / ai_advice / done）、
        失敗時は `analysis_error_stage` に失敗した工程が入る。

        分析は撮影画面と同じ 3:4（480×640）の黒帯つきの枠に写真を収めて行い、`image_url` / `shot_image_url` はその枠の画像です。縦長・横長の写真は黒帯が入ります（元の写真の解像度は保持されません）。

        受付時に店舗の月間分析回数と企業の AI アドバイス残数を予約する（分析が失敗・削除されても戻らない。画面の撮影と同じ扱い）。
        `enable_ai_advice: true` でも企業が AI アドバイスを使わない設定なら `ai_advice: disabled`、残数が 0 なら AI 無しで受け付けて
        `ai_advice: skipped_no_stock` になる。

        完了・失敗時はキーに設定した Webhook URL（または本リクエストの `webhook_url`）へ署名付きで POST する（README「Webhook」）。
        流量はキーごと 10 回/分（全体の 120 回/分にも数える）。
      operationId: createExamination
      tags: [examinations]
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema: { $ref: "#/components/schemas/ExaminationCreateRequest" }
            encoding:
              images[standing]: { contentType: image/jpeg, image/png }
              images[standing_side]: { contentType: image/jpeg, image/png }
      responses:
        "202":
          description: 受け付けた（分析はこれから）
          headers:
            Location: { $ref: "#/components/headers/Location" }
            Idempotent-Replayed: { $ref: "#/components/headers/IdempotentReplayed" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/ExaminationAccepted" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403":
          description: スコープ不足（`insufficient_scope`）、またはプランで診断を作れない（`plan_inactive`。トライアル期限切れなど）
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/Problem" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "429": { $ref: "#/components/responses/AnalysisTooManyRequests" }
  /v1/examinations/{uid}:
    get:
      summary: 診断詳細
      description: |
        スコープ `read:examinations`。スコア・グレード・判定項目・AI アドバイス本文・スキャン画像 URL・分析状況。
        画像 URL は署名付きで 10 分ほどで失効する（必要になったら取り直す）。
        メモ・社内メモ・トークガイド・AI へのプロンプトは返さない。
      operationId: getExamination
      tags: [examinations]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
        - $ref: "#/components/parameters/IfNoneMatch"
      responses:
        "200":
          description: OK
          headers: { ETag: { $ref: "#/components/headers/ETag" } }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Examination" }
        "304": { $ref: "#/components/responses/NotModified" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
    patch:
      summary: 診断の更新（日付のみ）
      description: |
        スコープ `write:examinations`。v1 で変えられるのは `date` だけ。`analysis_purpose` / `threshold_level_id` は
        保存済みのスコアと整合しなくなるため変更できない（渡すと 422 `read_only`）。`If-Match` 必須。
      operationId: updateExamination
      tags: [examinations]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ExaminationInput" }
            example: { date: "2026-10-03" }
      responses:
        "200":
          description: 更新後の診断（新しい ETag 付き）
          headers: { ETag: { $ref: "#/components/headers/ETag" } }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Examination" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "428": { $ref: "#/components/responses/PreconditionRequired" }
    delete:
      summary: 診断の削除（論理削除）
      description: スコープ `write:examinations`。
      operationId: deleteExamination
      tags: [examinations]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
      responses:
        "204": { description: 削除した }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/company:
    get:
      summary: 企業情報
      description: スコープ `read:settings`。
      operationId: getCompany
      tags: [settings]
      parameters:
        - $ref: "#/components/parameters/IfNoneMatch"
      responses:
        "200":
          description: OK
          headers: { ETag: { $ref: "#/components/headers/ETag" } }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Company" }
        "304": { $ref: "#/components/responses/NotModified" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    patch:
      summary: 企業設定の更新
      description: |
        スコープ `write:settings`（企業管理者・オーナーのキーだけ）。受け取るのは `CompanyInput` の項目だけで、
        プロンプト・決済・API の有効/無効は変えられない。`If-Match` 必須。
      operationId: updateCompany
      tags: [settings]
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CompanyInput" }
      responses:
        "200":
          description: 更新後の企業情報（新しい ETag 付き）
          headers: { ETag: { $ref: "#/components/headers/ETag" } }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Company" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "428": { $ref: "#/components/responses/PreconditionRequired" }
  /v1/shops:
    get:
      summary: 店舗一覧
      description: スコープ `read:settings`。有効な店舗を id 順に全件（ページングなし、`next_cursor` は常に null）。
      operationId: listShops
      tags: [settings]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/Shop" } }
                  next_cursor: { $ref: "#/components/schemas/NextCursor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /v1/shops/{uid}:
    get:
      summary: 店舗詳細
      description: スコープ `read:settings`。
      operationId: getShop
      tags: [settings]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
        - $ref: "#/components/parameters/IfNoneMatch"
      responses:
        "200":
          description: OK
          headers: { ETag: { $ref: "#/components/headers/ETag" } }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Shop" }
        "304": { $ref: "#/components/responses/NotModified" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
    patch:
      summary: 店舗設定の更新
      description: |
        スコープ `write:settings`。判定レベル・セルフ診断上限・公開ページの表示設定（`public`）だけを変えられる。
        LINE の秘密情報・プロンプト・月の診断上限（`monthly_exam_limit`。Saucer 側の設定）は受け取らない。`If-Match` 必須。
      operationId: updateShop
      tags: [settings]
      parameters:
        - { name: uid, in: path, required: true, schema: { type: string } }
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ShopInput" }
            example: { self_diagnosis_limit: 3, public: { accent_color: "#ff6600" } }
      responses:
        "200":
          description: 更新後の店舗（新しい ETag 付き）
          headers: { ETag: { $ref: "#/components/headers/ETag" } }
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Shop" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "428": { $ref: "#/components/responses/PreconditionRequired" }
  /v1/staffs:
    get:
      summary: スタッフ一覧
      description: |
        スコープ `read:settings`。名前・ロール・担当店舗だけ（メール等は返さない）。
        担当店舗が限定されたキーでは、所属店舗が見える店舗のスタッフだけ。
      operationId: listStaffs
      tags: [settings]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/Staff" } }
                  next_cursor: { $ref: "#/components/schemas/NextCursor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /v1/threshold_levels:
    get:
      summary: 判定レベルのマスタ
      description: スコープ `read:settings`。
      operationId: listThresholdLevels
      tags: [settings]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/ThresholdLevel" } }
                  next_cursor: { $ref: "#/components/schemas/NextCursor" }
              example:
                data:
                  - { id: gentle, name: 優しい, description: 緩い姿勢評価基準・初心者向け }
                  - { id: normal, name: 普通, description: 一般的な姿勢評価に適した設定 }
                  - { id: strict, name: 厳しい, description: 厳格な姿勢評価基準・専門向け }
                next_cursor: null
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /v1/reports/examinations:
    get:
      summary: 診断数の集計
      description: |
        スコープ `read:reports`（店舗管理者以上が発行したキー）。期間 × 粒度 × 店舗 × 分析目的の診断数。
        期間は診断日（date）で最大 13 か月。空のバケットも 0 で返す。
      operationId: reportExaminations
      tags: [reports]
      parameters:
        - $ref: "#/components/parameters/ReportFrom"
        - $ref: "#/components/parameters/ReportTo"
        - $ref: "#/components/parameters/Granularity"
        - { name: shop_uid, in: query, schema: { type: string } }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/ExaminationsReport" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/reports/scores:
    get:
      summary: スコアの集計
      description: |
        スコープ `read:reports`。分析完了の診断のグレード別件数・平均点の推移と、判定項目別の「要注意」比率。
        **判定基準の版（scoring_criteria_version）× 判定レベル（threshold_level_id）ごとに `groups` に分けて返す**
        （版・レベルが違うと点数・判定の意味が変わるため、混ぜた平均は出さない。例: 2026-09-29 の v2 切替をまたぐ期間は v1 と v2 の 2 グループ）。
        グレード境界は診断詳細の grade と同じ。集計対象が 20,000 件を超えると 422（期間を短くする）。
      operationId: reportScores
      tags: [reports]
      parameters:
        - $ref: "#/components/parameters/ReportFrom"
        - $ref: "#/components/parameters/ReportTo"
        - $ref: "#/components/parameters/Granularity"
        - { name: shop_uid, in: query, schema: { type: string } }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/ScoresReport" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/reports/clients:
    get:
      summary: 顧客の集計
      description: スコープ `read:reports`。新規顧客・診断あり顧客・再診断率・最終診断からの経過。
      operationId: reportClients
      tags: [reports]
      parameters:
        - $ref: "#/components/parameters/ReportFrom"
        - $ref: "#/components/parameters/ReportTo"
        - { name: shop_uid, in: query, schema: { type: string } }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/ClientsReport" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/reports/usage:
    get:
      summary: 今月の利用状況
      description: |
        スコープ `read:reports`。店舗ごとの今月の消費数・上限・残数と有効な診断数、AI アドバイス残数、プラン情報。
        `this_month_exam_count` / `remaining_exam_count` は新規分析の受付（`POST /v1/examinations` の `monthly_limit_exceeded`）と同じ消費カウンタ
        （診断を削除しても戻らない）。今月作成された削除されていない診断数は `completed_examination_count`。
      operationId: reportUsage
      tags: [reports]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/UsageReport" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
components:
  parameters:
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      description: 1 ページの件数。範囲外・整数でなければ 422
    Cursor:
      name: cursor
      in: query
      schema: { type: string }
      description: 前回のレスポンスの next_cursor をそのまま渡す（中身に意味はない。不正なら 422）
    UpdatedSince:
      name: updated_since
      in: query
      schema: { type: string, format: date-time }
      description: この日時以降に更新されたものだけ（ISO 8601。日付だけなら その日の 0 時 JST）
    From:
      name: from
      in: query
      schema: { type: string, format: date }
      description: 診断日がこの日以降
    To:
      name: to
      in: query
      schema: { type: string, format: date }
      description: 診断日がこの日以前
    AnalysisPurpose:
      name: analysis_purpose
      in: query
      schema: { type: string, enum: [default, initial_trial, post_treatment, regular_check] }
    AnalysisStatus:
      name: analysis_status
      in: query
      schema: { type: string, enum: [pending, processing, completed, failed] }
    ReportFrom:
      name: from
      in: query
      schema: { type: string, format: date }
      description: 期間の開始日（既定は to の 29 日前）。to との差は最大 13 か月（超えたら 422 period_too_long）
    ReportTo:
      name: to
      in: query
      schema: { type: string, format: date }
      description: 期間の終了日（既定は今日）。両端を含む
    Granularity:
      name: granularity
      in: query
      schema: { type: string, enum: [day, week, month], default: day }
      description: week は月曜始まり
    IfNoneMatch:
      name: If-None-Match
      in: header
      schema: { type: string }
      description: 前回の ETag。完全一致すれば 304（本文なし）
    IfMatch:
      name: If-Match
      in: header
      required: true
      schema: { type: string, example: '"8d36e2fe0c1a4b5d9e7f6a3b2c1d0e9f"' }
      description: 直前の GET / PATCH の ETag（完全一致。W/ や * は不可）。無ければ 428、他で更新されていれば 412
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema: { type: string, maxLength: 255, example: 7f0c2a9e-3b1d-4c55-9a8e-0d6b1f2e3c4a }
      description: 再送を安全にするキー（UUID 推奨）。24 時間保持。同じキーで本文が違えば 422
  headers:
    ETag:
      schema: { type: string }
      description: |
        強い ETag（例 "8d36e2fe0c1a4b5d9e7f6a3b2c1d0e9f"）。返す内容（data）が変われば変わる。
        ただし診断の画像 URL（取得のたびに署名し直す）は含めない
    Location:
      schema: { type: string, format: uri }
      description: 作成したリソースの URL
    IdempotentReplayed:
      schema: { type: string, enum: ["true"] }
      description: Idempotency-Key の再送で、保存した応答を返したとき
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: snv_<8 hex>_<64 hex>
      description: 事業者設定「API連携」で発行したキー。発行時に 1 度だけ表示される。
  schemas:
    Scope:
      type: string
      enum:
        - read:clients
        - write:clients
        - read:examinations
        - write:examinations
        - embed
        - read:settings
        - write:settings
        - read:reports
      description: |
        write:settings は企業管理者（オーナー含む）、read:reports は店舗管理者以上が発行したキーでだけ有効。
        それ以外は全スタッフ。発行者が降格されると、そのぶん実行時のスコープが縮む。
    Ping:
      type: object
      required: [company, scopes, shop_uids, key]
      properties:
        company:
          type: object
          properties:
            uid: { type: string }
            name: { type: string }
        scopes:
          type: array
          items: { $ref: "#/components/schemas/Scope" }
          description: 実行時に有効なスコープ（キーのスコープ ∩ 発行者の権限）
        shop_uids:
          type: array
          nullable: true
          items: { type: string }
          description: 扱える店舗。null は全店舗（発行者の担当店舗が限定されているときだけ配列）
        key:
          type: object
          properties:
            uid: { type: string }
            name: { type: string }
    NextCursor:
      type: string
      nullable: true
      description: 次のページのカーソル。null なら最後
    ClientInput:
      type: object
      description: 登録・更新で受け取る項目（登録は name 必須）。ここに無い項目（memo 等）は無視する
      properties:
        name: { type: string, maxLength: 255 }
        name_kana: { type: string, nullable: true, maxLength: 255 }
        email: { type: string, nullable: true, maxLength: 255 }
        phone_number: { type: string, nullable: true, maxLength: 255 }
        external_id: { type: string, nullable: true, maxLength: 255, description: 外部システムの顧客 ID（企業内で一意） }
        customer_number: { type: string, nullable: true, maxLength: 255 }
        height: { type: integer, nullable: true, minimum: 0, maximum: 300 }
        sex: { type: string, nullable: true }
        birthday: { type: string, format: date, nullable: true }
        shop_uid: { type: string, description: 見える店舗の uid。登録で省くと見える店舗の先頭 }
    CompanyInput:
      type: object
      properties:
        name: { type: string, maxLength: 255 }
        tel: { type: string, nullable: true, maxLength: 255 }
        homepage_url: { type: string, nullable: true, description: "http(s):// で始まる URL" }
        threshold_level_id: { type: string, description: /v1/threshold_levels の id }
        use_llm_advice: { type: boolean }
        client_login_method: { type: string, enum: [permanent_token, onetime_token, email_code] }
    ShopInput:
      type: object
      properties:
        threshold_level_id: { type: string, description: /v1/threshold_levels の id }
        visitor_threshold_level_id: { type: string, description: セルフ診断（ビジター）用。/v1/threshold_levels の id }
        self_diagnosis_limit: { type: integer, minimum: 0, description: 0 は無制限 }
        public:
          type: object
          description: 公開ページの表示設定（渡した項目だけ更新）
          properties:
            name_public: { type: string, nullable: true, maxLength: 255 }
            header_catch_copy: { type: string, nullable: true, maxLength: 50 }
            one_line_comment: { type: string, nullable: true, maxLength: 100 }
            accent_color: { type: string, nullable: true, pattern: "^#[0-9a-fA-F]{6}$" }
            background_gradient_type: { type: string, enum: [warm, cool] }
            recommended_menu_title: { type: string, nullable: true, maxLength: 50 }
    ExaminationInput:
      type: object
      properties:
        date: { type: string, format: date }
        analysis_purpose: { type: string, readOnly: true, description: 変更不可（渡すと 422 read_only） }
        threshold_level_id: { type: string, readOnly: true, description: 変更不可（渡すと 422 read_only） }
    ExaminationCreateRequest:
      type: object
      required: [client_uid, "images[standing]", "images[standing_side]"]
      properties:
        client_uid: { type: string, description: 対象の顧客（見えない顧客は 404） }
        shop_uid: { type: string, description: 省略時は顧客の店舗。担当外の店舗は 422 }
        date: { type: string, format: date, description: 診断日（省略時は今日） }
        analysis_purpose: { type: string, enum: [default, initial_trial, post_treatment, regular_check], default: default }
        threshold_level_id: { type: string, description: 判定レベル（/v1/threshold_levels の id）。省略時は目的の対応値 > 顧客の店舗の設定。受付時点で固定 }
        images[standing]: { type: string, format: binary, description: 正面写真（JPEG / PNG、10MB 以下） }
        images[standing_side]: { type: string, format: binary, description: 側面写真（JPEG / PNG、10MB 以下） }
        enable_ai_advice: { type: boolean, default: true, description: AI アドバイスを生成する（企業の設定が ON かつ残数があるときだけ使われる） }
        notify_client: { type: boolean, default: false, description: 完了時に顧客へ LINE / メールで通知する（画面の「ユーザーに通知」と同じ） }
        webhook_url: { type: string, format: uri, description: この分析だけの通知先（省略時はキーの既定値）。https・443・公開アドレスのみ }
    ExaminationAccepted:
      type: object
      properties:
        uid: { type: string, example: EM12345678 }
        analysis_status: { type: string, enum: [pending] }
        ai_advice: { type: string, enum: [enabled, disabled, skipped_no_stock], description: AI アドバイスを生成するか。skipped_no_stock は残数 0 で AI 無しにしたとき }
        poll_url: { type: string, format: uri, description: "進捗確認用（GET /v1/examinations/{uid}）" }
        created_at: { type: string, format: date-time }
    WebhookEvent:
      type: object
      description: |
        Webhook の本文。ヘッダー `X-Shiseinavi-Event-Id`（= id）、`X-Shiseinavi-Timestamp`（epoch 秒）、
        `X-Shiseinavi-Signature: v1=<HMAC-SHA256(secret, "timestamp.body")>`。受信側は event_id で重複を排除する。
        `data.examination` は診断サマリ（一覧の 1 件と同じ）で、AI アドバイスの状態・本文（ai_advice_result /
        ai_advice_result_status / ai_advice_requested）は含まれない。本文は `GET /v1/examinations/{uid}` で取得する。
        イベントは 1 診断につき 1 件だけ生成するが、配送は重複し得る（at-least-once）。
      properties:
        id: { type: string, format: uuid }
        type: { type: string, enum: [examination.completed, examination.failed] }
        created_at: { type: string, format: date-time }
        data:
          type: object
          required: [examination]
          properties:
            examination: { $ref: "#/components/schemas/ExaminationSummary" }
    EmbedTokenRequest:
      type: object
      required: [kind]
      properties:
        kind: { type: string, enum: [scan, mypage, result] }
        examination_uid: { type: string, description: kind=result のとき必須（この顧客の診断） }
    EmbedToken:
      type: object
      properties:
        url: { type: string, format: uri, example: "https://cp.shiseinavi.com/clients/CL12345678/login?token=...&access=embed&redirect=scan/shoot_method_select" }
        kind: { type: string, enum: [scan, mypage, result] }
        expires_at: { type: string, format: date-time }
        expires_in: { type: integer, example: 1800 }
    Client:
      type: object
      properties:
        uid: { type: string, example: CL12345678 }
        external_id: { type: string, nullable: true }
        name: { type: string, nullable: true }
        name_kana: { type: string, nullable: true }
        email: { type: string, nullable: true }
        phone_number: { type: string, nullable: true }
        height: { type: integer, nullable: true }
        sex: { type: string, nullable: true }
        birthday: { type: string, format: date, nullable: true }
        customer_number: { type: string, nullable: true }
        shop_uid: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    ExaminationSummary:
      type: object
      properties:
        uid: { type: string, example: EM12345678 }
        client_uid: { type: string, nullable: true, description: ビジター診断は null }
        shop_uid: { type: string }
        date: { type: string, format: date }
        analysis_purpose: { type: string, enum: [default, initial_trial, post_treatment, regular_check] }
        analysis_status: { type: string, enum: [pending, processing, completed, failed] }
        score: { type: number, nullable: true, description: 総合点（スタッフ編集 > 自動採点 > AI の順） }
        grade: { type: string, enum: [A, B, C, D], nullable: true }
        scoring_criteria_version: { type: string, example: v2 }
        top_image_url: { type: string, nullable: true, description: 正面写真（署名付き URL・短時間で失効） }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    Examination:
      allOf:
        - $ref: "#/components/schemas/ExaminationSummary"
        - type: object
          properties:
            diagnosis_result:
              type: array
              description: 判定項目（結果画面と同じ項目キー・項目名）
              items: { $ref: "#/components/schemas/DiagnosisItem" }
            ai_advice_result:
              type: object
              nullable: true
              additionalProperties: true
              description: |
                AI アドバイスの本文（overall_comment / front_posture_comment / side_posture_comment /
                exercise_program / recommended_products など）。スタッフが編集した文があればそちらを返す。
                点数・グレードは score / grade を使う（ここには含めない）
            ai_advice_result_status:
              type: string
              example: done
              description: AI アドバイスの状態。AI を使わない設定（ai_advice_requested=false）でも完了すれば done になる
            ai_advice_requested:
              type: boolean
              description: API または画面から AI アドバイスが依頼・生成された場合 true（API で enable_ai_advice が有効、または画面の撮影で AI アドバイスが生成された）。AI アドバイスの有無はこちらで見分ける（詳細だけに載り、一覧・Webhook には無い）
            analysis_checkpoint:
              type: string
              nullable: true
              enum: [predict_front, predict_side, render, analyze, score, ai_advice, done]
              description: ヘッドレス分析で完了した工程（画面の撮影は null）
            analysis_error_stage: { type: string, nullable: true, description: 失敗した工程（predict_front / predict_side / render / analyze / diagnosis / score / advice / canceled） }
            source: { type: string, enum: [cmp, api], description: cmp＝画面の撮影、api＝ヘッドレス分析 }
            scans:
              type: array
              items:
                type: object
                properties:
                  uid: { type: string }
                  scan_type: { type: string, enum: [standing, standing_side] }
                  image_url: { type: string, nullable: true, description: "骨格線入り。通常 480×640（ヘッドレス分析は写真を 3:4 の黒帯つきの枠に収めた画像。この修正以前に作られた診断は元写真の大きさ）" }
                  shot_image_url: { type: string, nullable: true, description: "骨格線なしの写真。通常 480×640（ヘッドレス分析は写真を 3:4 の黒帯つきの枠に収めた画像。この修正以前に作られた診断は元写真の大きさ）" }
            threshold_level: { type: string, nullable: true, description: この診断に使った判定レベル }
    DiagnosisItem:
      type: object
      properties:
        key: { type: string, example: front_head_tilt }
        view: { type: string, enum: [front, side] }
        title: { type: string, example: 頭の左右傾き }
        unit: { type: string, nullable: true, example: 度 }
        value: { type: number, nullable: true, description: 測定値 }
        score: { type: number, nullable: true }
        rating: { type: integer, nullable: true, description: 0〜4（2 が正常） }
        level:
          type: string
          enum: [good, mild, caution]
          nullable: true
          description: good=良好 / mild=少し気になる（正常から 1）/ caution=要注意（正常から 2 以上）
    Company:
      type: object
      properties:
        uid: { type: string }
        name: { type: string }
        name_inner: { type: string, nullable: true }
        tel: { type: string, nullable: true }
        homepage_url: { type: string, nullable: true }
        threshold_level_id: { type: string, enum: [gentle, normal, strict] }
        use_llm_advice: { type: boolean }
        client_login_method: { type: string, enum: [permanent_token, onetime_token, email_code] }
        payment_status: { type: string, enum: [trial, paid, free] }
        trial_end_date: { type: string, format: date, nullable: true }
        plan_name: { type: string, nullable: true }
        api_enabled: { type: boolean }
    Shop:
      type: object
      properties:
        uid: { type: string }
        name: { type: string }
        status: { type: string }
        threshold_level_id: { type: string }
        visitor_threshold_level_id: { type: string }
        self_diagnosis_limit: { type: integer, description: セルフ診断の上限（0 は無制限） }
        monthly_exam_limit: { type: integer, description: 月の診断上限（Saucer 側の設定。読み取りのみ） }
        public:
          type: object
          description: 公開ページの表示設定
          properties:
            name_public: { type: string, nullable: true }
            header_catch_copy: { type: string, nullable: true }
            one_line_comment: { type: string, nullable: true }
            accent_color: { type: string, nullable: true, example: "#ff6600" }
            background_gradient_type: { type: string, nullable: true, enum: [warm, cool] }
            recommended_menu_title: { type: string, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    Staff:
      type: object
      properties:
        uid: { type: string }
        name: { type: string }
        role: { type: string, enum: [company_admin, shop_admin, shop_member] }
        able_all_shops: { type: boolean, description: 全店舗を扱える（オーナー・企業管理者・全店舗設定・担当未設定） }
        shop_uids: { type: array, items: { type: string }, description: 担当店舗（全店舗のスタッフは空配列） }
    ThresholdLevel:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        description: { type: string }
    ReportPeriod:
      type: object
      properties:
        from: { type: string, format: date }
        to: { type: string, format: date }
        granularity: { type: string, enum: [day, week, month] }
    ExaminationCounts:
      type: object
      properties:
        total: { type: integer, description: 有効な診断数 }
        completed: { type: integer, description: 分析完了 }
        failed: { type: integer, description: 分析失敗 }
        ai_advice: { type: integer, description: AI アドバイスを使って生成済み（AI 無しで完了した診断は数えない） }
    ExaminationsReport:
      type: object
      properties:
        period: { $ref: "#/components/schemas/ReportPeriod" }
        totals: { $ref: "#/components/schemas/ExaminationCounts" }
        series:
          type: array
          items:
            allOf:
              - $ref: "#/components/schemas/ExaminationCounts"
              - type: object
                properties:
                  period_start: { type: string, format: date }
                  by_shop: { type: array, items: { $ref: "#/components/schemas/ShopExaminationCounts" } }
                  by_purpose: { type: array, items: { $ref: "#/components/schemas/PurposeExaminationCounts" } }
        by_shop: { type: array, items: { $ref: "#/components/schemas/ShopExaminationCounts" } }
        by_purpose: { type: array, items: { $ref: "#/components/schemas/PurposeExaminationCounts" } }
    ShopExaminationCounts:
      allOf:
        - $ref: "#/components/schemas/ExaminationCounts"
        - type: object
          properties:
            shop_uid: { type: string }
            name: { type: string }
    PurposeExaminationCounts:
      allOf:
        - $ref: "#/components/schemas/ExaminationCounts"
        - type: object
          properties:
            analysis_purpose: { type: string }
    ScoreSummary:
      type: object
      properties:
        count: { type: integer, description: 分析完了の診断数 }
        scored_count: { type: integer, description: うち点数がある診断 }
        average_score: { type: number, nullable: true, description: 平均点（小数 1 桁） }
        grades:
          type: object
          properties:
            A: { type: integer }
            B: { type: integer }
            C: { type: integer }
            D: { type: integer }
    ScoresReport:
      type: object
      properties:
        period: { $ref: "#/components/schemas/ReportPeriod" }
        groups:
          type: array
          description: 判定基準の版 × 判定レベルごとの集計（版・レベルの昇順。対象が無ければ空配列）
          items: { $ref: "#/components/schemas/ScoreGroup" }
    ScoreGroup:
      type: object
      properties:
        scoring_criteria_version: { type: string, example: v2, description: 判定基準の版（診断詳細の scoring_criteria_version） }
        threshold_level_id: { type: string, nullable: true, example: normal, description: 判定レベル（gentle / normal / strict。未指定で採点した診断は null） }
        totals: { $ref: "#/components/schemas/ScoreSummary" }
        series:
          type: array
          items:
            allOf:
              - $ref: "#/components/schemas/ScoreSummary"
              - type: object
                properties:
                  period_start: { type: string, format: date }
        items:
          type: array
          description: 判定項目別の要注意比率（rating が正常 2 から 2 以上離れた割合）
          items:
            type: object
            properties:
              key: { type: string }
              view: { type: string, enum: [front, side] }
              title: { type: string }
              evaluated_count: { type: integer }
              caution_count: { type: integer }
              caution_ratio: { type: number, nullable: true, description: 0〜1（小数 4 桁）。評価 0 件は null }
    ClientsReport:
      type: object
      properties:
        period:
          type: object
          properties:
            from: { type: string, format: date }
            to: { type: string, format: date }
        new_clients: { type: integer, description: 期間内に登録された顧客 }
        examined_clients: { type: integer, description: 期間内に診断した顧客 }
        repeat_clients: { type: integer, description: examined_clients のうち to までに 2 回以上診断した顧客 }
        repeat_rate: { type: number, nullable: true, description: repeat_clients / examined_clients（小数 4 桁） }
        since_last_examination:
          type: object
          description: to 時点の最終診断日からの経過日数別の顧客数
          properties:
            within_30_days: { type: integer }
            over_30_days: { type: integer, description: 31〜90 日 }
            over_90_days: { type: integer, description: 91〜180 日 }
            over_180_days: { type: integer, description: 181 日以上 }
            never_examined: { type: integer, description: to までに登録され診断が無い }
    UsageReport:
      type: object
      properties:
        month: { type: string, example: "2026-10" }
        shops:
          type: array
          items:
            type: object
            properties:
              shop_uid: { type: string }
              name: { type: string }
              this_month_exam_count: { type: integer, description: 今月の消費数（受付の月次枠と同じカウンタ。削除しても戻らない） }
              monthly_exam_limit: { type: integer }
              remaining_exam_count: { type: integer, description: monthly_exam_limit - this_month_exam_count（0 未満は 0）。受付の判定と一致する }
              completed_examination_count: { type: integer, description: 今月作成された有効な（削除されていない）診断数 }
        company:
          type: object
          properties:
            this_month_ai_stock: { type: integer, description: 今月の AI アドバイス残数 }
            payment_status: { type: string, enum: [trial, paid, free] }
            trial_end_date: { type: string, format: date, nullable: true }
            plan_name: { type: string, nullable: true }
    Problem:
      type: object
      description: RFC 9457 Problem Details
      required: [type, title, status]
      properties:
        type:
          type: string
          format: uri
          example: https://posture-api.shiseinavi.com/problems/insufficient_scope
          description: |
            `<サーバーの URL>/problems/<コード>`。判定は末尾のコードで行う。
            末尾のコード: unauthorized / insufficient_scope / not_found / validation_error / bad_request /
            conflict / rate_limited / maintenance / internal_error /
            precondition_required / precondition_failed /
            idempotency_key_required / invalid_idempotency_key / idempotency_key_reused / operation_in_progress
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        required_scopes:
          type: array
          items: { $ref: "#/components/schemas/Scope" }
          description: insufficient_scope（403）のときだけ
        errors:
          type: array
          description: |
            validation_error（422）のときだけ。code の例: invalid（形式）/ out_of_range / inclusion（選択肢外）/
            invalid_range（from > to）/ period_too_long（13 か月超）/ too_many_records（集計対象が多すぎる）/ not_found（店舗・顧客）/
            blank（必須）/ too_long / read_only（変更できない項目）
          items:
            type: object
            properties:
              field: { type: string }
              code: { type: string }
              message: { type: string }
  responses:
    ExaminationList:
      description: OK
      content:
        application/json:
          schema:
            type: object
            required: [data, next_cursor]
            properties:
              data: { type: array, items: { $ref: "#/components/schemas/ExaminationSummary" } }
              next_cursor: { $ref: "#/components/schemas/NextCursor" }
    NotModified:
      description: If-None-Match が一致（本文なし）
    BadRequest:
      description: Idempotency-Key が長すぎる（invalid_idempotency_key）など
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    Conflict:
      description: external_id の重複（conflict。errors に field=external_id / code=taken）、同じ Idempotency-Key の操作が処理中（operation_in_progress）
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
          example:
            type: https://posture-api.shiseinavi.com/problems/conflict
            title: Conflict
            status: 409
            detail: external_id already exists
            errors:
              - { field: external_id, code: taken, message: external_id は既に使われています }
    PreconditionFailed:
      description: If-Match が今の ETag と違う（他で更新された）。GET し直してからやり直す
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    PreconditionRequired:
      description: If-Match が無い
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    NotFound:
      description: 存在しない・他社・担当外の店舗（区別しない）
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    UnprocessableEntity:
      description: パラメータ不正（errors に field / code / message）
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
          example:
            type: https://posture-api.shiseinavi.com/problems/validation_error
            title: Unprocessable Entity
            status: 422
            detail: パラメータに誤りがあります
            errors:
              - { field: from, code: period_too_long, message: 期間は最大 13 か月です。期間を短くしてください }
    Unauthorized:
      description: キーがない・不正・失効・期限切れ・企業の API 無効・発行者停止（理由は区別しない）
      headers:
        WWW-Authenticate:
          schema: { type: string }
          example: Bearer realm="shiseinavi", error="invalid_token"
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    Forbidden:
      description: スコープ不足
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    TooManyRequests:
      description: 流量制限超過
      headers:
        Retry-After:
          schema: { type: integer }
          description: 再試行までの秒数
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    AnalysisTooManyRequests:
      description: |
        `rate_limited`（流量。`Retry-After` あり）、`too_many_pending_analyses`（企業の処理中の分析が 5 件。完了を待つ）、
        `monthly_limit_exceeded`（店舗の月間分析回数の上限。`limit` / `current` を含む。`Retry-After` なし）
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    InternalError:
      description: サーバーエラー
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
