Batch Query Overtime Rule Settings

Call this API to batch query the details of overtime rule settings by multiple overtime rule IDs.

API Call Description

For example, suppose the overtime rule in your Organization’s attendance group is set to Calculate overtime by approval time. In the DingTalk admin console, go to Attendance group management > Modify attendance group > Overtime rules > Settings. The general overtime rule is set to Calculate overtime by approval time. This setting applies to workdays, rest days, and holidays: overtime must be approved, and the overtime duration is based on the approval form. Call this API to get the setting details of the Calculate overtime by approval time overtime rule, including the rule name and overtime calculation method. In the admin console, open Attendance rule management > Overtime rules and edit an overtime rule. The Edit overtime rule panel contains the following settings:

Field	Options / notes
Rule name	Up to 30 characters
Application scope	For example, the whole Organization (except those with other overtime rules)
Owner	Optional
Day-type tabs	Workday, Rest day, Holiday
Allow overtime	On/off toggle
Allowed overtime period	Before work, After work
Calculation method	Calculate by approval duration, or Calculate by punch duration within the approved period

The rule in this example uses the Calculate by approval duration method.

Request

Basic Information

Field	Value
HTTP URL	https://api.dingtalk.io/v1.0/attendance/overtimeSettings/query
HTTP Method	POST
Supported app types	appType-Internal app　appType-Third-party enterprise app
Permissions	permission-qyapi_attendance_group_read-Attendance group query permission

Request Header

Name	Type	Required	Description
x-acs-dingtalk-access-token	String	Yes	The access credential for calling this API. Obtain it as follows: - Internal app: Call the Get the access token of an internal app API. - Third-party enterprise app: Call the API for getting the access token of an Organization authorized to a Third-party app.

Request Body

Name	Type	Required	Description
overtimeSettingIds	Array of Long	No	The overtime rule setting IDs. Call the Query user scheduling information API to obtain them from the overtimeSettingId field in features.

Request Example

HTTP

POST /v1.0/attendance/overtimeSettings/query HTTP/1.1
Host:api.dingtalk.io
x-acs-dingtalk-access-token:1d96xxxx
Content-Type:application/json

{
  "overtimeSettingIds" : [ 12345678 ]
}

Java

// This file is auto-generated, don't edit it. Thanks.
package com.aliyun.sample;

import com.aliyun.tea.*;
import com.aliyun.teautil.*;
import com.aliyun.teautil.models.*;
import com.aliyun.dingtalkattendance_1_0.*;
import com.aliyun.dingtalkattendance_1_0.models.*;
import com.aliyun.teaopenapi.*;
import com.aliyun.teaopenapi.models.*;

public class Sample {

    /**
     * Initialize the account Client with a Token
     * @return Client
     * @throws Exception
     */
    public static com.aliyun.dingtalkattendance_1_0.Client createClient() throws Exception {
        Config config = new Config();
        config.protocol = "https";
        config.regionId = "central";
        return new com.aliyun.dingtalkattendance_1_0.Client(config);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.dingtalkattendance_1_0.Client client = Sample.createClient();
        GetOvertimeSettingHeaders getOvertimeSettingHeaders = new GetOvertimeSettingHeaders();
        getOvertimeSettingHeaders.xAcsDingtalkAccessToken = "<your access token>";
        GetOvertimeSettingRequest getOvertimeSettingRequest = new GetOvertimeSettingRequest()
                .setOvertimeSettingIds(java.util.Arrays.asList(
                    12345678L
                ));
        try {
            client.getOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, new RuntimeOptions());
        } catch (TeaException err) {
            if (!com.aliyun.teautil.Common.empty(err.code) && !com.aliyun.teautil.Common.empty(err.message)) {
                // err contains the code and message attributes to help troubleshoot the issue
            }

        } catch (Exception _err) {
            TeaException err = new TeaException(_err.getMessage(), _err);
            if (!com.aliyun.teautil.Common.empty(err.code) && !com.aliyun.teautil.Common.empty(err.message)) {
                // err contains the code and message attributes to help troubleshoot the issue
            }

        }        
    }
}

Python

# -*- coding: utf-8 -*-
# This file is auto-generated, don't edit it. Thanks.
import sys

from typing import List

from alibabacloud_dingtalk.attendance_1_0.client import Client as dingtalkattendance_1_0Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_dingtalk.attendance_1_0 import models as dingtalkattendance__1__0_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient

class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client() -> dingtalkattendance_1_0Client:
        """
        Initialize the account Client with a Token
        @return: Client
        @throws Exception
        """
        config = open_api_models.Config()
        config.protocol = 'https'
        config.region_id = 'central'
        return dingtalkattendance_1_0Client(config)

    @staticmethod
    def main(
        args: List[str],
    ) -> None:
        client = Sample.create_client()
        get_overtime_setting_headers = dingtalkattendance__1__0_models.GetOvertimeSettingHeaders()
        get_overtime_setting_headers.x_acs_dingtalk_access_token = '<your access token>'
        get_overtime_setting_request = dingtalkattendance__1__0_models.GetOvertimeSettingRequest(
            overtime_setting_ids=[
                12345678
            ]
        )
        try:
            client.get_overtime_setting_with_options(get_overtime_setting_request, get_overtime_setting_headers, util_models.RuntimeOptions())
        except Exception as err:
            if not UtilClient.empty(err.code) and not UtilClient.empty(err.message):
                # err contains the code and message attributes to help troubleshoot the issue
                pass

    @staticmethod
    async def main_async(
        args: List[str],
    ) -> None:
        client = Sample.create_client()
        get_overtime_setting_headers = dingtalkattendance__1__0_models.GetOvertimeSettingHeaders()
        get_overtime_setting_headers.x_acs_dingtalk_access_token = '<your access token>'
        get_overtime_setting_request = dingtalkattendance__1__0_models.GetOvertimeSettingRequest(
            overtime_setting_ids=[
                12345678
            ]
        )
        try:
            await client.get_overtime_setting_with_options_async(get_overtime_setting_request, get_overtime_setting_headers, util_models.RuntimeOptions())
        except Exception as err:
            if not UtilClient.empty(err.code) and not UtilClient.empty(err.message):
                # err contains the code and message attributes to help troubleshoot the issue
                pass

if __name__ == '__main__':
    Sample.main(sys.argv[1:])

PHP

<?php

// This file is auto-generated, don't edit it. Thanks.
namespace AlibabaCloud\SDK\Sample;

use AlibabaCloud\SDK\Dingtalk\Vattendance_1_0\Dingtalk;
use \Exception;
use AlibabaCloud\Tea\Exception\TeaError;
use AlibabaCloud\Tea\Utils\Utils;

use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\SDK\Dingtalk\Vattendance_1_0\Models\GetOvertimeSettingHeaders;
use AlibabaCloud\SDK\Dingtalk\Vattendance_1_0\Models\GetOvertimeSettingRequest;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;

class Sample {

    /**
     * Initialize the account Client with a Token
     * @return Dingtalk Client
     */
    public static function createClient(){
        $config = new Config([]);
        $config->protocol = "https";
        $config->regionId = "central";
        return new Dingtalk($config);
    }

    /**
     * @param string[] $args
     * @return void
     */
    public static function main($args){
        $client = self::createClient();
        $getOvertimeSettingHeaders = new GetOvertimeSettingHeaders([]);
        $getOvertimeSettingHeaders->xAcsDingtalkAccessToken = "<your access token>";
        $getOvertimeSettingRequest = new GetOvertimeSettingRequest([
            "overtimeSettingIds" => [
                12345678
            ]
        ]);
        try {
            $client->getOvertimeSettingWithOptions($getOvertimeSettingRequest, $getOvertimeSettingHeaders, new RuntimeOptions([]));
        }
        catch (Exception $err) {
            if (!($err instanceof TeaError)) {
                $err = new TeaError([], $err->getMessage(), $err->getCode(), $err);
            }
            if (!Utils::empty_($err->code) && !Utils::empty_($err->message)) {
                // err contains the code and message attributes to help troubleshoot the issue
            }
        }
    }
}
$path = __DIR__ . \DIRECTORY_SEPARATOR . '..' . \DIRECTORY_SEPARATOR . 'vendor' . \DIRECTORY_SEPARATOR . 'autoload.php';
if (file_exists($path)) {
    require_once $path;
}
Sample::main(array_slice($argv, 1));

// This file is auto-generated, don't edit it. Thanks.
package main

import (
  "os"
  util  "github.com/alibabacloud-go/tea-utils/service"
  dingtalkattendance_1_0  "github.com/alibabacloud-go/dingtalk/attendance_1_0"
  openapi  "github.com/alibabacloud-go/darabonba-openapi/client"
  "github.com/alibabacloud-go/tea/tea"
)

/**
 * Initialize the account Client with a Token
 * @return Client
 * @throws Exception
 */
func CreateClient () (_result *dingtalkattendance_1_0.Client, _err error) {
  config := &openapi.Config{}
  config.Protocol = tea.String("https")
  config.RegionId = tea.String("central")
  _result = &dingtalkattendance_1_0.Client{}
  _result, _err = dingtalkattendance_1_0.NewClient(config)
  return _result, _err
}

func _main (args []*string) (_err error) {
  client, _err := CreateClient()
  if _err != nil {
    return _err
  }

  getOvertimeSettingHeaders := &dingtalkattendance_1_0.GetOvertimeSettingHeaders{}
  getOvertimeSettingHeaders.XAcsDingtalkAccessToken = tea.String("<your access token>")
  getOvertimeSettingRequest := &dingtalkattendance_1_0.GetOvertimeSettingRequest{
    OvertimeSettingIds: []*int64{tea.Int(12345678)},
  }
  tryErr := func()(_e error) {
    defer func() {
      if r := tea.Recover(recover()); r != nil {
        _e = r
      }
    }()
    _, _err = client.GetOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, &util.RuntimeOptions{})
    if _err != nil {
      return _err
    }

    return nil
  }()

  if tryErr != nil {
    var err = &tea.SDKError{}
    if _t, ok := tryErr.(*tea.SDKError); ok {
      err = _t
    } else {
      err.Message = tea.String(tryErr.Error())
    }
    if !tea.BoolValue(util.Empty(err.Code)) && !tea.BoolValue(util.Empty(err.Message)) {
      // err contains the code and message attributes to help troubleshoot the issue
    }

  }
  return _err
}

func main() {
  err := _main(tea.StringSlice(os.Args[1:]))
  if err != nil {
    panic(err)
  }
}

Node.js

// This file is auto-generated, don't edit it
import Util, * as $Util from '@alicloud/tea-util';
import dingtalkattendance_1_0, * as $dingtalkattendance_1_0 from '@alicloud/dingtalk/attendance_1_0';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import * as $tea from '@alicloud/tea-typescript';

export default class Client {

  /**
   * Initialize the account Client with a Token
   * @return Client
   * @throws Exception
   */
  static createClient(): dingtalkattendance_1_0 {
    let config = new $OpenApi.Config({ });
    config.protocol = "https";
    config.regionId = "central";
    return new dingtalkattendance_1_0(config);
  }

  static async main(args: string[]): Promise<void> {
    let client = Client.createClient();
    let getOvertimeSettingHeaders = new $dingtalkattendance_1_0.GetOvertimeSettingHeaders({ });
    getOvertimeSettingHeaders.xAcsDingtalkAccessToken = "<your access token>";
    let getOvertimeSettingRequest = new $dingtalkattendance_1_0.GetOvertimeSettingRequest({
      overtimeSettingIds: [
        12345678
      ],
    });
    try {
      await client.getOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, new $Util.RuntimeOptions({ }));
    } catch (err) {
      if (!Util.empty(err.code) && !Util.empty(err.message)) {
        // err contains the code and message attributes to help troubleshoot the issue
      }

    }    
  }

}

Client.main(process.argv.slice(2));

// This file is auto-generated, don't edit it. Thanks.

using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

using Tea;
using Tea.Utils;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample 
    {

        /**
         * Initialize the account Client with a Token
         * @return Client
         * @throws Exception
         */
        public static AlibabaCloud.SDK.Dingtalkattendance_1_0.Client CreateClient()
        {
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config();
            config.Protocol = "https";
            config.RegionId = "central";
            return new AlibabaCloud.SDK.Dingtalkattendance_1_0.Client(config);
        }

        public static void Main(string[] args)
        {
            AlibabaCloud.SDK.Dingtalkattendance_1_0.Client client = CreateClient();
            AlibabaCloud.SDK.Dingtalkattendance_1_0.Models.GetOvertimeSettingHeaders getOvertimeSettingHeaders = new AlibabaCloud.SDK.Dingtalkattendance_1_0.Models.GetOvertimeSettingHeaders();
            getOvertimeSettingHeaders.XAcsDingtalkAccessToken = "<your access token>";
            AlibabaCloud.SDK.Dingtalkattendance_1_0.Models.GetOvertimeSettingRequest getOvertimeSettingRequest = new AlibabaCloud.SDK.Dingtalkattendance_1_0.Models.GetOvertimeSettingRequest
            {
                OvertimeSettingIds = new List<long?>
                {
                    12345678
                },
            };
            try
            {
                client.GetOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, new AlibabaCloud.TeaUtil.Models.RuntimeOptions());
            }
            catch (TeaException err)
            {
                if (!AlibabaCloud.TeaUtil.Common.Empty(err.Code) && !AlibabaCloud.TeaUtil.Common.Empty(err.Message))
                {
                    // err contains the code and message attributes to help troubleshoot the issue
                }
            }
            catch (Exception _err)
            {
                TeaException err = new TeaException(new Dictionary<string, object>
                {
                    { "message", _err.Message }
                });
                if (!AlibabaCloud.TeaUtil.Common.Empty(err.Code) && !AlibabaCloud.TeaUtil.Common.Empty(err.Message))
                {
                    // err contains the code and message attributes to help troubleshoot the issue
                }
            }
        }

    }
}

C++

// This file is auto-generated, don't edit it. Thanks.

#include <alibabacloud/dingtalkattendance__1__0.hpp>
#include <alibabacloud/open_api.hpp>
#include <boost/any.hpp>
#include <darabonba/core.hpp>
#include <darabonba/util.hpp>
#include <iostream>
#include <map>
#include <vector>

using namespace std;

Alibabacloud_Dingtalkattendance_1_0::Client createClient() {
  shared_ptr<Alibabacloud_OpenApi::Config> config = make_shared<Alibabacloud_OpenApi::Config>();
  config->protocol = make_shared<string>("https");
  config->regionId = make_shared<string>("central");
  return Alibabacloud_Dingtalkattendance_1_0::Client(config);
}

int main(int argc, char *args[]) {
  args++;
  shared_ptr<Alibabacloud_Dingtalkattendance_1_0::Client> client = make_shared<Alibabacloud_Dingtalkattendance_1_0::Client>(createClient());
  shared_ptr<Alibabacloud_Dingtalkattendance_1_0::GetOvertimeSettingHeaders> getOvertimeSettingHeaders = make_shared<Alibabacloud_Dingtalkattendance_1_0::GetOvertimeSettingHeaders>();
  getOvertimeSettingHeaders->xAcsDingtalkAccessToken = make_shared<string>("<your access token>");
  shared_ptr<Alibabacloud_Dingtalkattendance_1_0::GetOvertimeSettingRequest> getOvertimeSettingRequest = make_shared<Alibabacloud_Dingtalkattendance_1_0::GetOvertimeSettingRequest>(map<string, boost::any>({
    {"overtimeSettingIds", boost::any(vector<long>({
      12345678
    }))}
  }));
  try {
    client->getOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, make_shared<Darabonba_Util::RuntimeOptions>(Darabonba_Util::RuntimeOptions()));
  }
  catch (std::exception &err) {
    if (!Darabonba_Util::Client::empty(err.code) && !Darabonba_Util::Client::empty(err.message)) {
      // err contains the code and message attributes to help troubleshoot the issue
    }
  }
}

Response

Response Body

Name	Type	Description
result	Array	The list of overtime setting details.
settingId	Long	The setting ID.
name	String	The rule name.
default	Boolean	Whether this is the default rule. - true: Yes - false: No
durationSettings	`Map<String, Object>`	The list of Date types for the overtime rule.
	Object	The details of the overtime rule type.
calcType	Integer	Whether an Approval form is required for overtime. Valid values: - 1: An Approval form must be submitted - 2: No Approval form is required - 3: Overtime is not allowed
durationType	Integer	The calculation method. Valid values: - 1: Calculated by Approval form duration - 2: Calculated by clock-in duration
overtimeRedress	Boolean	The switch for counting overtime duration as compensatory leave or overtime pay.
settings	Map	The value is Overtime start time or Minimum overtime duration.
overtimeRedressBy	String	How overtime duration is counted. Valid values: - vacation: Counted as compensatory leave - charge: Counted as overtime pay - manual: Chosen by the Employee
vacationRate	Float	The calculation ratio for compensatory leave duration.
skipTime	String	How break time is deducted. Valid values: - frame: Deduct by break period - duration: Deduct by overtime duration
skipTimeByFrames	Array	Deduction by break period. This parameter has a value only when skipTime is frame.
startTime	String	The start time, in `HH:mm` format.
endTime	String	The end time, in `HH:mm` format.
valid	Boolean	Whether the setting is in effect. - true: In effect - false: Not in effect
skipTimeByDurations	Array	Deduction by overtime duration. This parameter has a value only when skipTime is duration.
duration	Long	The daily overtime threshold duration, in seconds.
minus	Long	The deducted duration, in seconds.
holidayPlanOvertimeRedress	Boolean	The switch for counting scheduled overtime on rest days or holidays as compensatory leave or overtime pay.
holidayPlanOvertimeRedressBy	String	How scheduled overtime on rest days or holidays is counted. Valid values: - vacation: Counted as compensatory leave - charge: Counted as overtime pay - manual: Chosen by the Employee
holidayPlanVacationRate	Float	The calculation ratio for compensatory leave duration for scheduled overtime on rest days or holidays.
warningSettings	Array	The alert settings.
time	String	The alert type. Valid values: - everyday: Daily - everyweek: Weekly - everymonth: Monthly
threshold	Long	The reminder threshold.
action	String	The value is Risk alert or Maximum overtime duration.
stepType	Integer	The unit of overtime duration.
stepValue	Float	Whether the overtime duration is rounded, in hours. Valid values: - 1: No rounding - Other values: Round down to the nearest multiple of the step value
workMinutesPerDay	Integer	The equivalent duration of one day, in minutes.
overtimeDivisions	Array	The time split rules.
previousDayType	String	The type of the previous day.
nextDayType	String	The type of the next day.
timeSplitPoint	String	The time split point.
id	Long	The historical overtime rule setting ID.

Response Body Example

HTTP/1.1 200 OK
Content-Type:application/json

{
  "result" : [ {
    "settingId" : 841251521,
    "name" : "Test overtime rule name",
    "default" : false,
    "durationSettings" : {
      "key" : {
        "calcType" : 1,
        "durationType" : 2,
        "overtimeRedress" : true,
        "overtimeRedressBy" : "charge",
        "vacationRate" : 1,
        "skipTime" : "frame",
        "skipTimeByFrames" : [ {
          "startTime" : "12:00",
          "endTime" : "13:00",
          "valid" : true
        } ],
        "skipTimeByDurations" : [ {
          "duration" : 18000,
          "minus" : 3600
        } ],
        "holidayPlanOvertimeRedress" : true,
        "holidayPlanOvertimeRedressBy" : "vacation",
        "holidayPlanVacationRate" : 1
      }
    },
    "warningSettings" : [ {
      "time" : "everymonth",
      "threshold" : 129600,
      "action" : "alert"
    } ],
    "stepType" : 0,
    "stepValue" : 1,
    "workMinutesPerDay" : 480,
    "overtimeDivisions" : [ {
      "previousDayType" : "workDay",
      "nextDayType" : "restDay",
      "timeSplitPoint" : "00:00"
    } ],
    "id" : 12345678
  } ]
}

Error Codes

If a call to this API fails, find a solution in the Global error codes Document based on the error message.

HttpCode	Error code	Error message	Description
400	invalidSize	Invalid size	Invalid size of overtimeSettingIds
400	invalidParameter	Parameter error	Invalid overtimeSettingIds parameter
500	systemError	System error	System error

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Attendance

Docs & files

IM

API Call Description

Request

Basic Information

Request Header

Request Body

Request Example

Response

Response Body

Response Body Example

Error Codes

​API Call Description

​Request

​Basic Information

​Request Header

​Request Body

​Request Example

​Response

​Response Body

​Response Body Example

​Error Codes

API Call Description

Request

Basic Information

Request Header

Request Body

Request Example

Response

Response Body

Response Body Example

Error Codes