API リファレンス

YuCon API (v1) の仕様です。機械可読な OpenAPI 3.1 定義は openapi.yaml で配信しています。

ベース URL: https://api.yucon.info (開発環境は https://api.dev.yucon.info)
認証: Authorization: Bearer yucon_api_... ヘッダ (全エンドポイント必須)
リクエスト / レスポンスとも JSON (Content-Type: application/json)
v1 では破壊的変更 (フィールド削除・意味変更) を行いません。フィールド追加は随時行われるため、未知のフィールドは無視してください

エンドポイント一覧

メソッド	パス	用途
GET	`/v1/facilities/{facilityId}`	現在状態の取得 (セットアップ・疎通確認)
PUT	`/v1/facilities/{facilityId}/congestion`	施設の混雑度を更新
PUT	`/v1/facilities/{facilityId}/subfacilities/{subFacilityId}/congestion`	サブ設備の混雑度を更新

GET /v1/facilities/{facilityId}

施設の現在状態を返します。有効なトークンであれば権限に関係なく呼び出せる、機器のセットアップ・セルフテスト用エンドポイントです。

レスポンスの主なフィールド:

フィールド	説明
`congestionScale`	混雑度の段階数 (3 または 5)
`currentLevel`	現在の混雑度 (未設定の施設では null)
`openState`	営業状態: `open` / `closed` / `pre_open` / `post_close` / `unknown`。`closed` のとき更新は 409 で拒否されます。`pre_open` / `post_close` (開店前・閉店後の猶予帯) は更新可能。`unknown` は営業スケジュール未設定の施設で、常に更新可能
`token`	認証に使ったトークンのメタ情報 (`label` / `permissions` / `subScope`)。設定ミスの切り分けに使えます
`subFacilities[]`	サブ設備一覧 (`subFacilityId` / `name` / `congestionScale` / `currentLevel` / `isPrimary`)。トークンの `subScope` で絞られます

PUT /v1/facilities/{facilityId}/congestion

施設の代表混雑度を更新します。内部的には代表サブ設備への更新として扱われ、リアルタイム配信・履歴・混雑予測に反映されます。

リクエストボディ:

{ "level": 2 }

level は 1 (空いている) 〜 congestionScale (混雑) の整数です。

成功レスポンス (200):

{
  "success": true,
  "data": {
    "facilityId": "...",
    "currentLevel": 2,
    "currentLevelUpdatedAt": "2026-08-08T10:15:00+00:00",
    "currentLevelUpdatedBy": "STAFF_TOKEN#...",
    "congestionScale": 3
  }
}

PUT /v1/facilities/{facilityId}/subfacilities/{subFacilityId}/congestion

サブ設備単位で混雑度を更新します。level の上限はサブ設備ごとの congestionScale です (施設本体と異なる場合があります)。

トークンの subScope が対象サブ設備を許可している必要があります (primary = 代表サブ設備のみ / all = 全サブ設備)。

リクエストボディ:

{ "level": 3 }

成功レスポンス (200):

{
  "success": true,
  "data": {
    "facilityId": "...",
    "subFacilityId": "...",
    "currentLevel": 3,
    "currentLevelUpdatedAt": "2026-08-08T10:15:00+00:00",
    "currentLevelUpdatedBy": "STAFF_TOKEN#...",
    "isPrimary": false
  }
}

施設更新のレスポンスと異なり congestionScale は含まれません。isPrimary は代表サブ設備への更新だったかどうかを示します。

エラーレスポンス

エラーは共通の形で返ります。

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "...",
    "retryAfter": 30
  }
}

retryAfter は 429 のときのみ含まれます (Retry-After ヘッダと同値)。

code	HTTP	意味	機器側の推奨動作
`VALIDATION_ERROR`	400	リクエスト形式の誤り	再送しない。実装を修正
`INVALID_LEVEL`	400	`level` が段階数の範囲外	再送しない。実装を修正
`UNAUTHORIZED`	401	トークンが無効・期限切れ・失効済み	再送しない。管理者に通知 (再発行が必要)
`FORBIDDEN`	403	施設不一致・権限不足・subScope 外	再送しない。設定を確認
`FACILITY_NOT_FOUND`	404	施設が存在しない (削除済み)	再送しない
`FACILITY_CLOSED`	409	営業時間外のため受理しない	正常系。次の営業時間まで送信を止めるか、無視して定期送信を継続
`RATE_LIMITED`	429	レートリミット超過	`Retry-After` 秒待って再送
—	5xx	サーバ側の一時的な問題	指数バックオフで再送

レートリミット

単位	制限
更新対象 (施設 / サブ設備) ごと	30 秒に 1 回
トークンごと (混雑度更新)	10 回 / 60 秒
トークンごと (状態取得)	30 回 / 60 秒

トークン単位の制限は、有効なトークンで認証できたリクエストであれば成功・失敗を問わず消費されます
429 応答には Retry-After ヘッダ (秒) と error.retryAfter (同値) が含まれます
送信間隔は 60 秒以上を推奨します。30 秒ちょうどの間隔はクロック差で 429 になりやすく、混雑度の性質上それ以上の頻度に意味はありません