用 Offision 訪客證開啟您的閘門

這是大樓既有的門禁 — 旋轉閘門、閘機、大堂讀卡機，或另一套訪客管理系統 — 與 Offision 訪客管理 搭配運作的方式。訪客證由 Offision 發出；您的讀卡機掃描它，向 Offision 詢問它此刻是否有效； 開啟閘門的是您的系統；而同一個呼叫也記錄了這個人已經進來。

需要準備的東西

• 一套門禁系統，其讀卡機能在掃描到代碼時呼叫 HTTPS API，並依回應行動
• 該系統對外呼叫時使用的固定 IP 位址
• Offision 這一端約一小時，另加門禁廠商那一端所需的時間
• 在 Offision 先建立一筆測試訪問，這樣才有真的訪客證可以掃描

1. 建立 API 憑證

選擇 新增。名稱請以使用它的系統來命名 — 日後您會在稽核記錄裡讀到這個名稱， 大堂旋轉閘門 比 API key 3 容易辨認得多。

API 權限範圍 以列為單位，每一列是一個模組加上一種存取層級。閘門只需要一列：

只有在您同時要處理步驟 4 的會議室門時，才需要再加上 user.readwrite 與 bookableResource.read。

權限範圍是「沒給就不通」：呼叫沒有列出的模組會得到 403，而權杖本身看起來完全正常。IP限制 請填入該系統對外呼叫的位址。

用戶端 ID 與 用戶端密鑰 不在這張表單裡 — 它們由 Offision 產生，憑證儲存後顯示在詳細面板中。

接著由您這端到 OAuth 端點換取存取權杖，使用 grant_type=client_credentials、表單編碼，用戶端 ID 與密鑰可以用 HTTP Basic 認證送出，也可以放在表單欄位裡。確切格式請見 API 參考中的 權杖端點。

2. 檢查掃描到的代碼

把讀卡機讀到的內容原樣送到 驗證呼叫， 連同閘門所在的大樓一起。您不需要自己判斷手上是哪一種代碼 — QR 裡的訪客證 uid、印在訪客證上的六字元 訪客代碼、您自己的系統發出的代碼，或八位數的長期訪客證代碼，都會以同樣的方式解析。

回傳的是一個判定，而不是要您自己解讀的狀態：

同時回傳的還有 isGranted，那才是閘門真正依循的欄位；以及代碼背後的訪客與訪客證，讓閘門旁的螢幕 可以顯示姓名而不是一串代碼。

3. 記錄到訪

上面的檢查不會改變任何東西。略過這一步，每張訪客證都會永遠停在 未訪問：接待處看不到訪客抵達、 接待人不會收到通知，訪問報表也一直是空的。

簽到呼叫 接受同樣的代碼、以同樣的格式回答，並在判定為 valid 時記錄到訪。所以一個既要放行又要記錄的閘門， 只需要 一個 呼叫，而不是兩個 — 步驟 2 那個單獨的檢查，是給只做驗證的讀卡機用的，例如出口側的 掃描器或大堂的顯示裝置。

簽退呼叫 是它的鏡像，給同時讀取離場的閘門使用。

兩者每次掃描都可以安全呼叫。除了判定之外，它們還會回傳 action，說明實際記錄了什麼：

在動手寫閘門邏輯之前，有兩個行為值得先知道：

• 離開比進入寬鬆。 簽退接受任何能解析出來的訪客證，包括已過期的，這樣才不會有人因為開會期間 通行證失效而被困在大樓裡。真的簽到過的人才會記錄離開；沒簽到過的人閘門一樣會開，但 action 會 回傳 none，不會憑空生出一次訪問。
• 離開後回來可以重新進入，前提是該次訪問涵蓋那棟大樓。驗證會回報 alreadyCheckedOut 並拒絕； 同一組代碼的簽到則會把訪問重新打開。這是兩個呼叫刻意不一致的唯一之處，也是閘門應該呼叫簽到、 而不是自己依驗證的答案下判斷的原因。

每週都來的人所持的長期訪客證沒有可以打開的訪問，所以 action 永遠是 none。有效的長期訪客證一樣 會開門，那正是它存在的意義。長期訪客證有自己的 端點， 提供啟用與停用的操作，讓您不必刪除這個人就能停掉他的通行證。

4. 由預約開啟會議室門

這是另一個問題，值得分開看：不是站在大堂閘機前的訪客，而是站在會議室門前的員工。沒有人掃描任何東西 — 門必須事先就知道誰在什麼時候預約了這個房間。

• 用設定門禁卡的呼叫，把每個人的卡號存到他們的 Offision 使用者上（UserCard、UserCard2、 UserCard3，所以一個人可以持有不只一張），卡片繳回時再用移除門禁卡清掉。這需要 user.readwrite。
• 訂閱預約異動，提供您的回呼網址與要關注的資源。這些資源上的預約被建立、更動或取消時，Offision 會送到 該網址。
• 每次收到回呼時，把可預約資源的 ID 對應到您這端控制的門，讀出主辦人與參與者，再把他們的卡號轉成該 時段的權限。
• 您這端重新連上時，請重新讀取當天的資料。把回呼當成提醒，把查詢當成事實 — 漏掉的回呼在其他地方是看 不出來的。

如果會議室門收的是代碼而不是卡片，可預約資源的門禁金鑰是另一條路：讀取房間的一次性、每日或固定金鑰， 並訂閱每日與一次性金鑰，金鑰每次輪替時就會推送新的給您。

5. 確認是否成功

以下四項會各自獨立失效，請全部測試：

• 一張正常的訪客證。 在期間內掃描真的訪客證。您應該取得 valid、isGranted 為 true 與訪客姓名，閘門也應該打開。
• 回寫。 之後在 Offision 裡看那張訪客證。它應該已經變成 訪問中，受訪者也應該收到通知。
• 同一張再掃一次。 第二次仍然應該放行、回傳 alreadyCheckedIn，而且簽到時間完全沒有變動。
• 一張不該過的訪客證。 刻意掃描一張已取消的訪客證，以及一張明天的訪客證。兩張都必須被拒絕。

最後一項是最常被略過的。一台只用有效訪客證試過的讀卡機，就是一台誰都放行的讀卡機。

出問題的時候