Developer GuideAPI Call Description
Compensatory leave types do not require initialization through this API. Overtime duration automatically converts to compensatory leave duration. Create leave rules in either of 2 ways: by calling an API, or through the official DingTalk Attendance app:| Leave Rule Creation Method | Leave Type Updates Supported by This API |
|---|---|
| Leave types created by calling the Add Leave Rules API. | Supported |
| Leave types created in the Attendance app in the Admin Console. - Created by default by the Attendance app system. - Created through the Attendance app backend. | Not supported |
Request
| Basic Information | |
|---|---|
| HTTP URL | https://api.dingtalk.io/topapi/attendance/vacation/quota/init |
| HTTP Method | POST |
| Supported App Types | appType-Internal app appType-Third-party enterprise app |
| Permission Requirements | permission-qyapi_holiday_manage-DingTalk leave 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, obtain it by calling the Get the access_token of an Internal App API. - For a Third-party enterprise app, obtain it by calling the API for getting the access_token of a third-party organization. |
Request Body
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| op_userid | String | Yes | manager1 | The user ID of an admin in your organization who has app permissions for OA Approval. |
| leave_quotas | LeaveQuotas | Yes | The leave balance records to initialize. | |
| userid | String | Yes | zhangsan | The user ID of the employee. |
| end_time | Number | Yes | 1653851001000 | The end time of the quota validity period, as a timestamp in milliseconds. |
| start_time | Number | Yes | 1553851001000 | The start time of the quota validity period, as a timestamp in milliseconds. |
| leave_code | String | Yes | f84a282xxxx | The unique identifier of the leave type. Note - Initialization is supported for leave types added by calling the Add Leave Rules API. - Initialization is not supported for the organization’s built-in leave types. |
| reason | String | No | Imported by admin | The reason for the action. |
| quota_num_per_day | Number | No | 100 | The total quota, calculated in days. Note When the leave type is calculated in days, this value must not be empty and is measured in hundredths of a day. For example, 1000 = 10 days. |
| quota_num_per_hour | Number | No | 100 | The total quota, calculated in hours. Note When the leave type is calculated in hours, this value must not be empty and is measured in hundredths of an hour. For example, 1000 = 10 hours. |
| quota_cycle | String | No | 2019 | The cycle that the quota applies to. Note The format must be “yyyy”. |
Request Example
curl -X POST "https://api.dingtalk.io/topapi/attendance/vacation/quota/init" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=d82be2bxxxx023' \
-d 'leave_quotas=null' \
-d 'op_userid=zhangsan'
DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/vacation/quota/init");
OapiAttendanceVacationQuotaInitRequest req = new OapiAttendanceVacationQuotaInitRequest();
req.setOpUserid("zhangsan");
List<LeaveQuotas> list = new ArrayList<LeaveQuotas>();
LeaveQuotas leaveQuotas = new LeaveQuotas();
list.add(leaveQuotas);
leaveQuotas.setUserid("user1");
leaveQuotas.setEndTime(1653851001000L);
leaveQuotas.setStartTime(1553851001000L);
leaveQuotas.setLeaveCode("f84a2829-xxxx0653");
leaveQuotas.setReason("Imported by admin");
leaveQuotas.setQuotaNumPerDay(100L);
leaveQuotas.setQuotaNumPerHour(100L);
leaveQuotas.setQuotaCycle("2019");
req.setLeaveQuotas(list);
OapiAttendanceVacationQuotaInitResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
import dingtalk.api
req=dingtalk.api.OapiAttendanceVacationQuotaInitRequest("https://api.dingtalk.io/topapi/attendance/vacation/quota/init")
req.op_userid="zhangsan"
req.leave_quotas=""
try:
resp= req.getResponse(access_token)
print(resp)
except Exception,e:
print(e)
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');
$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiAttendanceVacationQuotaInitRequest;
$req->setOpUserid("zhangsan");
$leave_quotas = new LeaveQuotas;
$leave_quotas->userid="zhangsan";
$leave_quotas->end_time="1653851001000";
$leave_quotas->start_time="1553851001000";
$leave_quotas->leave_code="f84a2829-d245-4312-9ff2-0653e5b3abb2";
$leave_quotas->reason="Imported by admin";
$leave_quotas->quota_num_per_day="100";
$leave_quotas->quota_num_per_hour="100";
$leave_quotas->quota_cycle="2019";
$req->setLeaveQuotas(array($leave_quotas));
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/attendance/vacation/quota/init");
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/vacation/quota/init");
OapiAttendanceVacationQuotaInitRequest req = new OapiAttendanceVacationQuotaInitRequest();
req.OpUserid = "zhangsan";
List<OapiAttendanceVacationQuotaInitRequest.LeaveQuotasDomain> list2 = new List<OapiAttendanceVacationQuotaInitRequest.LeaveQuotasDomain>();
OapiAttendanceVacationQuotaInitRequest.LeaveQuotasDomain obj3 = new OapiAttendanceVacationQuotaInitRequest.LeaveQuotasDomain();
list2.Add(obj3);
obj3.Userid = "zhangsan";
obj3.EndTime = 1653851001000L;
obj3.StartTime = 1553851001000L;
obj3.LeaveCode = "f84a2829-d245-4312-9ff2-0653e5b3abb2";
obj3.Reason = "Imported by admin";
obj3.QuotaNumPerDay = 100L;
obj3.QuotaNumPerHour = 100L;
obj3.QuotaCycle = "2019";
req.LeaveQuotas_ = list2;
OapiAttendanceVacationQuotaInitResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
Response
Response Body
| Name | Type | Example | Description |
|---|---|---|---|
| result | Result[] | The returned result. | |
| reason | String | The quota calculated in days cannot be empty | The reason for the failure. |
| quota | Quota | The failed record. | |
| leave_code | String | f84a2829-xxxx0653 | The unique identifier of the leave type. |
| userid | String | user1 | The user ID of the employee. |
| quota_cycle | String | 2019 | The cycle that the quota applies to. |
| errcode | Number | 0 | The return code. |
| errmsg | String | ok | The error message returned when the call fails. |
| success | Boolean | true | Indicates whether the request succeeded. - true: Yes - false: No |
| request_id | String | zq4aec1jton8 | The request ID. |
Response Body Example
{
"errcode": 0,
"result": [
{
"quota": {
"leave_code": "f84a2829-xxxx0653",
"userid": "10203029011219896"
},
"reason": "The quota calculated in days cannot be empty"
}
],
"success": true,
"request_id": "zq4aec1jton8"
}