Notify Shift Swap Approval

Call this API to notify the attendance system to perform the shift swap action after the shift swap approval is granted. Users can swap shifts with themselves or with other users.

API Call Description

The following constraints apply to shift swaps:

Both parties must belong to a shift-based attendance group.
Both parties must have a scheduled shift or a scheduled day off on both the swap date and the return date.
The clock-in times after the swap cannot conflict. For example, the shift on the 1st is 08:00-22:00, and the shift on the 2nd is 10:00-09:00 (next day). If the shifts on the 1st and the 2nd are swapped, the shift on the 1st becomes 10:00-09:00 (next day), and the shift on the 2nd becomes 08:00-22:00. In this case, the clock-in time range of the 1st overlaps with the working hours of the 2nd. This is called a clock-in time conflict.
Shift swaps cannot be undone.

Request

Basic Information
HTTP URL	https://api.dingtalk.io/topapi/attendance/approve/schedule/switch
HTTP Method	POST
Supported App Types	appType-Internal app　appType-Third-party enterprise app
Required Permissions	permission-qyapi_attendance_group_manage-Attendance group management permission

Query Parameters

Name	Type	Required	Example	Description
access_token	String	Yes	bE74xxxx	The app credential used to call this API. - For an Internal app, call the Get the access_token of an Internal App API to obtain it. - For a Third-party enterprise app, call the Get the access_token of a Third-party Organization API to obtain it.

Request Body

Name	Type	Required	Example	Description
userid	String	Yes	manager123	The user ID of the initiator.
switch_date	String	Yes	2019-09-08	The requested shift swap date. A scheduled shift or a scheduled day off must exist on this date.
reback_date	String	Yes	2019-09-09	The return date. A scheduled shift or a scheduled day off must exist on this date. Note If the requester and the target user are the same person, the return date is required.
apply_userid	String	Yes	manager123	The user ID of the shift swap requester. Only users in a shift-based attendance group are supported.
target_userid	String	Yes	user123	The user ID of the target user. Only users in a shift-based attendance group are supported.
approve_id	String	Yes	2376620852	The Approval form ID. This is a Custom parameter value.
apply_shift_id	Number	Yes	1234566	The shift ID of the requester on the swap date. Call the Batch Query User Scheduling Information API to obtain the shift_id value.
target_shift_id	Number	Yes	1234566	The shift ID of the target user on the swap date. Call the Batch Query User Scheduling Information API to obtain the shift_id value.
reback_apply_shift_id	Number	Yes	1234566	The shift ID of the requester on the return date. Call the Batch Query User Scheduling Information API to obtain the shift_id value.
reback_target_shift_id	Number	Yes	1234566	The shift ID of the target user on the return date. Call the Batch Query User Scheduling Information API to obtain the shift_id value.

Request Example

curl -X POST "https://api.dingtalk.io/topapi/attendance/approve/schedule/switch" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=82683xxxxc28be8' \
-d 'apply_shift_id=123' \
-d 'apply_userid=dd_dd' \
-d 'approve_id=asdasdjashd' \
-d 'reback_apply_shift_id=789' \
-d 'reback_date=2019-09-09' \
-d 'reback_target_shift_id=897' \
-d 'switch_date=2019-09-08' \
-d 'target_shift_id=456' \
-d 'target_userid=aa_aa' \
-d 'userid=dd_dd'

Java

DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/approve/schedule/switch");
OapiAttendanceApproveScheduleSwitchRequest req = new OapiAttendanceApproveScheduleSwitchRequest();
req.setUserid("dd_dd");
req.setSwitchDate("2019-09-08");
req.setRebackDate("2019-09-09");
req.setApplyUserid("dd_dd");
req.setTargetUserid("aa_aa");
req.setApplyShiftId(123L);
req.setTargetShiftId(456L);
req.setRebackApplyShiftId(789L);
req.setRebackTargetShiftId(897L);
req.setApproveId("asdasdjashd");
OapiAttendanceApproveScheduleSwitchResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiAttendanceApproveScheduleSwitchRequest("https://api.dingtalk.io/topapi/attendance/approve/schedule/switch")

req.userid="dd_dd"
req.switch_date="2019-09-08"
req.reback_date="2019-09-09"
req.apply_userid="dd_dd"
req.target_userid="aa_aa"
req.apply_shift_id=123
req.target_shift_id=456
req.reback_apply_shift_id=789
req.reback_target_shift_id=897
req.approve_id="asdasdjashd"
try:
  resp= req.getResponse(access_token)
  print(resp)
except Exception,e:
  print(e)

PHP

include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiAttendanceApproveScheduleSwitchRequest;
$req->setUserid("dd_dd");
$req->setSwitchDate("2019-09-08");
$req->setRebackDate("2019-09-09");
$req->setApplyUserid("dd_dd");
$req->setTargetUserid("aa_aa");
$req->setApplyShiftId("123");
$req->setTargetShiftId("456");
$req->setRebackApplyShiftId("789");
$req->setRebackTargetShiftId("897");
$req->setApproveId("asdasdjashd");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/attendance/approve/schedule/switch");

IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/approve/schedule/switch");
OapiAttendanceApproveScheduleSwitchRequest req = new OapiAttendanceApproveScheduleSwitchRequest();
req.Userid = "dd_dd";
req.SwitchDate = "2019-09-08";
req.RebackDate = "2019-09-09";
req.ApplyUserid = "dd_dd";
req.TargetUserid = "aa_aa";
req.ApplyShiftId = 123L;
req.TargetShiftId = 456L;
req.RebackApplyShiftId = 789L;
req.RebackTargetShiftId = 897L;
req.ApproveId = "asdasdjashd";
OapiAttendanceApproveScheduleSwitchResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response Body

Name	Type	Example	Description
errcode	Number	0	The return code.
errmsg	String	ok	The description of the return code.

Response Body Example

{
        "errcode":0,
        "errmsg":"872995737"
}

Error Codes

If an error occurs when you call this API, find a solution in the Global Error Codes document based on the error message.

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Attendance

Docs & files

IM

API Call Description

Request

Query Parameters

Request Body

Request Example

Response

Response Body

Response Body Example

Error Codes

​API Call Description

​Request

​Query Parameters

​Request Body

​Request Example

​Response

​Response Body

​Response Body Example

​Error Codes

API Call Description

Request

Query Parameters

Request Body

Request Example

Response

Response Body

Response Body Example

Error Codes