> ## 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 オープンプラットフォームの勤怠打刻 API を使い、自社システムの社員の打刻記録を DingTalk 勤怠アプリへ自動で同期します。

### 背景

多くの組織では、カードリーダー、指紋認証端末、顔認証端末などの自社勤怠システムやサードパーティ製勤怠デバイスで、社員の打刻を記録しています。しかし、これらのシステムには DingTalk 勤怠との標準的なデータ連携インターフェースがありません。そのため、次のような問題が発生します。

* **手作業による打刻修正の非効率さ**：社員は自社システムで打刻した後、DingTalk で打刻修正を申請する必要があります。手間がかかり、申請を忘れることも少なくありません。
* **データの不整合**：勤怠データが自社システムと DingTalk に分散しています。人事担当者はシステム間で勤怠記録を照合しなければなりません。
* **即時性の不足**：社員は打刻後すぐに DingTalk で勤怠状況を確認したいと考えています。翌日の一括同期を待つことは望んでいません。

### 主なメリット

本ソリューションは、勤怠の打刻データをエンドツーエンドで同期します。DingTalk オープンプラットフォームの勤怠打刻 API を使い、自社システムの社員の打刻記録を DingTalk 勤怠アプリへ自動で同期します。

* **打刻の自動同期**：自社システムの打刻記録が DingTalk へ自動でアップロードされます。手作業は不要です。
* **管理エントリの一元化**：すべての勤怠データが DingTalk に集約されます。人事担当者は 1 つのプラットフォームで勤怠統計と分析を行えます。
* **迅速かつ低コストな連携**：必要なコア API は 2 つだけです。開発コストを低く抑えられます。

### ユースケース

本ソリューションは、次のような業務シナリオに適しています。

* **自社勤怠システムとの連携**：自社開発の勤怠システムやサードパーティ製勤怠デバイス（カードリーダー、指紋認証端末、顔認証端末など）を DingTalk 勤怠と接続し、打刻データを自動で同期します。
* **複数デバイスのデータ統合**：勤務拠点ごとに異なる勤怠デバイスを運用しており、すべての打刻記録を DingTalk で一元管理する必要がある場合に適しています。
* **勤怠状況のリアルタイム表示**：社員は翌日の一括同期を待たずに、打刻後すぐに DingTalk で勤怠状況を確認できます。
* **人事担当者によるシステム間照合の解消**：人事担当者が自社勤怠システムと DingTalk のデータを手作業で照合する必要がなくなり、勤怠統計を迅速化できます。

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

### シナリオ 1：自社勤怠システムの打刻データを同期する

#### 課題

従来は、社員が自社勤怠システムで打刻（カードや指紋など）した後、DingTalk に勤怠状況を反映するために打刻修正を申請する必要がありました。1 日に数千件の打刻が発生する組織では、人事担当者が毎日大量の打刻修正申請を処理しなければなりません。これには時間がかかり、ミスも発生しやすくなります。

#### 導入効果

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

  打刻データのリアルタイム同期フローは、次の 5 つのステップで構成されます。

  1. 社員が自社システムで打刻します。
  2. 自社勤怠システムが DingTalk API を呼び出し、データチャネルを確立します。
  3. 自社システムが API を通じて、DingTalk における社員の一意の識別子（**userId**）を取得します。
  4. 自社システムが打刻記録を DingTalk 勤怠へアップロードします。
  5. DingTalk 勤怠アプリが打刻状況をリアルタイムに表示します。

  アップロード時のパラメータ例：**userid**、**userCheckTime**、**deviceId**。
* **主な効果**

  * **二重作業の解消**：社員が自社勤怠システムで打刻すると、データは API を通じて DingTalk 勤怠へ同期されます。社員が打刻修正を申請したり、データを再入力したりする必要はありません。
  * **手作業による確認の削減**：打刻記録がリアルタイムに同期されるため、人事担当者が打刻修正申請を 1 件ずつ確認する必要がなくなります。手作業による確認業務が大幅に減り、時間を節約できます。
  * **データ精度の向上**：自動同期により、人手の介在や入力ミスがなくなります。勤怠データの真正性、正確性、追跡可能性を確保できます。
  * **ユーザー体験の向上**：社員はリアルタイムに打刻状況を確認でき、打刻漏れや打刻修正の申請忘れを心配する必要がなくなります。

### シナリオ 2：複数の勤怠デバイスのデータを統合する

#### 課題

大規模な組織では、勤務拠点ごとに複数種類の勤怠デバイス（指紋認証端末、顔認証端末、GPS 位置情報など）を導入していることがよくあります。各デバイスは打刻データを個別に保存しています。人事担当者は複数のシステムにログインして Excel ファイルをエクスポートし、手作業で統合しなければなりません。これは非常に非効率で、データの欠落も頻繁に発生します。

#### 導入効果

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

  複数の勤怠デバイスの打刻データを DingTalk に統合するデータフローは、次のとおりです。

  1. 社員がさまざまな勤怠デバイスで打刻します。
  2. 各デバイスがデータをリアルタイムに自社勤怠システムへアップロードします。
  3. 自社システムが **DingTalk オープンプラットフォーム API** を呼び出し、勤怠データを一括でアップロードします。
  4. DingTalk がすべての打刻データを受信し、統合して一元的に保存・管理します。
  5. 人事担当者が DingTalk のワークベンチで、統合された勤怠レポートと分析結果を確認します。

  従来の方法では、複数のシステムにログインし、Excel データをエクスポートして、手作業でデータを統合しレポートを作成する必要がありました。このフローでは、データが DingTalk に自動で集約され、ワンクリックでレポートを生成できます。
* **主な効果**

  * **複数ソースのデータを統一**：指紋認証端末、顔認証端末、GPS 位置情報などの勤怠デバイスの打刻データを、DingTalk 上で 1 つの標準形式に統合します。データのサイロ化を解消できます。
  * **ワンストップ管理**：人事担当者は、複数のシステムへのログインや Excel ファイルのエクスポート・手作業での統合を行うことなく、DingTalk ですべての社員の勤怠記録をリアルタイムに確認できます。
  * **統計処理の迅速化**：システムがデータを自動で集計し、レポートを生成します。勤怠統計にかかる期間を大幅に短縮できます。
  * **手作業の削減**：エクスポート、データクレンジング、統合といった繰り返しの手作業を自動化で置き換えます。人件費を削減し、人為的ミスのリスクを低減します。

## 実装ガイド

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

本ソリューションは、DingTalk オープンプラットフォームの勤怠関連 OpenAPI をベースに構築されています。主な技術コンポーネントは次のとおりです。

* **認証レイヤー**：`Client ID` / `Client Secret` を使って `access_token` を取得し、API 呼び出しを保護します。
* **権限管理レイヤー**：連絡先 API と勤怠 API の権限を申請します。
* **ユーザー ID 取得レイヤー**：連絡先のサーバー API を呼び出して部門ユーザーの詳細情報を取得し、DingTalk の組織構成における各社員のユーザー ID を取得します。
* **打刻アップロードレイヤー**：勤怠のサーバー API を呼び出し、自社システムの打刻日時などを含む打刻記録を DingTalk 勤怠アプリへアップロードします。

### 前提条件

作業を始める前に、次の要件を満たしていることを確認してください。

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

  * `qyapi_get_department_member`（連絡先の部門メンバーの読み取り権限）
  * `Pro.AttendanceRecord.Write`（勤怠打刻記録の書き込み権限）
* **開発環境**：Java 開発環境（JDK 1.6 以降）と Maven ビルドツールをインストール済みであること。
* **SDK**：DingTalk サーバーサイド SDK をダウンロード済みであること。詳細は、サーバーサイド SDK のダウンロードページを参照してください。SDK は Java、Python、Go などの言語に対応しています。

### コードの実装

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

ステップ 2：[API 権限を追加](https://help.dingtalk.io/ja/open/development/add-api-permission.md)します。「連絡先」と「勤怠」で検索し、対応する API 権限を申請します。

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

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

1. 連絡先のサーバー API [部門ユーザーの詳細情報を取得する](https://help.dingtalk.io/ja/open/development/queries-the-complete-information-of-a-department-user.md)を呼び出し、DingTalk の組織構成における各社員のユーザー ID を取得します。
2. 勤怠のサーバー API [打刻記録をアップロードする](https://help.dingtalk.io/ja/open/development/upload-punch-records.md)を呼び出し、自社システムの社員の打刻日時などの情報を DingTalk 勤怠アプリへアップロードします。これにより勤怠データが同期されます。

## 実装手順

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

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

### 注意

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

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

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

   * `qyapi_get_department_member`（連絡先の部門メンバーの読み取り権限）：部門ユーザーの詳細情報を取得し、ユーザー ID を取得します。
   * `Pro.AttendanceRecord.Write`（勤怠打刻記録の書き込み権限）：打刻記録を DingTalk 勤怠アプリへアップロードします。

> [!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分前に更新してください。
* **同時実行制御**：複数のスレッドが同時にトークンを更新して競合が発生しないよう、分散ロックを使用してください。
* **エラー時のリトライ**：ネットワークが不安定な場合は、間隔を延ばしながら（1 秒 → 2 秒 → 4 秒）最大 3 回まで自動でリトライしてください。

### ステップ 4：コア API を呼び出す

1. **部門ユーザーの詳細情報を取得する**：連絡先のサーバー API [部門ユーザーの詳細情報を取得する](https://help.dingtalk.io/ja/open/development/queries-the-complete-information-of-a-department-user.md)を呼び出し、DingTalk の組織構成における各社員のユーザー ID を取得します。

   ```java theme={"theme":{"light":"github-light","dark":"github-dark"}}
   public void deptInfo() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/list");
       OapiV2UserListRequest req = new OapiV2UserListRequest();
       req.setDeptId(1L);
       req.setCursor(0L);
       req.setSize(10L);
       req.setOrderField("entry_asc");
       req.setContainAccessLimit(false);
       req.setLanguage("zh_CN");
       OapiV2UserListResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   ```
2. **打刻記録をアップロードする**：勤怠のサーバー API [打刻記録をアップロードする](https://help.dingtalk.io/ja/open/development/upload-punch-records.md)を呼び出し、自社システムの社員の打刻日時などの情報を DingTalk 勤怠アプリへアップロードします。これにより勤怠データが同期されます。

   ```java theme={"theme":{"light":"github-light","dark":"github-dark"}}
   public void attendanceRecordUpload() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/record/upload");
       OapiAttendanceRecordUploadRequest req = new OapiAttendanceRecordUploadRequest();
       req.setUserid("01472825524039877041");
       req.setDeviceName("東門打刻機");
       req.setDeviceId("dingTalk_one");
       req.setPhotoUrl("https://xxx.com/xxx.png");
       req.setUserCheckTime(1665363600000L);
       OapiAttendanceRecordUploadResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   ```

**実装チェックリスト**：

* アプリ認証情報（Client ID / Client Secret）を取得済みである。
* 連絡先と勤怠の権限が付与されている。
* access\_token を取得済みである。
* 部門ユーザーの詳細情報を取得する API の呼び出しに成功し、正しいユーザー ID の一覧が返された。
* 打刻記録をアップロードする API の呼び出しに成功し、DingTalk 勤怠アプリに同期された打刻データが表示されている。

## FAQ

* **Q1：打刻記録をアップロードする際に必須のパラメータは何ですか？**

  A：必須パラメータは次のとおりです。

  * `userid`：DingTalk の組織構成における社員のユーザー ID
  * `userCheckTime`：打刻時刻（Unix タイムスタンプ、ミリ秒単位）
  * `deviceId`：勤怠デバイスの ID
  * `deviceName`：勤怠デバイスの名前

    任意のパラメータとして `photoUrl`（打刻記録に添付する画像の URL。公開アクセス可能である必要があります）があります。
* **Q2：打刻データの同期に失敗する主な原因は何ですか？**

  A：主な原因は次のとおりです。

  * ユーザー ID が正しくない（DingTalk の組織構成に属する社員のものである必要があります）
  * userCheckTime の形式が無効、または未来の時刻が指定されている
  * access\_token が無効、または有効期限が切れている
  * アプリが勤怠の権限を申請していない
  * ネットワークリクエストのタイムアウト、またはサーバーエラー
* **Q3：複数の社員の打刻データを一括でアップロードする場合のベストプラクティスは何ですか？**

  A：現在、この API は 1 回の呼び出しにつき 1 件の打刻記録のみを受け付けます。一括でアップロードするには、業務レイヤーで API をループ処理で呼び出し、レート制限に達しないよう呼び出し頻度を制御してください。一括アップロードの方法については、DingTalk のテクニカルサポートにお問い合わせいただくこともできます。


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