レセプション顔登録 API 仕様
レセプション顔登録システムで使用する API の一覧・イベントリスト・プロセスとのメッセージマッピング。 NES 提供の外部 API（共有マネージャー／レセプション顔登録ゲートウェイ）に加え、演出ゾーン横断で 参照する内部データストア（MF-1）の API を含む。MF-1 の全体仕様・設計論点は docs/mf-1/ARCHITECTURE.md を、全体フロー・プロセス定義は ARCHITECTURE.md を参照。
| API 系統 | 提供元 | 主な用途 | プロトコル |
|---|---|---|---|
| 共有マネージャー API | 共有マネージャ（ME-2、NES） | 訪問者情報取得・顔画像取得 | REST |
| レセプション顔登録ゲートウェイ API | レセプション顔登録ゲートウェイ（ME-1、NES） | 撮影・レセプション顔登録制御 | ZeroMQ（REQ/REP + PUB/SUB） |
| データストア API（MF-1 モック実装） | データストア（MF-1、演出用PC 内蔵 / Uniba） | 顔画像キャッシュ・メタデータ（顔パラメータ）保存／グループ取得 | REST |
共有マネージャー API（サイネージ用訪問者情報取得）
共有マネージャー（ME-2）が提供する、サイネージ／演出側から訪問者情報を取得するための REST API。 詳細仕様は 共有マネージャーAPIサイネージ用訪問者情報取得.html を参照。
- ベースURL（本番）:
https://facesharemng.bss.local/v1 - ベースURL（開発）:
https://facesharemngdev.bss.local/v1 - 取得元: 共有マネージャ（ME-2、NES チーム開発）。呼び出し元は主に演出用PC（MD-2）。API-3 は他演出ゾーン（またはそれを代表する演出用PC）が呼び出す。
- GW 経由の訪問者情報配信との関係: ゲートウェイ（ME-1）からの「訪問者情報配信」は事前登録の通知トリガー（当日データが利用可能になった合図）として扱う。実データの取得は演出用PC が API-1／API-2 で共有マネージャから取得する。
- 同意のみ完了者: 顔データ未登録のため、他演出ゾーンは API-3 による顔画像参照を行わない。
レセプション顔登録ゲートウェイ API（プロセス B 撮影・登録制御）
レセプション顔登録ゲートウェイ（ME-1、Face Registration Gateway）が提供する、ミラーサイネージ向け顔撮影・登録制御 API（v1.0.4）。 詳細仕様は 顔登録ゲートウェイ_API仕様書_1.0.4.html を参照。
- 通信プロトコル: ZeroMQ
- REQ/REP サーバ:
zmq://gateway-server:5555/zmq— クライアント（演出用PC）からのリクエスト受信用 REP ソケット - PUB/SUB サーバ:
zmq://gateway-server:5556/zmq— 処理進捗イベント配信用 PUB ソケット - 呼び出し元: 演出用PC（MD-2）。GW（ME-1）はリクエストに対して同期
GenericResponse（accepted/ エラー）を返し、進捗は PUB/SUB で非同期通知する。 - 配信レート・遅延（実測）: PUB/SUB の進捗イベント配信は実測で約 10fps、エンドツーエンド遅延 0.5〜1.0 秒。特に GW-EVT-1
capture_status_notifiedの連続配信がこのレートで届く。 - イベント様式のサンプルログ: サイネージゲートウェイが実際にイベント通知を行ったときのログはこちら。
event_log_sample.txtに格納（NES 提供）。
リクエスト（REQ/REP）
演出用PC → GW へ送るコマンド。すべて GenericResponse（timestamp / status / job_id / error_code / message）を同期返却。
イベント（PUB/SUB）
GW → 演出用PC へ非同期配信される進捗イベント。すべて event_type / job_id / timestamp を含む。
プロセスBでのメッセージマッピング
| プロセスB ステップ | 既存 ID | GW API |
|---|---|---|
| [PB-2] 撮影開始指示 | PB-2 | GW-REQ-1 start_face_capture |
| [PB-7] 撮影・加工中の状態通知 | PB-7 | GW-EVT-1 capture_status_notified（連続配信） |
| 撮影完了 → 登録処理開始（成功側） | PB-7 → PB-8 | GW-EVT-3 registration_started |
飛び入り参加者の visitor_id 採番 | PB 例外 | GW-EVT-4 target_visitor_id_notified |
| 登録仮完了（バックエンド登録要求完了） | PB-8 成功 | GW-EVT-5 registration_provisionally_completed |
| 登録最終完了 | PC-1 直前 | GW-EVT-6 registration_completed |
| レセプション顔登録失敗（システム／品質） | PB-8 失敗 / PB 例外 | GW-EVT-7 registration_failed（is_retryable で分岐） |
| FCH 強制中止／タイムアウト中断 | PB 例外 | GW-REQ-2 cancel_face_capture → GW-EVT-2 capture_canceled |
| 再登録（タブレット「再登録 or 諦め」→ 再登録） | PB 例外 | GW-REQ-3 retry_face_registration |
| 登録済み顔データ削除 | PB／C 例外 | GW-REQ-4 delete_face_registration |
注意事項
- 座標系:
CaptureStatusNotifiedEventの各種座標（顔／頭部／目／切り出し）は カメラ原座標系。鏡（ミラー）表示への反転は呼び出し側（演出用PC）で行う。 - ガイダンスコード:
guidance_codeは対象人物への動作指示（例:look_down= 下を向いて）。鏡側の演出にそのまま使える設計。 - job_id:
StartFaceCaptureRequestのレスポンスで返るjob_idを、以降のキャンセル要求／イベント突合に使用する。 - 配信レート・遅延前提: PUB/SUB イベントは実測で約 10fps（1フレーム ≒ 100ms）、遅延 0.5〜1.0 秒。鏡側のガイド表示・品質判定演出は、このフレームレートと最大 1 秒のラグを前提に設計する（しきい値・アニメーションの応答時間に余裕を持たせる）。
- 同意情報の送信 API はない: 同意完了状態は演出用PC がローカル保持し、NES へ送信する専用 API は存在しない。レセプション顔登録に進む場合は GW-REQ-1
start_face_capture（[PB-2] 撮影開始指示）の送信をもって同意済みとして扱う。 - 同意のみ完了者: SA-2 同意後に SA-3 で同意のみ完了にした場合はプロセス B に進めないため、GW-REQ-1
start_face_captureは送信しない。以降の GW イベント待受、PC-2 顔特徴量保存、API-3 顔画像参照も行わない。
データストア API（MF-1、演出ゾーン横断の単一データストア）
演出用PC（MD-2）内に組み込まれた**単一データストア（MF-1）**が提供する REST API。 レセプション／コリドー／イマーシブ／アクセラレーションの各演出ゾーンは個別 API を持たず、 この単一データストア（/api/datastore）へ集約される。タングラム（Uniba）開発。 プロセス C のPC-2 完了情報保存・PC-3 他演出への配信の実体にあたる。
本節はモック実装（nec-bss-mock #104）の API 契約を記述する。 MF-1 の設計仕様（エンドポイント MF1-API-1〜5・設計論点）は
docs/mf-1/ARCHITECTURE.mdが正本。 設計仕様は本実装に整合済み（ベース/api/datastore・保存PUT・保存キーmetadata）。 唯一、グループ内訪問者一覧のみ設計がGET /api/datastore/groups/{group_id}/visitors（visitors サフィックス付き）で、 モックのGET /api/datastore/groups/{group_id}（下記 DS-2）をこの形へ実装側で修正予定。
NES 提供の 共有マネージャー API（API-1〜3）／レセプション顔登録ゲートウェイ API（GW-REQ/EVT）とは 別系統の内部 API。レセプション顔登録で得た顔画像・氏名・顔パラメータ（metadata）をデータストアに保持し、 他の演出ゾーンが
visitor_id／group_id単位で取得・再利用する。
- ベースパス:
{origin}/api/datastore（演出用PC と同一ホスト・同一ポート） - 認証: なし（クローズドネットワーク内）
- レコード未存在は
404+{ "message": ..., "visitor_id" | "group_id": ... } - レスポンス内の
face_image_urlは、リクエスト元オリジンに基づく絶対 URLで返す （例:http://md-2.local:3000/api/datastore/visitors/{visitor_id}/face）。 リバースプロキシ経由ならそのホスト名がそのまま反映される。MQTT 配信時のみ相対パス（後述）。
エンドポイント一覧
- データストア直下は
visitors／groupsの 2 コレクション。visitor_idは/visitors/、group_idは/groups/配下にあり、セグメントは衝突しない。 - グループ定義（
groups／visitors）は共有マネージャー側にのみ存在するため、 DS-1／DS-2 はデータストアがvisitor_idで突き合わせてグループ単位の取得口を提供する。 日付クエリは管理系のGET /api/admin/groups?date=と同じ流儀。
レコードのデータモデル
| 項目 | 型 | 説明 |
|---|---|---|
visitor_id | string（主キー） | 訪問者 ID。レコードの一意キー |
metadata | object | null | スキーマレスなメタデータ（顔特徴量・氏名等の任意 JSON）。未設定は null |
face_image_url | string | null | キャッシュ顔画像の取得 URL。顔画像キャッシュがあるときのみ非 null |
updated_at | string（ISO8601） | 最終更新時刻 |
- 1 レコードに「顔画像キャッシュ」と「メタデータ」を持ち、**部分更新（upsert）**される。 顔画像だけ／メタデータだけの更新でも、もう一方は保持される。
- DS-2 のグループ全件取得では各レコードに
visitor_nameとface_status（共有マネージャー仕様の登録状態still／inprocess／provisional／complete／error）を併記し、 演出側が「登録完了の人だけ表示する」等の判定に使える。
主なリクエスト／レスポンス例
DS-1 グループ一覧（200）— ?date= 省略時は当日。該当無しは groups: []。
json
{
"date": "20260604",
"groups": [
{ "group_id": "G1779...", "group_name": "○○株式会社 ご一行", "visit_date": "20260604",
"language": "ja", "visitor_count": 5, "record_count": 3 }
]
}visitor_count: グループの訪問者総数。record_count: うちデータストアにレコードがある数。 language: 団体の表示言語（ja／en）。
DS-2 グループ全件取得（200）— 未存在グループは 404 + { message, group_id }。
json
{
"group_id": "G1779...", "group_name": "○○株式会社 ご一行",
"visit_date": "20260604", "language": "ja",
"records": [
{ "visitor_id": "V1779...", "visitor_name": "永倉 様", "face_status": "complete",
"face_image_url": "http://md-2.local:3000/api/datastore/visitors/V1779.../face",
"metadata": { "visitor_name": "永倉", "features": { "...": 0 } },
"updated_at": "2026-06-04T06:00:00.000Z" }
]
}DS-3 レコード取得（200）— 未作成は 404 + { message, visitor_id }。
json
{
"visitor_id": "V1779...",
"face_image_url": "http://md-2.local:3000/api/datastore/visitors/V1779.../face",
"metadata": { "visitor_name": "山田 太郎", "features": { "...": 0 } },
"updated_at": "2026-05-31T04:00:00.000Z"
}DS-4 顔画像取得 — Content-Type はキャッシュ時の MIME、Cache-Control: no-store。未キャッシュは 404。
DS-5 顔画像キャッシュ — body は画像バイナリ（Content-Type 省略時は image/jpeg）。空 body は 400。 レスポンス { visitor_id, face_image_url }。
DS-6 メタデータ保存 — body は任意 JSON（application/json）。既存メタデータは上書き（顔画像キャッシュは保持）。 レスポンスは保存後のレコード（DS-3 と同形）。
DS-7 メタデータクリア — 顔画像キャッシュは保持。レスポンスはクリア後のレコード（metadata: null）。レコードが無ければ null。
プロセス C での自動保存・配信
レセプション顔登録の最終完了（GW-EVT-6 registration_completed）時に、演出用PC が以下を自動実行する。
認識時の顔画像をキャッシュ（DS-5 相当）。
メタデータ（氏名・顔特徴量
features・completed_at等）を保存（DS-6 相当）。MQTT で各演出ゾーンへ配信トリガーを送る:
datastore/registration-completed（イベント、QoS 1）datastore/visitor/{visitor_id}（最新値、QoS 1・retained）
ペイロード:
{ visitor_id, visitor_name, face_image_url }。 MQTT は HTTP リクエスト文脈が無いためface_image_urlは相対パスで配信し、 受信側が自身の参照先オリジンを前置して解決する（HTTP API のレスポンスは絶対 URL）。2026-06-04 会議での確定: ホスピタリティ等の演出を顔登録完了直後に即座に出すため、 uniba 側から push 型で
visitor_idと顔写真を送る。トランスポートは MQTT over WebSocket（来館者タブレットと揃える）。
配信を受け取った演出ゾーンは、本 API（DS-3／DS-4）から実データを取得する。
注意事項
- キャッシュ顔画像の当日中破棄: 顔画像は用済み後（可能であれば当日中）に破棄する方針 （NES 回答 / Issue #26・#36）。破棄対象はキャッシュ顔画像のみで、
metadata（顔特徴量・氏名）は再訪に備えて保持する。既定の基準時刻は 0:00 JST。 破棄後は DS-3／DS-4 のface_image_urlがnullになる。 - 同意のみ完了者: 顔登録に進まないため PC-2（DS-5／DS-6）の保存・配信は行わない。
metadataはスキーマレス。保存した JSON はそのまま保持・返却される（バリデーションなし）。