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

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

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

資格情報そのもの — 名前の付け方、IP制限、クライアント ID とシークレットの表示場所、それらをトークンに交換する手順 — は自社システムをつなぐ が扱います。ここでの名前は、それを使うシステムの名前にしてください。あとで監査証跡でこの名前を読むことになるので、 API キー 3 より ロビーのターンスタイル のほうが見分けがつきます。

ゲートに必要な APIスコープ は 1 行だけです。

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

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

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

返るのは自分で解釈する状態ではなく判定です — valid、expired、cancelled、 wrongLocation など — そしてあわせて isGranted が返ります。バリアが実際に従うのはこの項目です。判定の一覧は来訪者バッジ API が返すものにあります。

3. 来訪を記録する

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

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

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

どちらも読み取るたびに呼び出して安全で、判定とあわせて実際に何が記録されたかを示す action を返します — 中にいるあいだの 2 回目の読み取りは、意図的に何も書き込みません。判定、 action、そしてチェックアウトと再入館の違いは来訪者バッジ API が返すものを参照してください。

4. 動作を確認する

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

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

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

うまくいかないとき

すべてのバッジを通してしまうゲートから、誰の来訪も記録されないゲートまで、実際に起きる 9 つの症状とその原因はゲートが拒否すべきバッジを通してしまうにあります。