Support Hub/API & Integrations/重複および順序が乱れた打刻イベントの処理方法
Translated from the English article and reviewed by a person. Read the English original
Developer

重複および順序が乱れた打刻イベントの処理方法

重複および順序が乱れた打刻イベントの処理方法

 

リアルタイムの生体認証勤怠管理は単純に見えます。誰かがスキャンし、システムがイベントを受信して保存します。しかし実際には、勤怠データはもっと複雑です。同じイベントが二度届くことがあります。従業員がスキャナーを続けて二回タップすることもあります。接続が切れていたデバイスが、午前の退勤イベントを午後になって送信することもあります。誰かが誤って出勤ボタンを押すこともあります。システムがイベントを届いたとおりにすべて保存すると、こうした小さな問題が、誤った労働時間、給与に関する紛争、そして誰も信頼しないレポートにつながります。本ガイドでは、重複および順序が乱れた打刻イベントの種類と発生原因を説明し、OperationID と LogTime に基づいて勤怠記録を正確に保つための明確なルールを紹介します。

01 · 課題

勤怠データを正確に保つことが見た目より難しい理由

勤怠イベントは、複数の拠点に分散した物理デバイスから発生し、実際の人が使用し、ときに切断されるネットワークを経由して届きます。これらの要素のそれぞれが、データが不完全な形で届く原因になります。いずれも生体認証システムの不具合ではありません。物理的な世界とソフトウェアが接するときに、必然的に起こることです。

幸いなことに、Cams Biometrics Gateway から送信される打刻イベントには、データを整理するために必要な情報がすべて含まれています。特に次の2つのフィールドが大きな役割を果たします。

フィールド 内容 できること
OperationID ゲートウェイが送信する各イベントの一意の参照番号 同じイベントが複数回届いた場合でも、完全に同一のイベントとして認識する
LogTime 実際にスキャンされた時刻と、デバイスのタイムゾーンオフセット 到着順に関係なく、イベントを実際に発生した順序で並べられる

より難しいケースに役立つフィールドが他に3つあります。UserId は個人を、SerialNumber はデバイスを特定し、Type は個人が出勤と退勤のどちらを押したかを示します。

Callback API による打刻イベントの例

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}

02 · すべての重複が同じではない

4種類の重複打刻イベント

最もよくある誤りは、すべての重複を同じように扱うことです。重複には4つの異なる種類があり、それぞれに異なる対処が必要です。技術的な原因によるものもあれば、デバイスの使い方によるものもあります。

重複の種類 現れ方 識別方法 対処方法
再送イベント まったく同じイベントが2回届く 同じ OperationID 2件目は無視するが、done を返信する
重複インポート コールバックで受信したイベントが、照合時に再度インポートされる 同じ UserId、LogTime、SerialNumber で、取得元が異なる 2件目は無視する
二重スキャン 個人が数秒以内にスキャナーを2回タップする OperationID は異なり、同一人物で、LogTime が非常に近接している 最小間隔ルールを用いて、1回の打刻として扱う
誤った種類の打刻 退勤のつもりが、出勤ボタンを押してしまう 間に退勤がないまま、出勤が2回連続する 労働時間を計算する際にペアリングルールを適用する

技術的な重複と人為的な重複の違い

最初の2つは技術的な重複です。システムが同じスキャンを2回認識したもので、単純に無視すべきものです。後の2つは人為的な重複です。実際に別々に行われたスキャンであり、その意味を判断することは業務ルールに属します。両者の処理は分けて考えてください。受信処理では技術的な重複のみを除去し、人為的な重複の扱いは勤怠ロジックで判断してください。

再送が発生する理由

コールバックは一往復のやり取りです。ゲートウェイがイベントを送信し、サーバーが done の確認応答を返します。サーバーの処理が遅い、再起動した、一時的に到達できないなどの理由で応答が届かない場合、イベントが再送されることがあります。サーバーがすでに最初のコピーを保存している場合もあります。そのため、ルールは常に同じです。OperationID がすでに確認済みであれば、再度保存はしませんが、ゲートウェイがイベントの到着を把握できるように done を返信してください。お使いの環境における正確な再送の動作は、Cams Web API のドキュメントで確認してください。

受信側が、重複を含むすべてのイベントに対して返す応答

{ "status": "done" }

03 · 到着順は実際の発生順ではない

打刻イベントが順序どおりに届かない理由

サーバーはイベントを到着順に受信しますが、勤怠の計算はスキャンの発生順に行う必要があります。ほとんどの場合、この2つは一致します。しかし、一致しない場合もあります。

原因 発生する事象 例
デバイスまたは拠点がオフラインになる デバイスはスキャンをローカルに記録し続け、接続が復旧すると、まとめて送信する 別のデバイスによる13:35のスキャンの後に、13:01の退勤が13:41に届く
ネットワークの遅延 異なるデバイスからのイベントは経路が異なり、届くまでの時間もそれぞれ異なる 1秒違いの2つのスキャンが、逆の順序で届く
1人あたり複数のデバイスを使用 従業員が正門で出勤し、通用口で退勤する 2台のデバイスからのイベントが、予測できない順序で混在する
照合によるインポート 欠落していたイベントが、後からデバイスログを使って補完される 月曜日のイベントが、火曜日にシステムへ追加される

ペイロードには、その違いを判断する情報がすでに含まれています。LogTime はスキャンが行われた時刻です。Time は、メッセージ自体のタイムスタンプで、GMT で表示されます。上のサンプルペイロードでは、スキャンは現地時間の 07:48 に行われましたが、メッセージは GMT の 04:19 に送信されています。これは同じタイムゾーンでは 09:49 にあたり、2時間の差があります。この差こそ、オフライン期間の典型的な特徴です。到着順に並べると、そのスキャンは誤った位置に配置されてしまいます。

到着時刻は、サーバーがイベントを把握した時刻を示します。LogTime は、イベントが実際に発生した時刻を示します。勤怠は必ず LogTime に従って処理してください。

04 · 8つのルール

正確な勤怠データのためのプレイブック

以下の8つのルールは、上記のすべてのケースに対応します。最初の4つは、コールバック受信処理とストレージに適用します。残りの4つは、保存されたイベントを勤怠データに変換するロジックに適用します。

1

まず生のイベントをすべて保存する

他の処理を行う前に、受信したペイロードをそのままの形で保存してください。後でルールに誤りがあったことがわかっても、生データから再処理できます。

2

繰り返し届く OperationID を無視する

ストレージ内で OperationID を一意にしてください。同じ OperationID が再度届いた場合は、保存をスキップしますが、done は返信してください。

3

インポートには自然キーを使用する

照合によりインポートされたイベントについては、UserId、LogTime、SerialNumber の組み合わせをスキャンの識別子として扱ってください。これにより、同じスキャンが2つの取得元から二重に保存されることがなくなります。

4

到着順ではなく LogTime で並べる

タイムゾーンオフセットを含めて LogTime を解析し、勤怠を計算する際は必ず LogTime で並べ替えてください。

5

到着時点ではなく、後から計算する

退勤イベントが届いた時点で、その日の労働時間を確定させないでください。遅れて届くイベントがあれば再計算し、給与計算の実行前など、一定の確定期間を経てから日次データをロックしてください。

6

最小間隔で二重スキャンを統合する

同一人物による短い時間枠内(例:2分以内)のスキャンは、1回の打刻として扱ってください。職場の実情に合った時間枠を選択してください。

7

明確なルールで打刻をペアリングする

誤って種類が設定された打刻の扱いを決めてください。例えば、時系列順にスキャンをペアリングする、最初のスキャンを出勤、最後のスキャンを退勤とするなどです。すべての場面で同じルールを適用してください。

8

すべての修正の記録を残す

ルールによってスキャンを統合、無視、または種類の変更を行った場合は、何が行われたか、またその理由を記録してください。人事部門や監査担当者は、生のスキャンがどのように労働時間に変換されたかを確認する必要があります。

デバイスの時計を正確に保つ

LogTime はデバイスの時計から取得されます。デバイスの時刻が誤っていると、そのデバイスのすべてのスキャンが誤ったものになり、どれほど並べ替えを行っても修正できません。各デバイスの日付、時刻、タイムゾーンが正しく設定されていることを確認し、停電後やファームウェアの更新後には必ず再確認してください。

05 · ルールの組み合わせ

実例:1人の従業員、混乱した1日

Burj Khalifa 拠点の従業員 2 の、実際にありうる1日を紹介します。表はイベントがサーバーに到着した順序で示しています。拠点は1日の一部の時間、接続が切断されていました。

到着時刻 OperationID Type LogTime ルールの処理内容
09:02 op-1001 CheckIn 08:58 保存済み
09:03 op-1001 CheckIn 08:58 同じ OperationID のため無視し、done を送信
09:04 op-1002 CheckIn 08:59 08:58 から2分以内のため、二重スキャンとして統合
13:40 op-1004 CheckIn 13:35 保存済み
13:41 op-1003 CheckOut 13:01 オフライン期間からの遅延到着:LogTime により 13:35 より前に配置
18:05 op-1005 CheckIn 18:04 出勤が2回連続:その日の最終退勤としてペアリング

LogTime で並べ替えて整理すると、その日は2つの明確な勤務時間帯になります。

時間帯 開始 終了 所要時間
午前 08:58 13:01 4時間3分
午後 13:35 18:04 4時間29分
合計勤務時間 8時間32分

ルールを適用しなければ、同じ生のイベントから、午前に3回の出勤、午後の出勤の後に現れる退勤、そして一日の終わりに退勤がない状態が生じていたでしょう。給与計算ではエラーが検出されるか、さらに悪いことに、誰も気づかないまま誤った労働時間が計算されていたかもしれません。

06 · 正確なデータのための設計

Cams Gateway が正確なデータの管理を支援する仕組み

正確な勤怠データは、適切な情報を備えたイベントから始まります。Cams Biometrics Gateway は、システムが受信するすべてのイベントを特定、順序付け、追跡できるように設計されています。

Cams の機能 役立つ点
すべてのイベントに OperationID を付与 再送されたイベントを確実に認識し、無視するための信頼できる方法を提供
タイムゾーンオフセット付きの LogTime 到着場所や到着時刻に関係なく、イベントを実際の発生順に配置可能
UserId、SerialNumber、LabelName 個人、デバイス、拠点を特定し、これらを組み合わせてインポート用の自然キーを構成
オフラインキャッシュとキュー 接続の中断中もイベントを保持し、元のタイムスタンプとともに配信
done による確認応答 各イベントの到着を明確に示し、配信を確認可能
ログを読み込む RESTful 操作 必要に応じてデバイスログを取得し、照合や欠落の補完が可能
AI Code Generator Prompts トークンを検証し、すべてのイベントを記録するコールバック受信処理を生成。本ガイドのルールを追加する準備が整った状態で出力

役割分担

Cams Gateway は、確認済みの各スキャンを、整理に必要な情報とともに配信します。技術的な重複の除去は、コールバック受信処理で行ってください。二重スキャンの統合、打刻のペアリング、労働時間の計算は、業務ルールがすでに存在する HRMS、給与計算、または勤怠ロジックで行ってください。

よくあるご質問

受信側で、重複イベントをエラーとして拒否すべきですか?

いいえ。重複イベントに対しても done を返信してください。イベントは正常に到着しているため、エラーを返すと再送を引き起こす可能性があります。保存をスキップするだけで十分です。

重複の検出に LogTime だけを使用できますか?

LogTime だけでは不十分です。異なる2人が同じ秒にスキャンすることもあります。再送されたイベントには OperationID を、インポートには UserId、LogTime、SerialNumber の組み合わせを使用してください。

二重スキャンの時間枠はどのくらいにすべきですか?

誤って繰り返しタップした場合を捕捉できるだけの長さが必要で、かつ、別々の正当な打刻を統合してしまわない程度の短さが必要です。1〜2分の時間枠は多くの職場に適していますが、シフトや拠点のレイアウトに合わせて選択してください。

その日の勤怠はいつロックすべきですか?

遅れて届くイベントを受け付けられるだけの確定期間を置いた後、例えば翌朝や給与計算の直前にロックしてください。それまでは、その日のイベントが新たに届くたびに再計算してください。

顔、カード、PIN によるスキャンにも同じルールが適用されますか?

はい。すべての入力方式は、同じ OperationID と LogTime フィールドを持つ同じイベント形式で届くため、本人確認の方法に関係なく同じルールが適用されます。

結論:信頼は偶然ではなくルールから生まれる

重複および順序が乱れた打刻イベントは、まれな例外的ケースではありません。実際のデバイス、実際のネットワーク、実際の人々を使って生体認証勤怠を運用する上で、通常起こりうることです。人事部門が信頼できる勤怠データと、紛争の原因となるデータの違いは、偶然によるものではありません。明確で一貫して適用される少数のルールによって生まれます。

繰り返し届く OperationID は無視してください。すべてを LogTime で並べてください。人為的な重複は技術的なエラーではなく、業務ルールとして扱ってください。計算は遅らせ、すべての修正を記録し、デバイスの時計を正確に保ってください。これらのルールを実施すれば、確認済みのスキャンはすべて信頼できる記録になります。

Cams Biometrics Gateway は、これらのルールを機能させるためのデータを提供します。すべてのコールバックイベントには、OperationID、タイムゾーンオフセット付きの LogTime、そして各スキャンを特定するために必要な個人、デバイス、拠点の詳細が含まれています。対応デバイスは15以上のブランドにわたります。オフラインキャッシュとキューは、中断中もイベントを保護し、RESTful 操作により、必要なときにいつでもデバイスログと照合できます。プラットフォームの詳細は CamsBiometrics.com をご覧ください。Web API の完全なドキュメントは developer.camsbiometrics.com でご確認いただけます。コールバック受信処理は AI Code Generator Prompts を使って生成できます。

Was this article helpful?