Robot Commander Api (1.9)

フリート管理システムに登録済みの全カチャカを返します。 各カチャカには現在のマップ ID、日次再起動設定、接続監視の最新状態（取得済みの場合）が含まれます。 登録解除済みのカチャカは含まれません。接続監視結果は取得タイミングにより省略される場合があります。 一覧取得のみでカチャカ本体の設定が変更されることはありません。

新しいカチャカをフリートに登録します。 カチャカのシリアル番号・パスコード・IP 取得方法（mDNS または手動指定）をリクエストで指定します。 カチャカ本体との接続に成功した場合のみ、フリート管理システムへの登録が完了します。 既に登録済みのカチャカのシリアル番号を指定した場合はエラーになります。接続に失敗した場合も登録されません。

ネットワーク上で mDNS により発見されたカチャカの一覧を返します。 未登録・登録済みのいずれも含まれ、フリートへの登録前確認に使用します。 スキャン結果はホスト側の最新状態に依存します。見つからない場合は空配列が返ります。 IP アドレスは mDNS 設定時の参考情報であり、登録後の接続先を保証するものではありません。

現在地が目的地として判定できたカチャカの一覧を返します。 カチャカの現在位置から算出した最寄りの目的地のうち、距離閾値以内と判定されたものがある場合のみ含まれます。 閾値は locationPresenceThreshold 設定で変更できます。 判定結果はリアルタイムの位置推定に依存するため、環境によって変動することがあります。

指定したシリアル番号のカチャカをフリート管理システムから登録解除します。カチャカ本体のデータは削除されません。 対象カチャカが共有マップの共有元になっている場合は登録解除できず 409 を返します（共有マップとそれに紐づくワークフロー定義が連鎖削除されるのを防ぐため）。先に共有元を切り替えるか、マップの使用を解除してください。

フリート管理 UI 上の表示名を更新します。 対象カチャカがフリート管理システムに登録済みである必要があります。

カチャカへの接続設定（IP 取得方法および IP アドレス）を更新します。 mDNS から手動設定への切り替え、手動設定から mDNS への切り替え、手動設定で IP アドレスが変わった場合に使用します。 更新後、フリート管理システムは新しい設定でカチャカへ接続を試みます。 接続に失敗するとエラーが返ることがあります。ネットワーク変更前後で正しい ipSource を指定してください。

カチャカの現在位置（x, y, theta）と、現在選択中のマップ ID を返します。最寄りの目的地との距離が閾値以内の場合は matchedLocationId も含まれます。 対象カチャカがフリート管理システムに登録済みである必要があります。

カチャカ本体の OS を再起動します。実行中タスクがある場合は失敗することがあります。 対象カチャカがフリート管理システムに登録済みである必要があります。

カチャカをメイン充電ドックへ移動させます。 メイン充電ドックが未設定の場合、またはカチャカがタスク実行中など操作できない状態の場合は失敗します。 充電ドックに戻るワークフロー（AUTO_HOMING）をキューに登録して実行します。完了まで時間がかかることがあります。 充電ドックへの到着後、バッテリー充電が開始されます。

カチャカを指定した目的地または目的地グループへ移動させます。 ワークフロー定義を作らず、一時的なワークフローを直接登録して実行するため、 走行制御エリアなどを考慮した走行になります。 カチャカが低電池・タスク実行中など割り当てできない状態の場合は、実行可能になるまで待機します。

カチャカが現在載せている台車を、その場に降ろします。 対象カチャカがフリート管理システムに登録済みである必要があります。

カチャカの現在位置にある台車を載せます。台車が近傍にない、または既に別の台車を載せている場合は失敗します。 対象カチャカがフリート管理システムに登録済みである必要があります。

カチャカの自己位置推定を、メイン充電ドックの座標にリセットします。マップ上で位置がずれた際のリカバリ操作に使用します。 対象カチャカがフリート管理システムに登録済みである必要があります。

カチャカの自己位置推定を、指定マップ上の目的地座標にリセットします。リクエストで mapId と locationId を指定します。 対象カチャカがフリート管理システムに登録済みである必要があります。

全登録カチャカのバッテリー残量（%）を一括取得します。 詳細なエラー内容はレスポンスの errorCode を参照してください。

キャンセル(停止)指示がまだ実機に届いていないロボットの一覧を返します。 サーバDB上は「キャンセル済み」でも、切断等により実機がまだ動作している可能性がある状態を表します。 配信完了・意図の陳腐化で解消されると一覧から消えます。 変化は WebSocket の UPDATE_ROBOT_PENDING_STOP イベントでも即時配信されます。

全登録カチャカの isReady 状態（タスク実行可能か）を一括取得します。 詳細なエラー内容はレスポンスの errorCode を参照してください。

本システムの運用ポリシー上、設定修正が必要なカチャカのみ返します。 カチャカ自身が返す非同期エラーの一覧ではありません。 全ての警告や障害を網羅するAPIではなく、正常運用できない設定状態のみを対象とします。

全カチャカのカチャカ設定（音量・速度・安全機能など）の一覧を返します。 フリート管理システムに保存されている最新の設定値が対象です。 カチャカ本体の設定変更後、反映まで時間がかかる場合があります。 設定の更新は PUT 系 API を使用してください。

複数カチャカの設定を一括更新します。 リクエストに含まれたカチャカのみが更新対象です。 各カチャカ本体へ設定が反映されますが、反映完了まで時間がかかる場合があります。 一部のカチャカで失敗した場合、全体がロールバックされない点に注意してください。

複数カチャカの接続先 Wi-Fi を一括で切り替えます。 各カチャカ本体へ SetWifiConfig（gRPC）で Wi-Fi 設定が反映されます。

リクエスト

• robots: カチャカごとに serialNumber と完全な wifiConfig を指定する（個別 API と同じ設定形式）
• 共通設定と個別設定の組み立てはクライアント側の責務

注意

• 切り替えが成功すると、フリート管理システムとカチャカの接続が切れる場合があります。
• フリート管理システム側のカチャカ IP 設定（robots.ipAddress / ipSource）は更新しません。再接続時は同一ネットワークへの接続と IP 設定の手動更新が必要です。
• パスワード・証明書はリクエスト処理時のみ使用し、フリート DB には保存しません。
• 一部のカチャカで失敗した場合、成功したカチャカはロールバックされません。

指定カチャカのカチャカ設定（音量・速度・安全機能など）を返します。 フリート管理システムに保存されている最新の設定値が対象です。 未登録のカチャカのシリアル番号を指定した場合は 404 になります。 設定の更新は PUT /robots/{serialNumber}/settings を使用してください。

指定カチャカの設定を更新します。音量・速度・安全機能など、カチャカ本体の各種パラメータが対象です。 対象カチャカがフリート管理システムに登録済みである必要があります。

指定カチャカの接続先 Wi-Fi を切り替えます。 カチャカ本体へ SetWifiConfig（gRPC）で Wi-Fi 設定が反映されます。

認証方式

• WPA_PSK: SSID + パスワード
• WPA_EAP_TLS: SSID + identity + クライアント証明書（PKCS#12, Base64）+ CA 証明書（DER, Base64）

IP アドレス

• AUTOMATIC: DHCP による自動取得
• FIXED: 固定 IP（ipAddress・subnetMask 必須）

注意

• 切り替えが成功すると、フリート管理システムとカチャカの接続が切れる場合があります。
• フリート管理システム側のカチャカ IP 設定（robots.ipAddress / ipSource）は更新しません。再接続時は同一ネットワークへの接続と IP 設定の手動更新が必要です。
• パスワード・証明書はリクエスト処理時のみ使用し、フリート DB には保存しません。
• 成功時のレスポンス body は空です。

指定カチャカが本体側で利用可能なマップ ID の一覧を返します。フリート管理システムのマップ一覧とは一致しない場合があります。 対象カチャカがフリート管理システムに登録済みである必要があります。

指定カチャカ本体から未共有・未使用のマップを削除します。 カチャカ本体での削除に成功した後、フリート管理システムのマップ一覧からも削除します。

全カチャカで発生中の非同期エラー（アラート）を一覧取得します。 詳細なエラー内容はレスポンスの errorCode を参照してください。

指定カチャカの作業マップを切り替えます。切り替え完了まで待機します。 対象カチャカがフリート管理システムに登録済みである必要があります。

API レスポンスに含まれる errorCode を、表示用メッセージへ変換するためのエラーコード定義（ErrorCodeJson）を返します。 定義はサーバーに保存された JSON（未保存の場合は同梱のデフォルト定義）から読み出します。 この API 自体は errorCode を返すものではなく、参照用の定義データです。

全登録カチャカのネットワーク情報（IP アドレス等）を一覧取得します。 詳細なエラー内容はレスポンスの errorCode を参照してください。

フリート管理システムが各カチャカから取得したマップの一覧を返します。 各マップについて、共有済みかどうか、共有元カチャカのシリアル番号などが含まれます。 共有前のマップも一覧に含まれるため、/sharedMaps/ 配下の API を呼ぶ前に共有状態を確認してください。 マップ画像の取得は /maps/{mapId}/image など別エンドポイントを使用します。

マップ名を変更します。

マップに設定されたパラメータセットキー（カチャカ側の設定プリセット識別子）を取得します。 詳細なエラー内容はレスポンスの errorCode を参照してください。

マップのパラメータセットキーを更新します。共有済みマップの場合はカチャカ側にも反映されます。 詳細なエラー内容はレスポンスの errorCode を参照してください。

マップ画像を PNG 形式で返します。 ファイルサイズが大きい場合があるため、事前に imageMetadata でサイズを確認することを推奨します。 画像は指定カチャカから取得した最新のマップデータに基づきます。 serialNumber クエリパラメータで取得元カチャカを指定する必要があります。

マップのプレビュー画像（縮小版）を PNG 形式で返します。 詳細なエラー内容はレスポンスの errorCode を参照してください。

到達不可能領域を示す画像を PNG 形式で返します。 詳細なエラー内容はレスポンスの errorCode を参照してください。

指定カチャカの現在マップを、フリートを通して複数台で共有できる状態にします。 共有元カチャカのマップデータ（目的地・エリア・台車など）がフリート管理システムに取り込まれます。 共有後は /sharedMaps/{mapId}/... で目的地やエリアを編集でき、変更は参加カチャカへ同期されます。 既に別の共有マップが存在する場合など、前提条件を満たさないとエラーになることがあります。

指定した複数の共有マップの共有元カチャカ（originSerialNumber）を、指定したカチャカへまとめて切り替えます。 共有元カチャカが故障した場合などに、別のカチャカへ共有元を付け替えてワークフローを維持するために使用します。 本エンドポイントは共有元シリアル番号の差し替えのみを行い、カチャカ本体への地図同期は行いません。 切り替え前に対象マップを変更前の共有元で同期し、各カチャカ（特に切り替え先）が最新の地図情報を持つ状態にしておくことを推奨します。 切り替え先カチャカがそのマップを保有していない（maps に該当行が無い）場合は 409 で弾きます（共有元が実体を持たない不整合を防ぐため）。 全件成功または全件失敗（atomic）で、一部のマップのみ切り替わることはありません。

共有マップごとに、共有元と内容が異なる共有先カチャカを返します。 判定対象は対象マップを現在利用中の共有先のみです。

driftKinds が空でないカチャカには共有元での変更が反映されておらず、マップの共有が必要です。 差分のない共有先、および差分のある共有先が1台もいないマップは結果に含めません。 共有元の情報が無く比較できなかった項目は、差分としては扱いません。