> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 自社勤怠システムの打刻修正データを DingTalk に同期・更新する

> 自社勤怠システムの打刻修正データを DingTalk に同期・更新する API です。承認・取り下げに応じて勤怠ステータスも更新します。

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

## 概要

本ソリューションは、組織の自社勤怠システムにある打刻修正データを DingTalk に同期します。DingTalk Open Platform の勤怠打刻修正 API を使い、自社の OA システムまたは休暇・勤怠システムと DingTalk 勤怠アプリを連携させます。

### 背景

日常の勤怠管理では、外出や打刻忘れにより、社員が打刻修正を必要とすることがあります。通常、社員は組織独自の OA システムまたは休暇・勤怠システムで申請を行います。しかし、DingTalk 勤怠の打刻漏れ記録には、こうした外部の承認結果が自動で反映されません。そのため、社員は 2 つのシステムで同じ作業を繰り返す必要があります。まず自社システムで打刻修正を申請し、次に DingTalk で勤怠ステータスを手動で変更します。2 つのシステムを並行運用すると社員の負担が増えます。また、データの不整合が生じ、勤怠統計の精度が低下します。

### 主なメリット

本ソリューションは、自社勤怠システムと DingTalk 勤怠の間で打刻修正データを自動同期します。システムをまたいだ手作業でのデータ入力を、API による標準化されたプロセスに置き換えます。その結果、勤怠管理が効率化され、データの一貫性も保たれます。

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

### ユースケース

本ソリューションは、次の業務シナリオに適用できます。

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

## 代表的な業務シナリオ

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

#### 課題

従来の方式では、社員は自社 OA システムで打刻修正を申請します。承認後も、DingTalk アプリを開いてその日の勤怠ステータスを手動で「打刻修正」に変更するか、DingTalk で改めて打刻修正を申請する必要があります。毎月数十件の打刻修正申請がある組織では、社員はこの手順を何度も繰り返すことになります。また、手順の抜けや日付の選択ミスが起こりやすく、勤怠データが不正確になります。

#### 導入効果

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

図：自社 OA システムで打刻修正申請が承認された後に DingTalk へ同期する作業フロー

* **主な利点**

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

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

#### 課題

社員が自社 OA システムで打刻修正申請を取り下げても、DingTalk 勤怠のステータスは自動では元に戻りません。「打刻修正承認済み」のまま表示されます。人事担当者は DingTalk の管理コンソールにログインし、記録を 1 件ずつ手動で修正する必要があります。時間がかかるうえ、修正漏れも発生しやすく、勤怠統計が不正確になります。

#### 導入効果

図：打刻修正申請の取り下げ後に元の打刻ステータスを復元する作業フロー

* **自動化された作業フロー**
* **主な利点**

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

## 実装ガイド

### 技術アーキテクチャ

本ソリューションは、DingTalk Open Platform のサーバー API を基盤としています。主な技術コンポーネントは次のとおりです。

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

**API のバージョン**：サーバー API には新バージョンと旧バージョンがあります。性能が高く、対応機能も幅広い新バージョンを使用してください。

### 前提条件

本ソリューションを実装する前に、次の要件を満たしていることを確認してください。

* **アプリの準備**：社内アプリを作成し、設定します。詳しくは、[アプリの作成と設定](https://help.dingtalk.io/ja/open/dingstart/create-application.md)を参照してください。
* **権限**：DingTalk の組織管理者またはサブ管理者の権限を持ち、次の API 権限を申請します。

  * `qyapi_attendance_group_manage`（勤怠グループ管理権限）
  * `qyapi_attendance_group_read`（勤怠グループ読み取り権限）
* **開発環境**：Java 開発環境（JDK 1.6 以降）と Maven ビルドツールをインストールします。
* **SDK**：DingTalk のサーバーサイド SDK をダウンロードします。詳しくは、「サーバーサイド SDK のダウンロード」を参照してください。SDK は Java、Python、Go などの言語に対応しています。

### コード実装

ステップ 1：アプリのクライアント ID と Client Secret を含む、アプリ認証情報を取得します。

ステップ 2：勤怠関連の API 権限を申請します。

ステップ 3：アプリのアクセス認証情報を取得します。詳しくは、[社内アプリの access\_token の取得](https://help.dingtalk.io/ja/open/development/obtain-orgapp-token)を参照してください。API を呼び出す際は、アクセストークンによって呼び出し元が認証されます。

ステップ 4：勤怠 API を呼び出します。

1. 社員が自社勤怠システムで打刻修正を申請したら、社員が選択した日付を指定してサーバー API [ユーザーのシフトの照会](https://help.dingtalk.io/ja/open/development/query-scheduling-for-a-day.md)を呼び出します。その日付における社員のシフト上の打刻時刻が返されます。
2. 社員は自社の休暇・勤怠システムで打刻修正の承認フォームを提出します。次の操作は承認結果によって異なります。

   * 申請が承認された場合は、サーバー API [打刻修正承認の通知](https://help.dingtalk.io/ja/open/development/make-up-the-card-after-approval.md)を呼び出します。提出された打刻修正データが DingTalk 勤怠アプリに同期され、勤怠ステータスが「打刻漏れ」から「打刻修正承認済み」に変わります。

### 注意

このステップでは、DingTalk 上に打刻修正の承認フォームは作成されません。

* 社員が打刻修正申請を取り下げた場合は、サーバー API [承認取り下げの通知](https://help.dingtalk.io/ja/open/development/notify-the-attendance-to-modify-the-punch-result-when-the.md)を呼び出します。DingTalk に同期済みの打刻修正申請が取り下げられ、勤怠ステータスが変更前の打刻ステータスに戻ります。

## 実装手順

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

1. [DingTalk 開発者コンソール](https://open-dev.dingtalk.io/)にログインします。
2. 対象のアプリを選択し、詳細ページを開きます。
3. **基本情報** > **認証情報と基本情報** をクリックします。
4. アプリの `Client ID` と `Client Secret` を控えておきます。

### 注意

`Client Secret` は安全に保管し、第三者と共有しないでください。ハードコードせず、環境変数や鍵管理システムに保存してください。

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

1. アプリの詳細ページで **権限管理** をクリックします。
2. 権限の検索ボックスに次の権限識別子を入力し、申請します。

   * `qyapi_attendance_group_manage`（勤怠グループ管理権限）：打刻修正データの同期と取り下げに使用します。
   * `qyapi_attendance_group_read`（勤怠グループ読み取り権限）：社員のシフトの照会に使用します。

> [!NOTE]
>
> 業務シナリオによって、必要な権限の組み合わせは異なります。実際に必要な権限を申請してください。たとえば、一括インポートのシナリオでは、ユーザーの一括操作に関する権限も必要です。

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

ステップ 1 で取得した Client ID と Client Secret を使って、アプリのアクセス認証情報を取得します。詳しくは、[社内アプリの access\_token の取得](https://help.dingtalk.io/ja/open/development/obtain-orgapp-token)を参照してください。

```java theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 [ユーザーのシフトの照会](https://help.dingtalk.io/ja/open/development/query-scheduling-for-a-day.md)を呼び出します。その日付における社員のシフト上の打刻時刻が返されます。

   ```java theme={"theme":{"light":"github-light","dark":"github-dark"}}
   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 [打刻修正承認の通知](https://help.dingtalk.io/ja/open/development/make-up-the-card-after-approval.md)を呼び出します。提出された打刻修正データが DingTalk 勤怠アプリに同期され、勤怠ステータスが「打刻漏れ」から「打刻修正承認済み」に変わります。

### 注意

このステップでは、DingTalk 上に打刻修正の承認フォームは作成されません。打刻修正の結果を勤怠記録に同期するだけです。

```java theme={"theme":{"light":"github-light","dark":"github-dark"}}
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());
}
```

### パラメータ：

| **名前** | **型** | **必須** | **説明** |
| - | - | - | - |
| userid | String | はい | 社員のユーザー ID。 |
| workDate | String | はい | 打刻修正の対象となる勤務日。 |
| punchId | Long | はい | 修正対象となるシフト上の打刻の ID。シフト照会 API から取得します。 |
| punchCheckTime | String | はい | シフト上の打刻時刻。 |
| userCheckTime | String | はい | ユーザーの打刻時刻。 |
| approveId | String | はい | 承認フォーム ID。任意の値を指定します。 |
| jumpUrl | String | いいえ | 承認フォームのリダイレクト先 URL。 |
| tagName | String | いいえ | 承認フォームの名前。 |

3. **承認の取り下げを通知する**：社員が打刻修正申請を取り下げた場合は、サーバー API [承認取り下げの通知](https://help.dingtalk.io/ja/open/development/notify-the-attendance-to-modify-the-punch-result-when-the.md)を呼び出します。DingTalk に同期済みの打刻修正申請が取り下げられ、勤怠ステータスが変更前の打刻ステータスに戻ります。

   ```java theme={"theme":{"light":"github-light","dark":"github-dark"}}
   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 システムに再確認のステップを設けてください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.