​

打刻修正の自動同期：承認後に DingTalk の勤怠ステータスをリアルタイムで更新

​

概要

​

背景

​

主なメリット

• システム間の自動同期：自社の休暇・勤怠システムで申請が承認されると、システムが DingTalk API を呼び出して打刻修正データを同期します。社員による追加の操作は不要です。
• 正確なステータス反映：承認結果（承認または取り下げ）に応じて、DingTalk の勤怠ステータスを「打刻修正承認済み」に設定するか、元の打刻ステータスに戻します。
• シフトの自動照合：同期前に、対象日における社員のシフト上の打刻時刻を照会します。これにより、打刻修正データが正しい時刻に紐付けられます。
• 承認フローの分離：同期によって DingTalk 上に打刻修正の承認フォームは作成されません。重複承認を防ぎ、自社の承認フローを独立して運用できます。

​

ユースケース

• 自社 OA システムとの同期：社員が自社 OA システムで打刻修正を申請し、承認されると、結果が DingTalk 勤怠に自動で同期されます。
• サードパーティの休暇・勤怠プラットフォーム：サードパーティの休暇・勤怠システムを利用している場合も、承認結果が DingTalk 勤怠アプリにリアルタイムで同期されます。
• 打刻修正の一括処理：人事部門が過去の打刻修正記録を一括インポートすると、記録が DingTalk 勤怠に自動で同期されます。
• 取り下げの同期：社員が自社システムで打刻修正申請を取り下げると、DingTalk 勤怠の元の打刻ステータスが自動で復元されます。

​

代表的な業務シナリオ

​

シナリオ 1：自社 OA システムで打刻修正申請が承認された後に DingTalk へ同期する

​

課題

​

導入効果

• 自動化された作業フロー

• 主な利点
  • 完全自動トリガー：自社 OA システムで承認されると、システムが DingTalk API を呼び出して打刻修正データを同期します。社員の操作は不要です。
  • 正確な照合：同期前に、対象日における社員のシフト上の打刻時刻を照会します。これにより、打刻修正データが正しい時刻に紐付けられます。
  • 即時反映：打刻修正データは同期と同時に有効になります。DingTalk の勤怠ステータスは「打刻漏れ」から「打刻修正承認済み」に変わります。
  • 承認フローの分離：同期によって DingTalk 上に打刻修正の承認フォームは作成されません。重複承認を防ぎ、自社の承認フローを独立して運用できます。

​

シナリオ 2：打刻修正申請の取り下げ後に元の打刻ステータスを復元する

​

課題

​

導入効果

• 自動化された作業フロー
• 主な利点
  • ステータスの自動ロールバック：自社システムで打刻修正申請が取り下げられると、システムが DingTalk API を呼び出して元の打刻ステータスを復元します。
  • データの一貫性：DingTalk の勤怠ステータスは、常に自社 OA システムの承認結果と一致します。
  • 監査証跡：同期や取り下げのたびに、操作者・タイムスタンプ・承認フォーム ID を記録し、コンプライアンス要件に対応します。
  • エラーの追跡：同期に失敗した場合、詳細なエラー情報をログに記録し、問題の調査と解決を支援します。

​

実装ガイド

​

技術アーキテクチャ

• 認証レイヤー：Client ID と Client Secret を使って access_token を取得し、API 呼び出しの安全性を確保します。
• 勤怠グループ管理レイヤー：勤怠グループの作成・照会・更新・削除を行う API を網羅的に提供します。固定シフト制とシフト制の両方の勤怠グループに対応しています。
• シフト管理レイヤー：シフトの作成・照会を行う API を提供します。シフトは勤怠グループの前提となるリソースです。
• エラーハンドリングレイヤー：体系的なエラーコードにより、問題の特定と解決を迅速に行えます。

​

前提条件

• アプリの準備：社内アプリを作成し、設定します。詳しくは、アプリの作成と設定を参照してください。
• 権限：DingTalk の組織管理者またはサブ管理者の権限を持ち、次の API 権限を申請します。
  • qyapi_attendance_group_manage（勤怠グループ管理権限）
  • qyapi_attendance_group_read（勤怠グループ読み取り権限）
• 開発環境：Java 開発環境（JDK 1.6 以降）と Maven ビルドツールをインストールします。
• SDK：DingTalk のサーバーサイド SDK をダウンロードします。詳しくは、「サーバーサイド SDK のダウンロード」を参照してください。SDK は Java、Python、Go などの言語に対応しています。

​

コード実装

1. 社員が自社勤怠システムで打刻修正を申請したら、社員が選択した日付を指定してサーバー API ユーザーのシフトの照会を呼び出します。その日付における社員のシフト上の打刻時刻が返されます。
2. 社員は自社の休暇・勤怠システムで打刻修正の承認フォームを提出します。次の操作は承認結果によって異なります。
   • 申請が承認された場合は、サーバー API 打刻修正承認の通知を呼び出します。提出された打刻修正データが DingTalk 勤怠アプリに同期され、勤怠ステータスが「打刻漏れ」から「打刻修正承認済み」に変わります。

​

注意

• 社員が打刻修正申請を取り下げた場合は、サーバー API 承認取り下げの通知を呼び出します。DingTalk に同期済みの打刻修正申請が取り下げられ、勤怠ステータスが変更前の打刻ステータスに戻ります。

​

実装手順

​

ステップ 1：アプリの認証情報を取得する

1. DingTalk 開発者コンソールにログインします。
2. 対象のアプリを選択し、詳細ページを開きます。
3. 基本情報 > 認証情報と基本情報 をクリックします。
4. アプリの Client ID と Client Secret を控えておきます。

​

注意

​

ステップ 2：API 権限を追加する

1. アプリの詳細ページで 権限管理 をクリックします。
2. 権限の検索ボックスに次の権限識別子を入力し、申請します。
   • qyapi_attendance_group_manage（勤怠グループ管理権限）：打刻修正データの同期と取り下げに使用します。
   • qyapi_attendance_group_read（勤怠グループ読み取り権限）：社員のシフトの照会に使用します。

​

ステップ 3：アクセス認証情報（access_token）を取得する

public void getAccessToken() throws ApiException {
  DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/gettoken");
  OapiGettokenRequest req = new OapiGettokenRequest();
  req.setAppkey("dingxxxxxxxxxhgn");
  req.setAppsecret("9G_xxxxxxxxxxxxxxx1JDf0Qq3nexxxxxxxxGIO");
  req.setHttpMethod("GET");
  OapiGettokenResponse rsp = client.execute(req);
  System.out.println(rsp.getBody());
}

• キャッシュ：access_token の有効期限は 2 時間です。メモリまたは Redis にキャッシュし、有効期限の5分前に更新してください。
• 同時実行の制御：複数のスレッドが同時にトークンを更新しないようにします。必要に応じて分散ロックを使用してください。
• エラー時のリトライ：ネットワークが不安定な場合は自動でリトライします。最大 3 回まで、間隔を段階的に延ばしてください（1 秒 → 2 秒 → 4 秒）。

​

ステップ 4：主要な API を呼び出す

1. ユーザーのシフトを照会する：社員が自社勤怠システムで打刻修正を申請したら、社員が選択した日付を指定してサーバー API ユーザーのシフトの照会を呼び出します。その日付における社員のシフト上の打刻時刻が返されます。
   public void scheduleInfo() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/schedule/listbyday");
       OapiAttendanceScheduleListbydayRequest req = new OapiAttendanceScheduleListbydayRequest();
       req.setOpUserId("ma******75");
       req.setUserId("014*********041");
       req.setDateTime(166*******00L);
       OapiAttendanceScheduleListbydayResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   
2. 打刻修正の承認を通知する：社員は自社の休暇・勤怠システムで打刻修正の承認フォームを提出します。申請が承認された場合は、サーバー API 打刻修正承認の通知を呼び出します。提出された打刻修正データが DingTalk 勤怠アプリに同期され、勤怠ステータスが「打刻漏れ」から「打刻修正承認済み」に変わります。

​

注意

public void approveCheck() throws ApiException {
    DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/approve/check");
    OapiAttendanceApproveCheckRequest req = new OapiAttendanceApproveCheckRequest();
    req.setUserid("ma****75");
    req.setWorkDate("2022-10-10 09:00:00");
    req.setPunchId(1006170802L);
    req.setPunchCheckTime("2022-10-10 09:00:00");
    req.setUserCheckTime("2022-10-10 08:00:00");
    req.setApproveId("dingTalk10001");
    req.setJumpUrl("https://www.dingtalk.io");
    req.setTagName("打刻修正");
    OapiAttendanceApproveCheckResponse rsp = client.execute(req, "access_token");
    System.out.println(rsp.getBody());
}

​

パラメータ：

3. 承認の取り下げを通知する：社員が打刻修正申請を取り下げた場合は、サーバー API 承認取り下げの通知を呼び出します。DingTalk に同期済みの打刻修正申請が取り下げられ、勤怠ステータスが変更前の打刻ステータスに戻ります。
   public void approveCancel() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/approve/cancel");
       OapiAttendanceApproveCancelRequest req = new OapiAttendanceApproveCancelRequest();
       req.setUserid("ma****75");
       req.setApproveId("dingTalk10001");
       OapiAttendanceApproveCancelResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   

• ✅ すべての API 呼び出しで成功ステータスコード（errcode=0）が返される。
• ✅ 打刻修正の同期後にシフト照会 API を呼び出し、打刻時刻が正しいことを確認している。
• ✅ 取り下げ後に、勤怠ステータスが元の状態に戻っていることを確認している。
• ✅ エラーログが網羅的で、承認フォーム ID・社員のユーザー ID・操作日時が含まれている。
• ✅ 自社 OA システムと DingTalk 勤怠の打刻修正データを定期的に照合し、一貫性が保たれている。

​

よくある質問

• Q1：打刻修正の同期は、DingTalk 標準の打刻修正承認とどう違いますか？ A：両者の目的はまったく異なります。
  • DingTalk 標準の打刻修正承認：社員が DingTalk アプリで打刻修正を申請 → 上長が承認 → 勤怠ステータスが自動更新されます。自社の OA システムを持たない組織に適しています。
  • 本ソリューションの打刻修正の同期：社員が自社の OA システムまたは休暇・勤怠システムで打刻修正を申請 → OA 承認が完了 → API が結果を DingTalk に同期します。成熟した OA 承認フローを持つ組織に適しており、社員が 2 つのシステムで同じ作業を繰り返す必要がなくなります。
  主な違い：本ソリューションでは、DingTalk 上に打刻修正の承認フォームは作成されません。OA の承認結果を DingTalk の勤怠記録に同期するだけなので、自社の承認フローを独立して運用できます。
• Q2：打刻修正の一括同期で一部の社員が失敗した場合は、どう対処すればよいですか？ A：一括同期では、記録を 1 件ずつ処理し、失敗したものをリトライします。
  1. 分割処理：リクエストのタイムアウトを避けるため、1 回のバッチに含める社員は 50 人以内にします。
  2. 失敗の切り分け：レスポンスを解析し、失敗した社員のユーザー ID とエラー原因（errcode/errmsg）を抽出します。
  3. カテゴリ別の対応：
     • User not in attendance group（勤怠グループ未所属）：社員が正しい勤怠グループに所属しているか確認します。
     • Date out of range（日付が範囲外）：打刻修正の日付が許可された期間内にあるか確認します。
     • Network timeout（ネットワークのタイムアウト）：最大 3 回まで、間隔を段階的に延ばして自動でリトライします（1 秒/2 秒/4 秒）。
  4. ログ記録：失敗ごとに承認フォーム ID・社員のユーザー ID・エラー原因・リトライ回数を記録し、担当者が手動でフォローアップできるようにします。
• Q3：打刻修正の同期後、データの一貫性はどのように検証すればよいですか？ A：3 段階の検証の仕組みを構築します。
  1. リアルタイムチェック：同期が成功したら、その日の社員の勤怠ステータスが「打刻漏れ」から「打刻修正承認済み」に変わったことをすぐに確認します。
  2. 定期照合：毎朝早い時間に全件照合ジョブを実行します。自社 OA システムから当日の打刻修正承認記録を、DingTalk 勤怠から打刻修正記録をそれぞれ取得します。承認フォーム ID と社員のユーザー ID で突き合わせ、不一致があればアラートチケットを作成します。
  3. エラー監視：同期に 3 回連続で失敗した社員がいる場合はアラートを発行し、人事管理者に手動での確認を依頼します。原因としては、退職者が勤怠グループから削除されていない、シフトが設定されていない、などが考えられます。
• Q4：その日に通常の打刻記録がある社員の打刻修正を取り下げると、どうなりますか？ A：取り下げを行うと、DingTalk の勤怠ステータスは打刻修正前の元の打刻ステータスに戻ります。具体的には次のとおりです。
  • 「打刻漏れ」（打刻なし）だった場合 → 「打刻漏れ」に戻ります。
  • 「通常打刻」だった場合 → 「通常打刻」に戻り、打刻修正の記録は削除されます。
  • 「遅刻/早退」だった場合 → 「遅刻/早退」に戻り、打刻修正の記録は削除されます。
  重要：取り下げは元に戻せません。一度実行すると、打刻修正のステータスは復元できません。誤って取り下げないよう、自社 OA システムに再確認のステップを設けてください。