Offision の来訪者バッジでゲートを開ける

建物が自前で持っている入退室管理 — ターンスタイル、ゲート、ロビーのリーダー、あるいは別の来訪者 管理システム — を Offision の来訪者管理と組み合わせる方法です。バッジを発行するのは Offision。 自社のリーダーがそれを読み取り、いまこの瞬間に有効かどうかを Offision に尋ね、バリアを開けるのは 自社側。そして同じ呼び出しが、その人が入館したことを記録します。

準備するもの

• コードを読み取ったときに HTTPS API を呼び出し、その答えに従って動けるリーダーを備えた入退室管理システム
• そのシステムが発信する固定の送信元 IP アドレス
• Offision 側で 1 時間程度、加えて入退室管理ベンダー側の作業時間
• 実際に読み取れるバッジがあるよう、テスト用の訪問予定を Offision に 1 件登録しておく

1. API 資格情報を作成する

追加 を選びます。名前は、それを使うシステムの名前にしてください。あとで監査証跡でこの名前を読む ことになるので、API キー 3 より ロビーのターンスタイル のほうが見分けがつきます。

APIスコープ は行で指定し、1 行がモジュールとアクセスレベルの組み合わせです。ゲートに必要なのは 1 行だけです。

user.readwrite と bookableResource.read は、手順 4 の会議室のドアも扱う場合にだけ追加してください。

スコープは「未許可なら拒否」です。行のないモジュールを呼び出すと 403 が返り、トークン自体は正常なまま 見えます。IP制限 には、そのシステムが発信するアドレスを入力します。

クライアント ID と クライアントシークレット はこのフォームにはありません。Offision が生成し、 保存後に詳細パネルに表示されます。

自社側はこれらを OAuth のトークンエンドポイントでアクセストークンに交換します。grant_type=client_credentials、 フォームエンコード、クライアント ID とシークレットは HTTP Basic 認証情報としても、フォームの項目としても 送れます。正確な形は API リファレンスの トークンエンドポイント を参照してください。

2. 読み取ったコードを照会する

読み取った内容をそのまま 照会の呼び出し に、ゲートが設置されている建物とあわせて送ります。どの種類のコードを持っているかを自社側で判別する必要は ありません。QR の中のバッジ uid、バッジに印字された 6 桁の ビジターコード、自社システムが発行した コード、8 桁の長期バッジコード — どれも同じように解決されます。

返るのは、自分で解釈する状態ではなく判定です。

あわせて isGranted が返ります。バリアが実際に従うのはこの項目です。コードの背後にある来訪者とバッジも 返るので、ゲート脇の画面にコードではなく氏名を表示できます。

3. 来訪を記録する

いまの照会は何も変えません。この手順を省くと、すべてのバッジは 未訪問 のままです。受付には来訪者が到着した ことが表示されず、訪問先には通知が届かず、訪問レポートも空のままになります。

チェックインの呼び出し は同じコードを受け取り同じ形で答え、判定が valid のときは来訪も記録します。つまり、入館の許可と記録を 両方行うゲートが呼ぶのは 1 本 であって 2 本ではありません。手順 2 の照会は、退館側のスキャナーや ロビーの表示など、確認だけを行うリーダーのためのものです。

チェックアウトの呼び出し はその対で、入館だけでなく退館も読み取るゲート向けです。

どちらも、読み取るたびに呼び出して安全です。判定とあわせて、実際に何が記録されたかを示す action が返ります。

ゲート側の処理を書く前に知っておきたい挙動が 2 つあります。

• 退館は入館より緩やかです。 チェックアウトは解決できるバッジをすべて受け付けます。期限切れのものも 含めてです。会議のあいだにパスが切れたからといって、館内に閉じ込められる人が出ないようにするためです。 退館が記録されるのは実際にチェックインした人だけで、していない人にはゲートは開きますが action は none になります。存在しなかった訪問を作り出さないためです。
• 退館後に戻ってきた人は再入館できます。 ただしその訪問がその建物を含んでいる場合に限ります。照会は alreadyCheckedOut を返して拒否し、同じコードでのチェックインは訪問を開き直します。2 つの呼び出しが 意図的に食い違う唯一の場所であり、ゲートが照会の答えで自分で判断するのではなくチェックインを呼ぶべき 理由でもあります。

毎週のように訪れる人が持つ長期バッジには開くべき訪問がないので、action は常に none です。有効なもの であればゲートは開き、それがこのバッジの目的です。長期バッジには 専用のエンドポイント があり、有効化と無効化の操作で、人を削除せずにパスだけを止められます。

4. 予約から会議室のドアを開ける

これは別の問題なので、分けて考える価値があります。ロビーのゲートに立つ来訪者ではなく、会議室のドアの前に 立つ社員の話です。誰も何も読み取りません。ドアの側が、誰がいつその部屋を予約したのかをあらかじめ知って おく必要があります。

• 各人のカード番号を Offision のユーザーに保存します（UserCard、UserCard2、UserCard3 の 3 枚まで 持てます）。カードが返却されたら削除します。user.readwrite が必要です。
• 予約の変更を購読します。コールバック URL と対象のリソースを指定すると、それらの予約が作成・変更・ キャンセルされたときに Offision がその URL へ送信します。
• コールバックのたびに、予約可能リソースの ID を自社側が制御するドアに対応づけ、主催者と参加者を読み取り、 そのカード番号をその時間帯の権限に変換します。
• 自社側が再接続したときは、その日の予約を取得し直してください。コールバックはきっかけ、クエリが正、と 扱うのが基本です。取りこぼしたコールバックは、それ以外の方法では見えません。

会議室のドアがカードではなくコードを受け付ける場合は、予約可能リソースのアクセスキーがもう一つの道です。 部屋のワンタイム、日次、固定のキーを読み取り、日次とワンタイムのキーは購読しておけば、更新されるたびに 新しいものが届きます。

5. 動作を確認する

次の 4 つは独立して壊れるので、すべて試してください。

• 正常なバッジ。 期間内に実物を読み取ります。valid、isGranted が true、来訪者の氏名が返り、 バリアが開くはずです。
• 書き戻し。 そのあと Offision でそのバッジを見ます。訪問中 に変わり、訪問先へ通知が届いている はずです。
• 同じバッジをもう一度。 2 回目も入館が認められ、alreadyCheckedIn が返り、チェックイン時刻が まったく動いていないことを確認します。
• 不正なバッジ。 キャンセル済みのバッジと、明日のバッジをわざと読み取ります。どちらも拒否されなければ なりません。

省かれがちなのは最後の 1 つです。正常なバッジでしか試していないリーダーは、誰でも通すリーダーです。

うまくいかないとき