機器実装ガイド

計測機器や自社システムに YuCon API を組み込む際の推奨実装をまとめます。

送信ループの基本形

起動時: GET /v1/facilities/{facilityId} で疎通確認し、congestionScale とサブ設備 ID を取得する
定期送信: 計測値を混雑度 (1 〜段階数) に変換し、PUT .../congestion で送信する。間隔は 60 秒以上
応答処理: 下表のとおり分岐する

応答	処理
200	正常。次の周期へ
429	`Retry-After` 秒待って再送 (または次の周期まで待つ)
409 (`FACILITY_CLOSED`)	営業時間外。エラーとして扱わない。次の周期まで待つ
401 / 403 / 400 / 404	再送しても解決しません。送信を停止し、管理者に通知する
5xx / タイムアウト	指数バックオフ (例: 1 分 → 2 分 → 4 分、上限 15 分) で再送

同じ値が続く場合も定期送信して問題ありません (変化がなければ表示は変わらないだけです)。混雑度の更新が 2 時間以上止まると、利用者画面では「情報が古い」表示になります。

トークンの安全な取り扱い

トークンは機器の設定領域・サーバーの環境変数など、サーバー / 機器側にのみ保管してください
Web ページの JavaScript への埋め込みは動作しません (ブラウザからの直接呼び出しは非サポートです)
トークンをソースコードにコミットしない・ログに出力しないでください
送信は必ず HTTPS です (API は平文 HTTP を受け付けません)

トークンのローテーション

トークンは無停止で交換できます (施設あたり有効トークン 20 本まで)。

管理画面で新しいトークンを発行する
機器の設定を新トークンに切り替える
動作確認後、旧トークンを無効化する

機器を撤去したときや、トークンの漏洩が疑われるときは、すぐに管理画面から無効化してください。無効化した瞬間からそのトークンでの更新は 401 で失敗します。

運用のヒント

機器名 (トークンのラベル) は更新履歴に「誰が更新したか」として表示されます。機器を識別できる名前を付けてください
管理画面のトークン一覧にある最終使用で、機器が生きているかを確認できます。定期送信している機器なら、最終使用は常に直近になっているはずです
有効期限 (expiresAt) を設定したトークンは、期限を過ぎると自動的に 401 になります。長期運用の機器では無期限で発行し、ローテーションで管理する方が事故が少なくなります

よくある質問

Q. 営業時間外も送信し続けてよいですか?

はい。営業時間外の送信は 409 (FACILITY_CLOSED) で受理されませんが、機器側はこれを正常系として扱えば、営業時間を意識しない単純な実装にできます。事前に判定したい場合は GET /v1/facilities/{facilityId} の openState を使ってください。

Q. 手動更新と併用できますか?

できます。管理画面・スタッフページ・API のどこから更新しても同じ扱いです。ただし更新間隔 (30 秒に 1 回) は共有のため、直後の API 送信は 429 になることがあります。

Q. 過去のデータをまとめて送信できますか?

現在の v1 では対応していません (オフライン中のデータの後送りは将来の拡張候補です)。復旧後は現在値の送信から再開してください。