勤怠対象者の割り当て：一括追加と正確な管理

概要

背景

組織は常に変化しています。社員の入社、退職、職務の異動、部門間の移動が日常的に発生します。こうした変更のたびに、人事担当者や管理者は DingTalk 管理コンソールで勤怠グループのメンバーを 1 人ずつ更新する必要があります。新入社員は勤怠グループに追加し、退職者は削除し、異動者は別の勤怠グループへ移す必要があります。社員数が 1,000 人を超える組織では、変更が毎月数十件から数百件に及ぶこともあります。手作業での更新には多くの時間と労力がかかります。さらに漏れや誤りが発生しやすく、打刻エラーや勤怠データの不正確さにつながります。

主なメリット

本ソリューションは、勤怠グループメンバーのライフサイクル全体を自動化します。手作業で行っていた一括追加・照会・更新・削除を、API による標準化された操作に置き換えます。その結果、人事システムの運用効率が向上し、データの一貫性が保たれます。

メンバー管理の一括自動化：API を通じてメンバーを追加・照会・更新・削除でき、手作業は不要です。
最適な API の選択：個人、部門、または混在したメンバー構成に応じて最適な照会 API を選び、完全かつ正確なデータを取得できます。
リアルタイム検証：ユーザーが特定の勤怠グループに所属しているかを確認し、更新直後に結果を検証してデータの一貫性を保ちます。
システム間のデータ統一：人事システム、OA システム、DingTalk の間で勤怠グループメンバーのデータをリアルタイムに同期し、データのサイロ化を解消します。

ユースケース

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

社員の入社：人事担当者が人事システムに新入社員を登録すると、該当部門の勤怠グループに自動で追加します。
社員の退職：OA の退職承認が承認されると、すべての勤怠グループから社員を自動で削除します。
職務の異動：社員が異動すると、元の勤怠グループから削除し、異動先部門の勤怠グループに自動で追加します。
メンバーの一括調整：組織構成の変更後、複数の勤怠グループのメンバーリストを一括で更新します。

典型的な業務シナリオ

シナリオ 1：新入社員を勤怠グループに自動で追加する

課題

従来の運用では、人事担当者は新入社員の初日ごとに DingTalk 管理コンソールにログインし、該当部門の勤怠グループを探して新入社員を 1 人ずつ手作業で追加する必要があります。毎日 5〜10 人が入社する場合、人事担当者はこの作業を何度も繰り返すことになります。追加漏れやグループの選択ミスが起こりやすく、新入社員が正常に打刻できない事態が発生します。

導入効果

自動化フロー 自動化フローは次の 5 つのステップで実行されます。
1. 人事担当者が新しい社員の情報（名前、部門、役職）を登録します。
2. 社員の部門 ID から対象の勤怠グループを特定し、その groupKey を取得します。
3. batch-add-employees API を呼び出し、新入社員の userId を勤怠グループに追加します。
4. query-members-by-id API を呼び出し、社員が正常に追加されたことを確認します。
5. 当日から打刻権限が有効になり、勤怠の記録が開始されます。
主な利点
- 完全自動のトリガー：人事担当者が新入社員を登録すると、人事システムが API を呼び出して社員を勤怠グループに追加します。手作業は不要です。
- 正確なマッチング：社員の部門に対応する勤怠グループをシステムが自動で特定するため、選択ミスを防げます。
- 即時反映：追加直後にシステムが結果を検証するため、新入社員は初日から打刻できます。
- 監査証跡：各操作で操作者、タイムスタンプ、勤怠グループ ID を記録し、コンプライアンス要件を満たします。

シナリオ 2：退職者を勤怠グループから自動で削除する

課題

社員が退職すると、人事担当者は関連するすべての勤怠グループからその社員を手作業で削除する必要があります。社員が複数の勤怠グループ（たとえば所属部門とプロジェクトチーム）に所属している場合、手作業では削除漏れが起こりやすくなります。その結果、退職者が引き続き打刻できてしまい、勤怠データが不正確になり、給与計算に誤りが生じるおそれがあります。

導入効果

自動化フロー 自動化フローは次の 5 つのステップで実行されます。
1. OA承認の退職申請が承認されると、システムがイベントを検知して自動化をトリガーします。
2. queries-a-user-attendance-group API を呼び出し、社員が所属するすべての勤怠グループの ID を取得します。
3. 取得したグループを順に処理し、batch-delete-employees API を呼び出して社員を一括で削除します。
4. query-members-by-id API を呼び出し、社員がすべての勤怠グループから削除されたことを 1 つずつ確認します。
5. 社員の打刻権限が取り消され、勤怠の記録が停止します。
主な利点
- 完全自動のトリガー：OA の退職承認が承認されると、削除処理が自動で実行され、手作業は不要です。
- 漏れのない対応：1 回の処理ですべての勤怠グループを照会して社員を削除するため、削除漏れを防げます。
- 即時反映：削除直後にシステムが結果を検証するため、退職者は打刻できなくなります。
- 完全な監査ログ：すべての削除操作で詳細情報を記録し、コンプライアンス監査とトレーサビリティの要件を満たします。

実装ガイド

技術アーキテクチャ

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

認証レイヤー：Client ID と Client Secret を使用して access_token を取得し、API 呼び出しの安全性を確保します。
メンバー管理レイヤー：勤怠グループメンバーを一括で追加・照会・更新・削除するための API 機能を網羅的に提供します。
スマートルーティングレイヤー：メンバーの種類（個人、部門、または混在）に応じて最適な照会 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：クライアント ID と Client Secret を含むアプリ認証情報を取得します。ステップ 2：qyapi_attendance_group_manage と qyapi_attendance_group_read の API 権限を申請します。ステップ 3：アクセス認証情報を取得します。詳細は社内アプリの access_token を取得するを参照してください。API を呼び出す際、アクセストークンによって呼び出し元の身元が認証されます。ステップ 4：勤怠関連の API を呼び出します。

サーバー API 勤怠対象者の一括追加を呼び出し、勤怠グループに勤怠対象者を追加します。
サーバー API ユーザーの勤怠グループの取得を呼び出し、ユーザーが所属する勤怠グループの情報を取得します。
勤怠グループの勤怠対象者の情報を取得します。
- サーバー API 勤怠対象者のユーザー ID の取得を呼び出し、勤怠対象者のユーザー ID を取得します。
- サーバー API 勤怠対象者の取得を呼び出し、勤怠対象者の情報を取得します。
- サーバー API 勤怠対象者リストの照会を呼び出し、勤怠対象者のリストを取得します。
サーバー API ユーザーが勤怠グループに所属しているかの確認を呼び出し、部門または社員が勤怠グループに所属しているかを確認します。
サーバー API 勤怠対象者の更新を呼び出し、勤怠グループの勤怠対象者を更新します。
サーバー API 勤怠対象者の一括削除を呼び出し、勤怠対象者を削除します。

実装手順

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

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

注意

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

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

アプリの詳細ページで、権限管理をクリックします。
権限の検索ボックスに次の権限識別子を入力し、申請します。
- qyapi_attendance_group_manage（勤怠グループ管理権限）：勤怠グループを作成・更新・削除します。
- qyapi_attendance_group_read（勤怠グループ照会権限）：勤怠グループの概要と詳細を照会します。

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

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

ステップ 1 で取得した Client ID と Client Secret を使用して、アクセス認証情報を取得します。詳細は社内アプリの 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 を呼び出す

勤怠グループ管理の作業フローについては、勤怠ルールの設定：勤怠グループの一括作成と動的な調整を参照してください。

勤怠対象者を一括追加する：サーバー API 勤怠対象者の一括追加を呼び出し、勤怠グループに勤怠対象者を追加します。

public void  addAttendanceMembers() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/users/add");
        OapiAttendanceGroupUsersAddRequest req = new OapiAttendanceGroupUsersAddRequest();
        req.setOpUserid("manager7675");
  			//groupKey の取得：groupId を groupKey に変換します。勤怠グループ管理の作業フローを参照してください
        req.setGroupKey("2A5**********24");
        req.setUserIdList("085218*********9877041");
        OapiAttendanceGroupUsersAddResponse rsp = client.execute(req, "access_token");
        System.out.println(rsp.getBody());
    }

ユーザーの勤怠グループを取得する：サーバー API ユーザーの勤怠グループの取得を呼び出し、ユーザーが所属する勤怠グループの情報を取得します。

 public void attendanceUserGroup() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/getusergroup");
        OapiAttendanceGetusergroupRequest req = new OapiAttendanceGetusergroupRequest();
        req.setUserid("0852**********72");
        OapiAttendanceGetusergroupResponse rsp = client.execute(req, "access_token");
        System.out.println(rsp.getBody());
    }

勤怠グループの勤怠対象者の情報を取得する 次の 3 つのメンバー照会 API は、勤怠グループの勤怠対象者に部門が含まれる場合に主な違いが生じます。管理コンソールで勤怠 > 勤怠グループ管理を開き、勤怠グループを編集します。勤怠対象者フィールドには、部門全体と個々のユーザーを同時に指定できます。これとは別に勤怠対象外者フィールドもあります。

API	山田太郎さんのユーザー ID	テスト部門の部門 ID	テスト部門の社員のユーザー ID
勤怠対象者のユーザー ID の取得	✅	❎	✅
勤怠対象者の取得	✅	✅	❎
勤怠対象者リストの照会	✅	❎	❎

注：✅ はデータを取得できることを、❎ はデータを取得できないことを示します。

勤怠対象者のユーザー ID を取得する：サーバー API 勤怠対象者のユーザー ID の取得を呼び出し、勤怠対象者のユーザー ID を取得します。

 public void attendanceGroupMemberUsers() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/memberusers/list");
        OapiAttendanceGroupMemberusersListRequest req = new OapiAttendanceGroupMemberusersListRequest();
        req.setCursor(0L);
        req.setOpUserId("ma********75");
        req.setGroupId(1001290520L);
        OapiAttendanceGroupMemberusersListResponse rsp = client.execute(req, "access_token");
        System.out.println(rsp.getBody());
    }

勤怠対象者の情報を取得する：サーバー API 勤怠対象者の取得を呼び出し、勤怠対象者の情報を取得します。

 public void groupMemberList() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/member/list");
        OapiAttendanceGroupMemberListRequest req = new OapiAttendanceGroupMemberListRequest();
        req.setCursor(0L);
        req.setOpUserId("ma*******5");
        req.setGroupId(1001290520L);
        OapiAttendanceGroupMemberListResponse rsp = client.execute(req, "access_token");
        System.out.println(rsp.getBody());
    }

勤怠対象者のリストを照会する（ページネーション対応）： サーバー API 勤怠対象者リストの照会を呼び出し、勤怠対象者のリストを取得します。

  public void groupUsersQuery() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/users/query");
        OapiAttendanceGroupUsersQueryRequest req = new OapiAttendanceGroupUsersQueryRequest();
        req.setSize(50L);
        req.setCursor("");
        req.setOpUserid("m*******75");
        req.setGroupKey("2A5B6**********EF24");
        OapiAttendanceGroupUsersQueryResponse rsp = client.execute(req, "access_token");
        System.out.println(rsp.getBody());
    }

ユーザーが勤怠グループに所属しているかを確認する：サーバー API ユーザーが勤怠グループに所属しているかの確認を呼び出し、社員が特定の勤怠グループに所属しているかを確認します。

public void checkGroupMember() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/member/listbyids");
        OapiAttendanceGroupMemberListbyidsRequest req = new OapiAttendanceGroupMemberListbyidsRequest();
        req.setOpUserId("m*******75");
        req.setMemberIds("085**********272");
        req.setMemberType(0L);
        req.setGroupId(1001290520L);
        OapiAttendanceGroupMemberListbyidsResponse rsp = client.execute(req, "access_token");
        System.out.println(rsp.getBody());
    }

勤怠対象者を更新する：サーバー API 勤怠対象者の更新を呼び出し、勤怠グループのメンバーリストを調整します（社員または部門の追加・削除）。

 public void updateGroupMember() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/member/update");
        OapiAttendanceGroupMemberUpdateRequest req = new OapiAttendanceGroupMemberUpdateRequest();
        req.setOpUserId("man*****75");
        req.setGroupId(1001290520L);
        req.setScheduleFlag(0L);
        OapiAttendanceGroupMemberUpdateRequest.TopGroupMemberUpdateParam updateParam = new OapiAttendanceGroupMemberUpdateRequest.TopGroupMemberUpdateParam();
//        updateParam.setAddDepts(Arrays.asList("123"));
//        updateParam.setRemoveDepts(Arrays.asList("456"));
        updateParam.setAddUsers(Arrays.asList("012**********197"));
//        updateParam.setAddExtraUsers(Arrays.asList("user456"));
//        updateParam.setRemoveExtraUsers(Arrays.asList("user789"));
//        updateParam.setRemoveUsers(Arrays.asList("user121"));
        req.setUpdateParam(updateParam);
        OapiAttendanceGroupMemberUpdateResponse rsp = client.execute(req, "access_token");
        System.out.println(rsp.getBody());
    }

勤怠対象者を一括削除する：サーバー API 勤怠対象者の一括削除を呼び出し、退職者や異動者を勤怠グループから削除します。

 public void deleteGroupMember() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/users/remove");
        OapiAttendanceGroupUsersRemoveRequest req = new OapiAttendanceGroupUsersRemoveRequest();
        req.setOpUserid("ma******75");
        req.setGroupKey("2A5************F24");
        req.setUserIdList("012*********3197");
        OapiAttendanceGroupUsersRemoveResponse rsp = client.execute(req, "access_token");
        System.out.println(rsp.getBody());
    }

実装チェックリスト：

✅ すべての API 呼び出しが成功ステータスコード（errcode=0）を返している。
✅ 追加・削除の各操作後に検証 API を呼び出し、結果を確認している。
✅ 問題の追跡に必要なエラーログが漏れなく記録されている。
✅ 人事システムと DingTalk の勤怠グループメンバーのデータを定期的に照合し、一貫性が保たれている。

FAQ

Q1：3 つのメンバー照会 API にはどのような違いがありますか？ A：各 API は、異なるメンバー種別のシナリオに適しています。
- 勤怠対象者のユーザー ID の取得：ユーザー ID のリストのみを返します。勤怠グループにメンバーが存在するかどうかだけを確認したい場合に使用します。
- 勤怠対象者の取得：メンバーの詳細情報（名前、部門など）を返します。メンバーの詳細を表示する必要がある場合に使用します。
- 勤怠対象者リストの照会：ページネーションによる照会に対応しています。メンバー数の多い勤怠グループで、メンバーを分割して取得する場合に使用します。
勤怠グループに部門メンバーが含まれる場合は、次の点に注意してください。個人のユーザー ID で照会すると、その社員の情報が返されます。一方、部門 ID で照会しても、その部門に属する社員の詳細は直接返されません。部門メンバーの照会 API を別途呼び出してください。
Q2：メンバーの一括追加で一部が失敗した場合は、どのように対処すればよいですか？ A：一括追加 API は「ベストエフォート」方式を採用しており、成功したメンバーと失敗したメンバーを分けて返します。次の手順で対処してください。
1. レスポンスを解析し、失敗したメンバーのユーザー ID とエラーの原因を抽出します。
2. 失敗内容をログに記録し、原因を分析します（例：ユーザーが存在しない、すでに勤怠グループに所属している）。
3. 回復可能なエラーはリトライします（例：新規作成したユーザーがまだ同期されていない）。
4. 回復不能なエラーはスキップし、ログに記録します（例：ユーザーがすでに組織を退職している）。
Q3：退職者を確実に削除するにはどうすればよいですか？ A：次の手順で、漏れなく削除してください。
1. OA の退職承認が承認された後、ユーザーの勤怠グループの取得 API を呼び出し、社員が所属するすべての勤怠グループの ID を取得します。
2. すべての勤怠グループを順に処理し、勤怠対象者の一括削除 API を呼び出して社員を削除します。
3. ユーザーが勤怠グループに所属しているかの確認 API を呼び出し、社員がすべての勤怠グループから削除されたことを確認します。
4. 勤怠グループ ID の一覧、操作日時、操作者を含めて、操作内容をログに記録します。

API 呼び出しガイド

認証と認可

連絡先

カレンダー

会議

AI Table

勤怠

Docs とファイル

IM

勤怠対象者の追加・取得・更新・削除

勤怠対象者の割り当て：一括追加と正確な管理

概要

背景

主なメリット

ユースケース

典型的な業務シナリオ

シナリオ 1：新入社員を勤怠グループに自動で追加する

課題

導入効果

シナリオ 2：退職者を勤怠グループから自動で削除する

課題

導入効果

実装ガイド

技術アーキテクチャ

前提条件

コードの実装

実装手順

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

注意

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

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

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

FAQ

​勤怠対象者の割り当て：一括追加と正確な管理

​概要

​背景

​主なメリット

​ユースケース

​典型的な業務シナリオ

​シナリオ 1：新入社員を勤怠グループに自動で追加する

​課題

​導入効果

​シナリオ 2：退職者を勤怠グループから自動で削除する

​課題

​導入効果

​実装ガイド

​技術アーキテクチャ

​前提条件

​コードの実装

​実装手順

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

​注意

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

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

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

​FAQ

勤怠対象者の割り当て：一括追加と正確な管理

概要

背景

主なメリット

ユースケース

典型的な業務シナリオ

シナリオ 1：新入社員を勤怠グループに自動で追加する

課題

導入効果

シナリオ 2：退職者を勤怠グループから自動で削除する

課題

導入効果

実装ガイド

技術アーキテクチャ

前提条件

コードの実装

実装手順

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

注意

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

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

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

FAQ