​

休暇・勤怠承認の連携：休暇・勤怠データを DingTalk 勤怠へ自動同期する

​

概要

​

背景

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

​

主なメリット

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

​

ユースケース

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

​

代表的な業務シナリオ

​

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

​

課題

​

導入効果

• 自動化された作業フロー 打刻データのリアルタイム同期フローは、次の 5 つのステップで構成されます。
  1. 社員が自社システムで打刻します。
  2. 自社勤怠システムが DingTalk API を呼び出し、データチャネルを確立します。
  3. 自社システムが API を通じて、DingTalk における社員の一意の識別子（userId）を取得します。
  4. 自社システムが打刻記録を DingTalk 勤怠へアップロードします。
  5. DingTalk 勤怠アプリが打刻状況をリアルタイムに表示します。
  アップロード時のパラメータ例：userid、userCheckTime、deviceId。
• 主な効果
  • 二重作業の解消：社員が自社勤怠システムで打刻すると、データは API を通じて DingTalk 勤怠へ同期されます。社員が打刻修正を申請したり、データを再入力したりする必要はありません。
  • 手作業による確認の削減：打刻記録がリアルタイムに同期されるため、人事担当者が打刻修正申請を 1 件ずつ確認する必要がなくなります。手作業による確認業務が大幅に減り、時間を節約できます。
  • データ精度の向上：自動同期により、人手の介在や入力ミスがなくなります。勤怠データの真正性、正確性、追跡可能性を確保できます。
  • ユーザー体験の向上：社員はリアルタイムに打刻状況を確認でき、打刻漏れや打刻修正の申請忘れを心配する必要がなくなります。

​

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

​

課題

​

導入効果

• 自動化された作業フロー 複数の勤怠デバイスの打刻データを DingTalk に統合するデータフローは、次のとおりです。
  1. 社員がさまざまな勤怠デバイスで打刻します。
  2. 各デバイスがデータをリアルタイムに自社勤怠システムへアップロードします。
  3. 自社システムが DingTalk オープンプラットフォーム API を呼び出し、勤怠データを一括でアップロードします。
  4. DingTalk がすべての打刻データを受信し、統合して一元的に保存・管理します。
  5. 人事担当者が DingTalk のワークベンチで、統合された勤怠レポートと分析結果を確認します。
  従来の方法では、複数のシステムにログインし、Excel データをエクスポートして、手作業でデータを統合しレポートを作成する必要がありました。このフローでは、データが DingTalk に自動で集約され、ワンクリックでレポートを生成できます。
• 主な効果
  • 複数ソースのデータを統一：指紋認証端末、顔認証端末、GPS 位置情報などの勤怠デバイスの打刻データを、DingTalk 上で 1 つの標準形式に統合します。データのサイロ化を解消できます。
  • ワンストップ管理：人事担当者は、複数のシステムへのログインや Excel ファイルのエクスポート・手作業での統合を行うことなく、DingTalk ですべての社員の勤怠記録をリアルタイムに確認できます。
  • 統計処理の迅速化：システムがデータを自動で集計し、レポートを生成します。勤怠統計にかかる期間を大幅に短縮できます。
  • 手作業の削減：エクスポート、データクレンジング、統合といった繰り返しの手作業を自動化で置き換えます。人件費を削減し、人為的ミスのリスクを低減します。

​

実装ガイド

​

技術アーキテクチャ

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

​

前提条件

• アプリ：社内アプリを作成し、設定済みであること。詳細は、アプリの作成と設定を参照してください。
• 権限：DingTalk の組織管理者またはサブ管理者の権限を持ち、次の API 権限を申請済みであること。
  • qyapi_get_department_member（連絡先の部門メンバーの読み取り権限）
  • Pro.AttendanceRecord.Write（勤怠打刻記録の書き込み権限）
• 開発環境：Java 開発環境（JDK 1.6 以降）と Maven ビルドツールをインストール済みであること。
• SDK：DingTalk サーバーサイド SDK をダウンロード済みであること。詳細は、サーバーサイド SDK のダウンロードページを参照してください。SDK は Java、Python、Go などの言語に対応しています。

​

コードの実装

1. 連絡先のサーバー API 部門ユーザーの詳細情報を取得するを呼び出し、DingTalk の組織構成における各社員のユーザー ID を取得します。
2. 勤怠のサーバー API 打刻記録をアップロードするを呼び出し、自社システムの社員の打刻日時などの情報を DingTalk 勤怠アプリへアップロードします。これにより勤怠データが同期されます。

​

実装手順

​

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

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

​

注意

​

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

1. アプリの詳細ページで、権限管理をクリックします。
2. 権限の検索ボックスに次の権限識別子を入力し、申請します。
   • qyapi_get_department_member（連絡先の部門メンバーの読み取り権限）：部門ユーザーの詳細情報を取得し、ユーザー ID を取得します。
   • Pro.AttendanceRecord.Write（勤怠打刻記録の書き込み権限）：打刻記録を DingTalk 勤怠アプリへアップロードします。

​

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

​

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

1. 部門ユーザーの詳細情報を取得する：連絡先のサーバー API 部門ユーザーの詳細情報を取得するを呼び出し、DingTalk の組織構成における各社員のユーザー ID を取得します。
   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 打刻記録をアップロードするを呼び出し、自社システムの社員の打刻日時などの情報を DingTalk 勤怠アプリへアップロードします。これにより勤怠データが同期されます。
   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 のテクニカルサポートにお問い合わせいただくこともできます。