> ## 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. # 勤怠対象者の追加・取得・更新・削除 > 勤怠グループの対象者を追加・取得・更新・削除する API です。人事・OA システムと連携し、入退社や異動に伴うメンバー管理を自動化できます。 # 勤怠対象者の割り当て：一括追加と正確な管理 ## 概要 ### 背景 組織は常に変化しています。社員の入社、退職、職務の異動、部門間の移動が日常的に発生します。こうした変更のたびに、人事担当者や管理者は 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 には新バージョンと旧バージョンがあります。パフォーマンスと機能サポートの面で優れた新バージョンを優先して使用してください。 ### 前提条件 作業を始める前に、次の条件を満たしていることを確認してください。 * **アプリの準備**：社内アプリを作成して設定します。詳細は[アプリの作成と設定](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：`qyapi_attendance_group_manage` と `qyapi_attendance_group_read` の 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/batch-add-employees-under-the-attendance-group.md)を呼び出し、勤怠グループに勤怠対象者を追加します。 2. サーバー API [ユーザーの勤怠グループの取得](https://help.dingtalk.io/ja/open/development/queries-a-user-attendance-group.md)を呼び出し、ユーザーが所属する勤怠グループの情報を取得します。 3. 勤怠グループの勤怠対象者の情報を取得します。 * サーバー API [勤怠対象者のユーザー ID の取得](https://help.dingtalk.io/ja/open/development/query-attendance-group-personnel-information-in-batches.md)を呼び出し、勤怠対象者のユーザー ID を取得します。 * サーバー API [勤怠対象者の取得](https://help.dingtalk.io/ja/open/development/batch-query-of-attendance-group-members.md)を呼び出し、勤怠対象者の情報を取得します。 * サーバー API [勤怠対象者リストの照会](https://help.dingtalk.io/ja/open/development/batch-query-of-employees-in-the-attendance-group.md)を呼び出し、勤怠対象者のリストを取得します。 4. サーバー API [ユーザーが勤怠グループに所属しているかの確認](https://help.dingtalk.io/ja/open/development/query-members-by-id.md)を呼び出し、部門または社員が勤怠グループに所属しているかを確認します。 5. サーバー API [勤怠対象者の更新](https://help.dingtalk.io/ja/open/development/attendance-group-member-update.md)を呼び出し、勤怠グループの勤怠対象者を更新します。 6. サーバー API [勤怠対象者の一括削除](https://help.dingtalk.io/ja/open/development/batch-delete-employees-under-the-attendance-group.md)を呼び出し、勤怠対象者を削除します。 ## 実装手順 ### **ステップ 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 を呼び出す > [!NOTE] > > 勤怠グループ管理の作業フローについては、[勤怠ルールの設定：勤怠グループの一括作成と動的な調整](https://help.dingtalk.io/ja/open/development/operation-related-to-attendance-group.md)を参照してください。 1. **勤怠対象者を一括追加する**：サーバー API [勤怠対象者の一括追加](https://help.dingtalk.io/ja/open/development/batch-add-employees-under-the-attendance-group.md)を呼び出し、勤怠グループに勤怠対象者を追加します。 ```java theme={"theme":{"light":"github-light","dark":"github-dark"}} 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()); } ``` 2. **ユーザーの勤怠グループを取得する**：サーバー API [ユーザーの勤怠グループの取得](https://help.dingtalk.io/ja/open/development/queries-a-user-attendance-group.md)を呼び出し、ユーザーが所属する勤怠グループの情報を取得します。 ```java theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. **勤怠グループの勤怠対象者の情報を取得する** 次の 3 つのメンバー照会 API は、勤怠グループの勤怠対象者に部門が含まれる場合に主な違いが生じます。 管理コンソールで**勤怠** > **勤怠グループ管理**を開き、勤怠グループを編集します。**勤怠対象者**フィールドには、**部門**全体と個々の**ユーザー**を同時に指定できます。これとは別に**勤怠対象外者**フィールドもあります。 | API | 山田太郎さんのユーザー ID | テスト部門の部門 ID | テスト部門の社員のユーザー ID | | - | - | - | - | | [勤怠対象者のユーザー ID の取得](https://help.dingtalk.io/ja/open/development/query-attendance-group-personnel-information-in-batches.md) | ✅ | ❎ | ✅ | | [勤怠対象者の取得](https://help.dingtalk.io/ja/open/development/batch-query-of-attendance-group-members.md) | ✅ | ✅ | ❎ | | [勤怠対象者リストの照会](https://help.dingtalk.io/ja/open/development/batch-query-of-employees-in-the-attendance-group.md) | ✅ | ❎ | ❎ | **注**：✅ はデータを取得できることを、❎ はデータを取得できないことを示します。 * **勤怠対象者のユーザー ID を取得する**：サーバー API [勤怠対象者のユーザー ID の取得](https://help.dingtalk.io/ja/open/development/query-attendance-group-personnel-information-in-batches.md)を呼び出し、勤怠対象者のユーザー ID を取得します。 ```java theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 [勤怠対象者の取得](https://help.dingtalk.io/ja/open/development/batch-query-of-attendance-group-members.md)を呼び出し、勤怠対象者の情報を取得します。 ```java theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 [勤怠対象者リストの照会](https://help.dingtalk.io/ja/open/development/batch-query-of-employees-in-the-attendance-group.md)を呼び出し、勤怠対象者のリストを取得します。 ```java theme={"theme":{"light":"github-light","dark":"github-dark"}} 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()); } ``` 4. **ユーザーが勤怠グループに所属しているかを確認する**：サーバー API [ユーザーが勤怠グループに所属しているかの確認](https://help.dingtalk.io/ja/open/development/query-members-by-id.md)を呼び出し、社員が特定の勤怠グループに所属しているかを確認します。 ```java theme={"theme":{"light":"github-light","dark":"github-dark"}} 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()); } ``` 5. **勤怠対象者を更新する**：サーバー API [勤怠対象者の更新](https://help.dingtalk.io/ja/open/development/attendance-group-member-update.md)を呼び出し、勤怠グループのメンバーリストを調整します（社員または部門の追加・削除）。 ```java theme={"theme":{"light":"github-light","dark":"github-dark"}} 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()); } ``` 6. **勤怠対象者を一括削除する**：サーバー API [勤怠対象者の一括削除](https://help.dingtalk.io/ja/open/development/batch-delete-employees-under-the-attendance-group.md)を呼び出し、退職者や異動者を勤怠グループから削除します。 ```java theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 の取得](https://help.dingtalk.io/ja/open/development/query-attendance-group-personnel-information-in-batches.md)：ユーザー ID のリストのみを返します。勤怠グループにメンバーが存在するかどうかだけを確認したい場合に使用します。 * [勤怠対象者の取得](https://help.dingtalk.io/ja/open/development/batch-query-of-attendance-group-members.md)：メンバーの詳細情報（名前、部門など）を返します。メンバーの詳細を表示する必要がある場合に使用します。 * [勤怠対象者リストの照会](https://help.dingtalk.io/ja/open/development/batch-query-of-employees-in-the-attendance-group.md)：ページネーションによる照会に対応しています。メンバー数の多い勤怠グループで、メンバーを分割して取得する場合に使用します。 勤怠グループに部門メンバーが含まれる場合は、次の点に注意してください。個人のユーザー ID で照会すると、その社員の情報が返されます。一方、部門 ID で照会しても、その部門に属する社員の詳細は直接返されません。部門メンバーの照会 API を別途呼び出してください。 * **Q2：メンバーの一括追加で一部が失敗した場合は、どのように対処すればよいですか？** A：一括追加 API は「ベストエフォート」方式を採用しており、成功したメンバーと失敗したメンバーを分けて返します。次の手順で対処してください。 1. レスポンスを解析し、失敗したメンバーのユーザー ID とエラーの原因を抽出します。 2. 失敗内容をログに記録し、原因を分析します（例：ユーザーが存在しない、すでに勤怠グループに所属している）。 3. 回復可能なエラーはリトライします（例：新規作成したユーザーがまだ同期されていない）。 4. 回復不能なエラーはスキップし、ログに記録します（例：ユーザーがすでに組織を退職している）。 * **Q3：退職者を確実に削除するにはどうすればよいですか？** A：次の手順で、漏れなく削除してください。 1. OA の退職承認が承認された後、[ユーザーの勤怠グループの取得](https://help.dingtalk.io/ja/open/development/queries-a-user-attendance-group.md) API を呼び出し、社員が所属するすべての勤怠グループの ID を取得します。 2. すべての勤怠グループを順に処理し、[勤怠対象者の一括削除](https://help.dingtalk.io/ja/open/development/batch-delete-employees-under-the-attendance-group.md) API を呼び出して社員を削除します。 3. [ユーザーが勤怠グループに所属しているかの確認](https://help.dingtalk.io/ja/open/development/query-members-by-id.md) API を呼び出し、社員がすべての勤怠グループから削除されたことを確認します。 4. 勤怠グループ ID の一覧、操作日時、操作者を含めて、操作内容をログに記録します。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.