訪客證 API 會回傳什麼

驗證、簽到、簽退可能回傳的每一種判定、可能記錄的每一種 action，以及三者刻意不一致的那一個場合 —— 簽退之後又回來的訪客。

更新於 2026年8月30日

閘門會用到的三個呼叫 —— 驗證、簽到、簽退 —— 都接受一個掃描到的代碼，也都用同一種形式回答。這一頁講的就是那個形式：閘門要依循的判定，以及 Offision 在回答的同時記錄了什麼。使用它們的步驟在用 Offision 訪客證開啟您的閘門。

判定

`verify`	意思
`valid`	此刻在這棟大樓有效
`notYetValid`	是真的訪客證，但訪問還沒開始
`expired`	訪問已經過去
`cancelled`	訪問或訪客證已取消 — 還在等您的系統提供代碼的訪客證也算在內
`rejected`	審批人拒絕了這位訪客
`waitingForApproval`	還沒有人審批這位訪客
`wrongLocation`	真實且有效的訪客證 — 但屬於另一棟大樓
`alreadyCheckedOut`	這位訪客已經離開
`notFound`	代碼對不到任何東西

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

簽到與簽退除了判定之外還會回傳 action，說明實際寫入了什麼。

`action`	什麼時候會拿到
`checkedIn`	首次到訪 — 訪客證轉為訪問中
`alreadyCheckedIn`	訪客本來就在裡面。沒有寫入任何東西
`reCheckedIn`	離開後又回來。原本的離開記錄被清除
`checkedOut`	訪客證轉為已離開
`alreadyCheckedOut`	已經記錄過。離開時間維持不變
`none`	沒有記錄任何東西 — 被拒絕的掃描、長期訪客證，或從未簽到的人離開

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

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

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