# 姿勢ナビ API（β）ドキュメント

> 姿勢ナビの Company API（β）のリファレンスとクイックスタート。APIキーの発行、顧客の登録、写真2枚を送っての姿勢分析と結果の取得、分析完了の Webhook、埋め込み URL、エラー形式と流量制限。

URL: https://shiseinavi.com/docs/api
更新日: 2026-10-29

姿勢ナビ（運営: 株式会社Saucer）は、写真1枚で姿勢を AI 分析し、その結果をお客様との会話の入口にして、初回体験の入会率・継続率を上げる、整体院・接骨院、パーソナルジム、ピラティス、エステサロンなどの店舗向け SaaS です。料金は月5,000円〜。

> **β版です。予告なく仕様を変更する場合があります。** エンドポイント・項目・制限値は、β期間中に変わることがあります。変更があったときは、このページと [OpenAPI](https://shiseinavi.com/openapi/company-api.yaml) を更新します。

姿勢ナビの Company API は、店舗（企業）が自分で発行した API キーで、自社のシステムや AI エージェントから姿勢ナビのデータを扱うための REST API です。

- **できること**: 顧客・診断の取得と登録、**正面・側面の写真2枚を送ると姿勢分析が走り、結果を取得できる**、分析の完了・失敗の Webhook 通知、診断の撮影画面・結果画面を自社アプリから開く埋め込み URL の発行、診断数・スコアなどの集計
- **AI から使う**: 仕様を [OpenAPI（YAML）](https://shiseinavi.com/openapi/company-api.yaml) で公開しています。AI エージェント（Claude Code、ChatGPT のカスタムアクションなど）に OpenAPI と API キーを渡せば、API をそのまま呼び出せます（[AI エージェントから使う](#ai-agents)）
- **AI 向けの要約**: [llms.txt](https://shiseinavi.com/llms.txt) / [llms-full.txt](https://shiseinavi.com/llms-full.txt)（このページの全文を含みます）

## 基本

| 項目 | 内容 |
|---|---|
| ベース URL | `https://posture-api.shiseinavi.com`（パスは `/v1/...`。`/api` のプレフィックスはありません） |
| 認証 | `Authorization: Bearer snv_<8文字>_<64桁>`（店舗の管理画面で発行した API キー） |
| 形式 | JSON（UTF-8）。書き込みの本文も `Content-Type: application/json`（写真の送信だけ multipart） |
| 日時 | ISO 8601（UTC、末尾 `Z`）。日付は `YYYY-MM-DD` |
| エラー | [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) の `application/problem+json` |
| 仕様 | [OpenAPI 3.0（YAML）](https://shiseinavi.com/openapi/company-api.yaml) |

## API キーの発行

API キーは、店舗が姿勢ナビの管理画面で発行します（企業管理者・オーナーの権限が必要です）。

1. 姿勢ナビの管理画面に、企業管理者（オーナーを含む）でログインします
2. 右上のメニューの「API設定 β」（または「事業者設定」→「API連携」）を開きます
3. 「キーを発行」から、名前（用途）・スコープ・有効期限を選んで発行します。分析完了の通知を受けたい場合は、Webhook の送信先 URL も入れられます（あとからでも設定できます）
4. 表示された API キー（`snv_...`）と Webhook の署名シークレットを、その場でコピーして保管します。**どちらも1度しか表示されません**

- キーを発行すると「外部 API を有効にする」が自動で ON になります。OFF にすると、発行済みのすべてのキーがすぐに使えなくなります（ON に戻せば、失効していないキーは再び使えます）
- 不要になったキーは「失効する」で止めます。直近の呼び出し（50件）と Webhook の配送履歴を画面で確認できます
- キーで使える範囲は **キーのスコープ ∩ 発行したスタッフの今の権限** です。発行者が停止・削除・降格されると、そのキーも止まる（または狭まる）ので、退職者のキーは自動で使えなくなります
- 担当店舗が限定されたスタッフが発行したキーは、その店舗のデータだけを扱えます（他店舗の詳細は 404、他店舗を条件に指定すると 422）

### スコープ

| スコープ | できること | 発行者に必要な権限 |
|---|---|---|
| `read:clients` | 顧客の閲覧 | 全スタッフ |
| `read:examinations` | 診断の閲覧 | 全スタッフ |
| `read:settings` | 企業・店舗・スタッフ・判定レベルの閲覧 | 全スタッフ |
| `read:reports` | 集計の閲覧 | 店舗管理者以上 |
| `write:clients` | 顧客の登録・更新・削除 | 全スタッフ |
| `write:examinations` | 写真を送っての新規分析、診断の更新（日付のみ）・削除 | 全スタッフ |
| `write:settings` | 企業・店舗設定の変更 | 企業管理者（オーナーを含む） |
| `embed` | 診断画面・マイページ・結果を開く URL の発行 | 全スタッフ |

スコープが足りないと `403 insufficient_scope` になり、本文の `required_scopes` に必要なスコープが入ります。

## クイックスタート（curl）

疎通確認 → 顧客の登録 → 写真2枚を送って分析 → 結果の取得、の順に進めます。

```bash
export SNV_KEY="snv_xxxxxxxx_..."        # 発行した API キー（コードやチャットに直接貼らない）
BASE=https://posture-api.shiseinavi.com
```

### 1. 疎通確認

```bash
curl -s "$BASE/v1/ping" -H "Authorization: Bearer $SNV_KEY"
# → {"data":{"company":{"uid":"CP12345678","name":"株式会社サンプル"},"scopes":["read:clients",...],"shop_uids":null,"key":{...}}}
```

どの企業・スコープ・店舗範囲で動くキーかが返ります（スコープ不要）。

### 2. 顧客を登録する（`write:clients`）

```bash
KEY=$(uuidgen)   # この依頼の冪等キー（再送でも同じ値を使う）
curl -s -X POST "$BASE/v1/clients" \
  -H "Authorization: Bearer $SNV_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name":"山田太郎","email":"taro@example.com","external_id":"CRM-12345"}'
# → 201 {"data":{"uid":"CL12345678", ...}}  Location: .../v1/clients/CL12345678
```

通信が切れたときは、同じ `KEY` で同じコマンドをもう一度実行してください。新しい登録・診断は作られず、同じ応答が返ります（`KEY` は依頼1回ごとに1度だけ作り、再送では作り直さない）。

- `external_id` に自社システムの顧客 ID を入れておくと、`GET /v1/clients?external_id=CRM-12345` で引けます（他の顧客と重なると `409 conflict`）
- `Idempotency-Key` を付けると、タイムアウト後に再送しても二重に登録されません

### 3. 写真2枚を送って分析する（`write:examinations`）

```bash
KEY=$(uuidgen)   # この依頼の冪等キー（再送でも同じ値を使う）
curl -s -X POST "$BASE/v1/examinations" \
  -H "Authorization: Bearer $SNV_KEY" \
  -H "Idempotency-Key: $KEY" \
  -F client_uid=CL12345678 \
  -F "images[standing]=@front.jpg" \
  -F "images[standing_side]=@side.jpg"
# → 202 {"data":{"uid":"EM12345678","analysis_status":"pending","ai_advice":"enabled",
#                 "poll_url":"https://posture-api.shiseinavi.com/v1/examinations/EM12345678", ...}}
```

通信が切れたときは、同じ `KEY` で同じコマンドをもう一度実行してください。新しい登録・診断は作られず、同じ応答が返ります（`KEY` は依頼1回ごとに1度だけ作り、再送では作り直さない）。

`Idempotency-Key` は**必須**です。受け付けると `202` と `poll_url` が返り、サーバーが骨格検出 → 骨格線の描画 → 解析 → 採点 → AI アドバイスまで進めます。写真の条件は [分析に使う写真](#photos) を見てください。

### 4. 結果を取得する（ポーリング、または Webhook）

```bash
curl -s "$BASE/v1/examinations/EM12345678" -H "Authorization: Bearer $SNV_KEY"
# analysis_status: pending → processing → completed | failed
```

- 所要時間は 20〜60 秒ほどです。ポーリングは 5 秒間隔程度にしてください
- `completed` になると、スコア・評価・判定項目・AI アドバイスなどが入ります。画面で撮影した診断と同じく、顧客の診断履歴・結果画面・手渡し PDF にもそのまま載ります
- AI アドバイスの有無は `ai_advice_requested`（true / false）で見分けてください。`ai_advice_result_status` は AI を使わない設定でも完了すれば `done` になります。`ai_advice_requested` は詳細（`GET /v1/examinations/{uid}`）だけに載り、一覧・Webhook の本文には含みません
- 待ちたくない場合は [Webhook](#webhook) で完了・失敗の通知を受け取れます

### 5. （任意）結果画面を自社アプリから開く（`embed`）

```bash
curl -s -X POST "$BASE/v1/clients/CL12345678/embed_tokens" \
  -H "Authorization: Bearer $SNV_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"result","examination_uid":"EM12345678"}'
# → {"data":{"url":"https://cp.shiseinavi.com/clients/CL12345678/login?token=...","kind":"result","expires_in":1800}}
```

返った `url` を新しいタブで開くと、その顧客の結果画面が表示されます（[埋め込み URL](#embed)）。

## エンドポイント一覧

| メソッド | パス | 内容 | スコープ |
|---|---|---|---|
| `GET` | `/v1/ping` | 疎通確認 | 不要 |
| `GET` | `/v1/clients` | 顧客一覧 | `read:clients` |
| `POST` | `/v1/clients` | 顧客の登録 | `write:clients` |
| `GET` | `/v1/clients/{uid}` | 顧客詳細 | `read:clients` |
| `PATCH` | `/v1/clients/{uid}` | 顧客の更新 | `write:clients` |
| `DELETE` | `/v1/clients/{uid}` | 顧客の削除（論理削除） | `write:clients` |
| `POST` | `/v1/clients/{uid}/embed_tokens` | 埋め込み URL の発行 | `embed` |
| `GET` | `/v1/clients/{uid}/examinations` | 顧客の診断一覧 | `read:examinations` |
| `GET` | `/v1/examinations` | 診断一覧（企業横断） | `read:examinations` |
| `POST` | `/v1/examinations` | ヘッドレス新規分析（写真 2 枚を送って分析を依頼） | `write:examinations` |
| `GET` | `/v1/examinations/{uid}` | 診断詳細 | `read:examinations` |
| `PATCH` | `/v1/examinations/{uid}` | 診断の更新（日付のみ） | `write:examinations` |
| `DELETE` | `/v1/examinations/{uid}` | 診断の削除（論理削除） | `write:examinations` |
| `GET` | `/v1/company` | 企業情報 | `read:settings` |
| `PATCH` | `/v1/company` | 企業設定の更新 | `write:settings` |
| `GET` | `/v1/shops` | 店舗一覧 | `read:settings` |
| `GET` | `/v1/shops/{uid}` | 店舗詳細 | `read:settings` |
| `PATCH` | `/v1/shops/{uid}` | 店舗設定の更新 | `write:settings` |
| `GET` | `/v1/staffs` | スタッフ一覧 | `read:settings` |
| `GET` | `/v1/threshold_levels` | 判定レベルのマスタ | `read:settings` |
| `GET` | `/v1/reports/examinations` | 診断数の集計 | `read:reports` |
| `GET` | `/v1/reports/scores` | スコアの集計 | `read:reports` |
| `GET` | `/v1/reports/clients` | 顧客の集計 | `read:reports` |
| `GET` | `/v1/reports/usage` | 今月の利用状況 | `read:reports` |

項目の詳細・レスポンスの形は [OpenAPI](https://shiseinavi.com/openapi/company-api.yaml) が正本です。

## 一覧のページングと差分同期

```
GET /v1/clients?limit=50
→ { "data": [...], "next_cursor": "MTc2MTYxMjAwMDAwMDAwMDo0Mg==" }

GET /v1/clients?limit=50&cursor=MTc2MTYxMjAwMDAwMDAwMDo0Mg==
→ { "data": [...], "next_cursor": null }   ← null なら最後
```

- `limit` は 1〜100（既定 20）。並びは更新の新しい順（`updated_at` 降順）
- `next_cursor` はそのまま次のリクエストに渡してください（中身に意味はありません）
- 差分同期には `updated_since`（ISO 8601）を使います
- 店舗・スタッフ・判定レベルは全件を返します（`next_cursor` は常に null）

## 書き込みの作法（冪等キー・楽観ロック）

| 操作 | 作法 |
|---|---|
| 作成（`POST`） | `Idempotency-Key` ヘッダー（UUID 推奨・最大 255 文字・24 時間保持）。同じキー・同じ本文の再送には最初の応答をそのまま返します（`Idempotent-Replayed: true`）。写真を送る `POST /v1/examinations` では必須 |
| 更新（`PATCH`） | **`If-Match` 必須**。直前の `GET`（または `PATCH`）で受け取った `ETag` をそのまま付けます。ほかで先に更新されていたら `412 precondition_failed` になるので、`GET` し直してからやり直します |
| 削除（`DELETE`） | 論理削除。`204 No Content` |

```bash
# GET で ETag を取り、If-Match に付けて更新する
ETAG=$(curl -s -D - -o /dev/null "$BASE/v1/clients/CL12345678" -H "Authorization: Bearer $SNV_KEY" \
  | awk 'tolower($1)=="etag:" {print $2}' | tr -d '\r')
curl -s -X PATCH "$BASE/v1/clients/CL12345678" \
  -H "Authorization: Bearer $SNV_KEY" -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" \
  -d '{"phone_number":"09011112222"}'
```

- 本文は渡した項目だけを変えます（`null` を渡すとその項目を空にします）
- 詳細（`/v1/clients/{uid}` など）は強い `ETag` を返します。`If-None-Match` に付けて送ると、変わっていなければ `304 Not Modified` になります
- 同じ `Idempotency-Key` の操作が処理中、または前回がサーバーエラーで結果が分からないときは `409 operation_in_progress`（24 時間は同じキーを使えません。結果を `GET` で確かめてください）。`409`・`429` の応答は保存しないので、時間をおいて同じキーで再送すれば再実行されます
- 同じ `Idempotency-Key` を別の内容に使うと `422 idempotency_key_reused`、`PATCH` に `If-Match` が無いと `428 precondition_required`

## 写真を送って分析する（`POST /v1/examinations`）

正面・側面の写真を multipart で送ると、画面で撮影したときと同じ診断ができます。

| 項目 | 内容 |
|---|---|
| `client_uid` | 必須。対象の顧客 |
| `images[standing]` / `images[standing_side]` | 必須。正面・側面の写真 |
| `shop_uid` | 省略時は顧客の店舗 |
| `date` / `analysis_purpose` / `threshold_level_id` | 任意。判定レベルは受付時点で固定されます |
| `enable_ai_advice` | 既定 true。企業の設定が OFF なら `ai_advice: disabled`、AI アドバイスの残数が 0 なら AI なしで受け付けて `ai_advice: skipped_no_stock` |
| `notify_client` | 既定 false。true なら完了時に顧客へ LINE / メールで知らせます |
| `webhook_url` | 任意。この分析だけの通知先（省略時はキーに設定した URL） |

### 分析に使う写真

- **JPEG または PNG、1枚 10MB 以下**。正面と側面の2枚
- 全身が写り、画面で撮影するときと同じ構図の写真を使ってください
- 分析は、撮影画面と同じ **3:4（480×640）の枠** に写真を収めて行います。縦長・横長の写真は上下または左右に黒帯が入ります（元の写真の解像度は保持されません）。結果の `image_url`（骨格線入り）・`shot_image_url`（骨格線なし）はこの枠の画像です
- ゆったりした服装や暗い照明では結果が変わります。体のラインが分かる服装・明るい場所での撮影をおすすめします

### 進み方と制限

- `analysis_status` は `pending` → `processing` → `completed` | `failed`。`analysis_checkpoint` に完了した工程（`predict_front` / `predict_side` / `render` / `analyze` / `score` / `ai_advice` / `done`）、失敗時は `analysis_error_stage` に失敗した工程が入ります
- 受付時に **店舗の月間分析回数** と **企業の AI アドバイス残数** を予約します。分析が失敗・削除されても戻りません（画面で撮影したときと同じ扱いです）
- 同時に処理できる API からの分析は企業ごとに 5 件までです。超えると `429 too_many_pending_analyses`（完了を待って、**同じ `Idempotency-Key` で再送**してかまいません）
- 骨格検出の一時的な失敗は 3 回まで自動で再試行します。30 分以上 `processing` のまま止まった分析は自動で積み直します
- 受け付けたあとにキーを失効しても分析は完了します（Webhook は送りません）

| status | type の末尾 | いつ |
|---|---|---|
| 400 | `idempotency_key_required` | `Idempotency-Key` が無い |
| 403 | `plan_inactive` | 契約・プランの状態により診断を作れない |
| 404 | `not_found` | 顧客が無い・担当外 |
| 422 | `validation_error` | 写真が無い・JPEG / PNG でない・10MB 超、`webhook_url` が不正、担当外の `shop_uid` など（`errors[].field`） |
| 429 | `too_many_pending_analyses` | 処理中の分析が 5 件 |
| 429 | `monthly_limit_exceeded` | 店舗の月間分析回数の上限（本文に `limit` / `current`） |
| 429 | `rate_limited` | 流量超過（`Retry-After`） |

## Webhook（分析の完了・失敗を受け取る）

API キーごとに **送信先 URL** を設定すると（`POST /v1/examinations` の `webhook_url` でも指定できます）、写真を送って依頼した分析が完了・失敗したときに、その URL へ POST します。画面で撮影した診断は対象外です。

### ペイロード

```json
{
  "id": "3f2b8c1e-5d7a-4a63-9b0e-2c4d6f8a1b2c",
  "type": "examination.completed",
  "created_at": "2026-10-29T03:00:00Z",
  "data": { "examination": { "uid": "EM12345678", "analysis_status": "completed", "...": "GET /v1/examinations の1件と同じ形" } }
}
```

- `type` は `examination.completed` か `examination.failed`
- `data.examination` は診断の一覧の1件と同じ形で、AI アドバイスの状態・本文は含みません。本文は `GET /v1/examinations/{uid}` で取得してください
- イベントは1診断につき1件ですが、**配送は重複することがあります**（再送・受信後の切断など）。`id` で重複を除いてください
- `data.examination.top_image_url` は短時間で切れる署名付き URL です。画像が必要なときは `GET /v1/examinations/{uid}` で取り直してください

### ヘッダーと署名の検証

| ヘッダー | 中身 |
|---|---|
| `X-Shiseinavi-Event-Id` | イベント ID（本文の `id` と同じ）。**受信側はこれで重複を除いてください** |
| `X-Shiseinavi-Timestamp` | 送信時刻（epoch 秒） |
| `X-Shiseinavi-Signature` | `v1=<HMAC-SHA256(署名シークレット, "<timestamp>.<本文>") の hex>` |

署名シークレットはキーの発行時に1度だけ表示されます（画面の「署名シークレットを再発行」で取り直せます。古いシークレットはすぐ無効になります）。時刻が現在から 5 分以上ずれていれば捨てることをおすすめします（リプレイ対策）。

Node.js:

```js
const crypto = require("crypto");
function verify(rawBody, headers, secret) {
  const timestamp = headers["x-shiseinavi-timestamp"];
  const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const given = headers["x-shiseinavi-signature"] || "";
  return expected.length === given.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given)) &&
    Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
}
```

Ruby（Rails）:

```ruby
secret    = ENV["SHISEINAVI_WEBHOOK_SECRET"]
timestamp = request.headers["X-Shiseinavi-Timestamp"]
body      = request.raw_post
expected  = "v1=" + OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{body}")
valid     = ActiveSupport::SecurityUtils.secure_compare(expected, request.headers["X-Shiseinavi-Signature"].to_s) &&
            (Time.now.to_i - timestamp.to_i).abs < 300
```

署名は**受け取った本文のバイト列そのまま**で計算します（JSON を読み直してから並べ直すと一致しません）。

### 送信先の条件と再送

- 送信先は **https・ポート 443・公開アドレス** のみです（プライベート・ループバック・リンクローカル・クラウドのメタデータ宛ては、登録時と送信時の両方で拒否します）。リダイレクトは追いません
- **2xx を 10 秒以内に返してください**。応答本文は 64KB までにしてください
- 2xx 以外・タイムアウトは失敗として、1 分・10 分・1 時間・6 時間・24 時間後に再送します（最初の送信と合わせて計 6 回）。それでも失敗した配送は、管理画面の「Webhook の配送履歴」に残ります
- 署名シークレットが無いキー（Webhook の公開前に発行したキー）には送信しません。シークレットを再発行してください

## 埋め込み URL（撮影画面・結果画面を自社アプリから開く）

`POST /v1/clients/{uid}/embed_tokens`（スコープ `embed`）で、その顧客の画面に **30 分・1 回限り** でログインできる URL を発行します。

| `kind` | 開く画面 | できること |
|---|---|---|
| `scan` | 診断画面（撮影方法の選択から） | 撮影して診断を作る（顧客情報の更新・比較の作成はできません） |
| `mypage` | 顧客のマイページ | 閲覧のみ |
| `result` | 指定した診断の結果（`examination_uid` が必須） | 閲覧のみ |

- ログイン後の画面は 30 分有効です。キーの失効・発行したスタッフの停止・顧客が担当外の店舗に移ったときは、その時点で使えなくなります
- 開き方は **新しいタブかリダイレクト** をおすすめします（iframe での表示は、カメラの権限・Cookie の扱いを検証中です）

## エラー

エラーは [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) の `application/problem+json` で返します。

```json
{
  "type": "https://posture-api.saucer-saas.com/problems/validation_error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "パラメータに誤りがあります",
  "errors": [{ "field": "from", "code": "period_too_long", "message": "期間は最大 13 か月です。期間を短くしてください" }]
}
```

`type` はエラーの種類を表す識別子です。**末尾（`validation_error` など）で種類を見分けてください**（URL として開く必要はありません）。

| status | type の末尾 | いつ |
|---|---|---|
| 401 | `unauthorized` | キーが無い・不正・失効・期限切れ・API が無効・発行者が停止（理由は区別しません） |
| 403 | `insufficient_scope` / `plan_inactive` | スコープ不足 / 契約・プランの状態により診断を作れない |
| 404 | `not_found` | 存在しない・他社・担当外の店舗のデータ |
| 409 | `conflict` / `operation_in_progress` | `external_id` の重複 / 同じ `Idempotency-Key` の操作が処理中・結果不明 |
| 412 | `precondition_failed` | `If-Match` が今の内容と違う |
| 422 | `validation_error` / `idempotency_key_reused` | パラメータ不正（`errors[].field` / `code` / `message`） / 冪等キーの使い回し |
| 428 | `precondition_required` | `PATCH` に `If-Match` が無い |
| 429 | `rate_limited` / `too_many_pending_analyses` / `monthly_limit_exceeded` | 流量超過（`Retry-After` 秒後に再試行） / 分析の同時実行数・月間上限 |
| 503 | `maintenance` | メンテナンス中（読み取りも止まります） |
| 500 | `internal_error` | サーバーエラー |

## 流量制限

| 対象 | 上限 |
|---|---|
| キーごと | 120 回/分・5,000 回/日 |
| 企業ごと（全キーの合計） | 600 回/分 |
| 集計（`/v1/reports/*`） | 上とは別に、キーごと 30 回/分 |
| 写真の分析の受付（`POST /v1/examinations`） | 上とは別に、キーごと 10 回/分 |
| 認証前（IP ごと） | 300 回/分 |
| 認証失敗 | IP ごと 20 回/分（超えると 1 分間すべて 429） |

超えると `429` と `Retry-After`（秒）を返します。

## 集計 API

- `GET /v1/reports/examinations`（診断数）・`/scores`（スコア）・`/clients`（顧客）・`/usage`（今月の利用状況）。スコープ `read:reports`
- 期間は `from` / `to`（診断日、両端を含む）。省略時は今日までの 30 日間で、最大 13 か月です。`granularity` は `day` / `week`（月曜始まり）/ `month`
- `/v1/reports/scores` は分析が完了した診断が対象で、判定基準の版 × 判定レベルごとに `groups` で返します（版・レベルが違う点数は混ぜて平均しません）
- `/v1/reports/usage` で、店舗ごとの今月の診断数・上限・残りを返します

## 返さない情報

外部（特に AI）に渡ったときの指示の混入や漏えいを避けるため、次の情報は API で返しません: 顧客・診断のメモ／社内メモ、トークガイド、AI へのプロンプト、LINE の秘密情報、決済のキー、スタッフのメールアドレス。

## AI エージェントから使う

姿勢ナビの API は通常の REST API なので、HTTP を呼べる AI エージェントからそのまま使えます。専用の連携機能を入れる必要はありません。

- **Claude Code など、手元でコマンドを実行できるエージェント**: このページの URL と [OpenAPI](https://shiseinavi.com/openapi/company-api.yaml) を渡し、API キーは環境変数（例: `SNV_KEY`）に入れて「環境変数のキーを使って」と伝えます。curl やスクリプトで、写真の送信（multipart）まで実行できます
- **ChatGPT のカスタムアクション（GPTs の Actions）など、OpenAPI を読み込めるツール**: [OpenAPI（YAML）](https://shiseinavi.com/openapi/company-api.yaml) を読み込ませ、認証に API キー（Bearer）を設定します。写真のアップロード（multipart）に対応しているかは、お使いのツールによります

安全に使うために:

- **AI 用に専用のキーを発行し、スコープを必要なものだけに絞ってください**（読むだけなら `read:*` のみ）。使い終わったら失効します
- キーをチャットの本文やコードに直接書かないでください。環境変数・ツールの認証設定に入れます
- 書き込み（登録・更新・削除・分析の依頼）は、実行前に内容を確認させる運用をおすすめします
- 顧客の氏名・写真・姿勢データが外部の AI サービスに送られる場合があります。各 AI サービスのデータの扱いと、自社のプライバシーポリシー・お客様の同意の範囲でご利用ください

AI アシスタントに使い方を聞くときのプロンプト例:

```text
姿勢ナビの API で顧客を登録して写真を分析し結果を取得する手順を教えて。ドキュメント: https://shiseinavi.com/docs/api と https://shiseinavi.com/llms.txt
```

## よくある質問

### API は誰が使えますか

姿勢ナビを契約している店舗（企業）が、管理画面で API キーを発行して使えます。キーを発行できるのは企業管理者（オーナーを含む）です。

### 写真を送ってから結果が出るまで、どれくらいかかりますか

20〜60 秒ほどです（骨格検出2回と AI アドバイスの生成を含みます）。`GET /v1/examinations/{uid}` を 5 秒間隔程度でポーリングするか、Webhook で完了の通知を受け取ってください。

### API で分析した診断は、店舗の画面にも出ますか

出ます。画面で撮影した診断と同じく、顧客の診断履歴・結果画面・手渡し PDF にそのまま載ります。

### 分析の回数は、画面での撮影と別に数えますか

同じです。API で受け付けた分析も、店舗の月間分析回数と企業の AI アドバイス残数を使います。分析が失敗・削除されても戻りません。

### 撮影画面を自社アプリに組み込めますか

`POST /v1/clients/{uid}/embed_tokens` で、診断画面（`scan`）・マイページ（`mypage`）・結果画面（`result`）を開く URL（30 分・1 回限り）を発行できます。新しいタブかリダイレクトで開いてください。

### API はいつまで β 版ですか

未定です。β版です。予告なく仕様を変更する場合があります。 仕様の変更はこのページと OpenAPI に反映します。API についてのご相談は「[無料お問い合わせ](https://shiseinavi.com/contact)」からどうぞ。
