スマートロックの入退室ログをAPIで取得し、勤怠システムやセキュリティ監視基盤に流したい。こうした依頼を受けたものの、機器ごとに履歴の持ち方がばらばらで、どこから設計すればよいか迷っている開発者・SIerの方は少なくありません。ログが取れると思って案件を進めたら、実際は管理画面からCSVを書き出すしかなかった、という例も現場ではよく見かけます。
ログ連携の成否を分けるのは、取得方式の選び方と、時刻・識別子・権限の設計です。ここでは、ポーリングとWebhookの使い分け、データ設計の確認点、業務システムへの連携パターンを順に整理し、最後に当社3ブランドでログを取得できる範囲を中立的にまとめました。

入退室ログをAPIで取得する3つの方式と選び方
結論から書くと、入退室ログの取得は「定期的に取りに行く(ポーリング)」と「発生時に送ってもらう(Webhook)」を組み合わせる設計が基本です。リアルタイム性が欲しい通知はWebhookで受け、漏れの補完や日次集計はREST APIの履歴取得で行うと、どちらか一方に頼るより取りこぼしに強くなります。
もうひとつの選択肢が、管理ソフトからのCSV書き出しです。APIを持たない機器や、ローカルPCで管理する構成ではこの方法しかないこともあります。
それぞれの特性を比べると、違いがはっきりします。ポーリングは実装が単純で、取得期間を指定して再取得できるのが強みです。一方で、取得間隔の分だけ遅延が出ますし、短い間隔で叩き続ければ相手側にも負荷がかかります。Webhookは扉が開いた直後に受信側へ通知が届くため、在室状況の表示やアラートに向いています。ただ、受信サーバーが停止していた時間帯の通知をどう扱うかはサービスによって異なり、再送の有無は必ず仕様書で確かめる必要があります。
現場でよくある例として、夜間にWebhook受信サーバーのメンテナンスを行った結果、その時間帯の入退室だけが勤怠データから抜け落ちていた、というケースがあります。翌朝のポーリングで差分を取り直す仕組みがあれば、こうした欠落は防げました。
「とりあえずWebhookだけで十分では?」と感じたことはありませんか? 通知は即時性、履歴APIは完全性、と役割を分けて考えるのが安全です。
Q: スマートロックの入退室ログをAPIで取得する方式は?
A: REST APIで履歴を定期取得するポーリングと、入退室の発生時に通知を受けるWebhookの2つが中心。両方を併用すると取りこぼしを補完できます。
ログ取得APIの設計で確認したいデータ項目と時刻の扱い
時刻、扉、利用者、認証方式、結果。入退室ログの1レコードに最低限ほしいのはこの5つです。どれかが欠けると、後段のシステムで「誰がどの扉を何時に通ったか」を再現できなくなります。
意外に見落とされやすいのが時刻の基準です。ログのタイムスタンプが「扉側の機器で認証した時刻」なのか「クラウドが受信した時刻」なのかで、集計結果がずれることがあります。通信が一時的に途切れた機器が後からまとめてログを送る構成では、受信順と発生順が入れ替わるのも珍しくありません。並び替えや重複判定には発生時刻とイベントIDを使い、受信時刻は参考値として扱うのが無難でしょう。機器側の時計がずれていれば、そもそも発生時刻が信用できなくなります。機器の時刻を自動で補正する仕組みがあるかどうかは、選定時に確認しておきたい点です。
APIの仕様書を読むときは、次の観点を押さえておくと手戻りが減ります。
- 履歴を期間・扉・利用者で絞り込めるか、ページングの方式は何か
- APIトークンの権限を、読み取り専用や特定の扉だけに限定できるか
- Webhookの通知単位(扉ごと・出来事ごと)と、受信側での重複排除に使えるID
- 利用者IDと人事システムの社員番号をどう対応づけるか
なかでもトークンの権限設計は見落とされがちです。勤怠連携のためだけに発行したトークンで遠隔解錠までできてしまうと、漏えい時の影響が大きくなります。「読む」と「開ける」は別のトークンに分ける、と覚えておいてください。
アクセスログは個人に紐づくデータです。顔認証を使う場合、顔特徴データは個人識別符号として個人情報に当たります。ログの保存期間や取り扱いは社内規程で定め、法令面の判断は個人情報保護委員会の公式情報などで確認することをおすすめします。
Q: 入退室ログAPIで必要なデータ項目は?
A: 発生時刻、扉ID、利用者ID、認証方式、認証結果の5項目が基本。順序の整合にはイベントIDと機器側の発生時刻を使うと安全です。
勤怠・所在管理への入退室ログ連携パターン
朝9時前、オフィスの入口で社員がカードをかざす。その瞬間の記録が勤怠システムに反映され、総務の担当者は打刻漏れを追いかけずに済む。API連携でよく描かれるのはこうした場面です。リサーチ時に参照した解説記事でも、APIで勤怠管理システムと連携し、入退室履歴を自動反映させたり、所在をリアルタイムに確認したりする使い方が紹介されています(参考:iTSCOM for Business)。
実装は大きく2パターンに分かれます。1つ目は、Webhookで受けたイベントを自社の中継サーバーに一度ためてから、勤怠SaaSや社内DBへ流す構成です。中継層を挟むと、通知先が増えても扉側の設定を変えずに済みますし、再処理もしやすくなります。2つ目は、夜間バッチで前日分の履歴をまとめて取得し、勤怠の締め処理に合わせて反映する構成です。リアルタイム性は落ちますが、運用はシンプルになります。
ここでひとつ寄り道をします。入退室ログをそのまま「労働時間」とみなしてよいかは、別の議論です。建物に入った時刻と業務開始の時刻は一致しないことも多いので、打刻の補助データとして使うのか、勤怠の正データにするのかは、労務担当と事前にすり合わせておいてください。
逆方向の連携も見逃せません。入社・退職・異動のたびに利用者を手作業で登録・削除していると、人数が多い企業ほど負担が大きくなります(参考:アスピック)。退職者の権限が残ったままになっていた、と気づいて冷や汗をかいた経験はありませんか? 人事システムを起点に利用者登録APIを呼び出す仕組みを作れば、ログ取得と権限管理が同じ連携基盤でまとまります。
Q: 入退室ログを勤怠システムに連携する方法は?
A: Webhookで受けたイベントを中継サーバー経由で勤怠システムへ流し、夜間にREST APIで前日分の履歴を取り直して差分を補う構成が一般的です。
エナスピレーション3ブランドで入退室ログを取得できる範囲
弊社のEPIC・Lavish・Guubは、ログを外部システムから取得できるかどうかが、ブランドと構成によって異なります。「どれでもAPIで取れる」わけではない点を先にお伝えしておきます。
電気錠のLavishでは、ネットワーク制御器 COA-23F/COA-45F にクラウドゲートウェイ GW-2(有線LAN)を追加すると、クラウドサービス WatchKey につながります。WatchKey のREST APIでは、入退室履歴を期間・扉・利用者で絞り込んで取得でき、Webhookで扉・出来事ごとの通知も受けられます。APIトークンの権限は操作ごと・扉ごとに絞れるため、前のセクションで触れた「読むだけのトークン」も作れます。操作の記録や、COA の時刻の自動補正にも対応しています。WatchKey の利用料は月額0円、APIの利用料・連携料も無料です(機器代・施工費・回線は別途、連携開発の当社受託は有償)。回線が切れても、COA-23F/45F に登録済みのカード・QRコードで入退室は続けられます。なお、GW-2 がない構成はローカルPCでの管理となり、クラウドAPIは使えません。構成の詳細は クラウドゲートウェイ GW-2 と クラウド・システム連携 のページにまとめています。
スマートロックのEPICは、別売のBluetoothモジュールと無線LANブリッジを追加した対応機種(FLASSA 1J ver.2、ZEUS 13D ver.2、FACEY 25D ver.2、SLEEKY 35D など)で WatchKey につながり、Lavish と同じ管理画面でまとめて扱えます。履歴の確認にはBluetoothモジュールが前提で、標準状態ではクラウド連携できない点にご注意ください。クラウド・APIの利用料は無料です。EPICで取得できるAPIの範囲は機種・構成によって異なるため、個別にお問い合わせください。
ロッカー用電子錠のGuubは、スタンドアロンで動作する製品です。クラウド管理やAPI連携、利用履歴のクラウド管理には対応していません。ログ連携が要件に含まれるロッカー案件では、この点を前提に機器構成を検討してください。

Q: Lavishの入退室ログをAPIで取得するには何が必要?
A: ネットワーク制御器 COA-23F/COA-45F とクラウドゲートウェイ GW-2 を組み合わせ、WatchKey のREST APIで期間・扉・利用者を指定して履歴を取得します。
扉の台数、既設の錠前、連携先のシステム、Webhookを受ける環境。この4点が分かれば、どの構成でログを取得できるかを具体的にご提案できます。案件の要件を整理したうえで、まずは構成のご相談からお気軽にお寄せください。