Skip to content

timeman-close.md

Latest commit

 

History

History
424 lines (352 loc) · 12.9 KB

timeman-close.md

File metadata and controls

424 lines (352 loc) · 12.9 KB
Raw

Close Current Day timeman.close

{% note tip "" %}

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

{% endnote %}

Scope: timeman

Who can execute the method: any user

The method timeman.close ends the current workday.

Method Parameters

#| || Name type | Description || || USER_ID integer | User identifier.

Defaults to the current user || || TIME datetime | The end time and date of the workday in the ATOM (ISO-8601) format, for example, 2025-02-12T15:52:01+00:00. The date must match the start date of the workday.

By default, the workday is closed at the current moment in the timezone where the workday was started.

If the end timezone differs from the start timezone, the end time is automatically converted to the timezone in which the day was started. || || REPORT string | Reason for changing the workday.

Required under the conditions:

  • the TIME parameter is specified
  • the employee does not have a flexible schedule || || LAT double | Geographic latitude of the end of the workday || || LON double | Geographic longitude of the end of the workday || |#

Code Examples

{% include Examples Note %}

{% list tabs %}

  • cURL (Webhook)

    curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"USER_ID":503,"TIME":"2025-03-27T17:00:01+00:00","REPORT":"Forgot to close the workday","LAT":53.548841,"LON":9.987274}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/timeman.close

  • cURL (OAuth)

    curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"USER_ID":503,"TIME":"2025-03-27T17:00:01+00:00","REPORT":"Forgot to close the workday","LAT":53.548841,"LON":9.987274,"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/timeman.close

  • JS (TS)

    // This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

// Shape of the payload returned in result (match the "response handling" section of the page)
type TimemanCloseResult = {
  STATUS: string,
  TIME_START: ISODate,
  TIME_FINISH: ISODate | null,
  DURATION: string,
  TIME_LEAKS: string,
  ACTIVE: boolean,
  IP_OPEN: string,
  IP_CLOSE: string | null,
  LAT_OPEN: number,
  LON_OPEN: number,
  LAT_CLOSE: number,
  LON_CLOSE: number,
  TZ_OFFSET: number,
  TIME_FINISH_DEFAULT?: ISODate | null,
}

try {
  const response = await $b24.actions.v2.call.make<TimemanCloseResult>({
    method: 'timeman.close',
    params: {
      USER_ID: 503,
      TIME: '2025-03-27T17:00:01+00:00',
      REPORT: 'Forgot to close the workday',
      LAT: 53.548841,
      LON: 9.987274,
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info(result.STATUS, result.TIME_START, result.TIME_FINISH, result.DURATION)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

  • JS (UMD)

    <!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function closeWorkday() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'timeman.close',
        params: {
          USER_ID: 503,
          TIME: '2025-03-27T17:00:01+00:00',
          REPORT: 'Forgot to close the workday',
          LAT: 53.548841,
          LON: 9.987274,
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info(result.STATUS, result.TIME_START, result.TIME_FINISH, result.DURATION)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', closeWorkday)
</script>

  • Python

    from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.timeman.close(
        user_id=503,
        time="2025-03-27T17:00:01+00:00",
        report="Forgot to close the workday",
        lat=53.548841,
        lon=9.987274,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Bitrix API error",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Bitrix SDK error: {error.message}")
except Exception as error:
    print(f"Unexpected error: {error}")

  • PHP

    try {
    $response = $b24Service
        ->core
        ->call(
            'timeman.close',
            [
                'USER_ID' => 503,
                'TIME'    => '2025-03-27T17:00:01+00:00',
                'REPORT'  => 'Forgot to close the workday',
                'LAT'     => 53.548841,
                'LON'     => 9.987274,
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);
    // Your data processing logic
    processData($result);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error closing timeman: ' . $e->getMessage();
}

  • BX24.js

    BX24.callMethod(
    'timeman.close',
    {
        'USER_ID' : 503,
        'TIME': '2025-03-27T17:00:01+00:00',
        'REPORT': 'Forgot to close the workday',
        'LAT': 53.548841, 
        'LON': 9.987274
    },
    function(result) {
        if (result.error()) {
            console.error(result.error());
        } else {
            console.info(result.data());
        }
    }
);

  • PHP CRest

    require_once('crest.php');

$result = CRest::call(
    'timeman.close',
    [
        'USER_ID' => 503,
        'TIME' => '2025-03-27T17:00:01+00:00',
        'REPORT' => 'Forgot to close the workday',
        'LAT' => 53.548841,
        'LON' => 9.987274
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

  • Go

    // client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "timeman.close", b24.Params{
	"USER_ID": 503,
	"TIME":    "2025-03-27T17:00:01+00:00",
	"REPORT":  "Forgot to close the workday",
	"LAT":     53.548841,
	"LON":     9.987274,
})
if err != nil {
	return fmt.Errorf("timeman.close: %w", err)
}

var item struct {
	Status     string `json:"STATUS"`
	TimeStart  string `json:"TIME_START"`
	TimeFinish string `json:"TIME_FINISH"`
	Duration   string `json:"DURATION"`
	TimeLeaks  string `json:"TIME_LEAKS"`
	Active     bool   `json:"ACTIVE"`
}
if err := json.Unmarshal(res.Result, &item); err != nil {
	return fmt.Errorf("parse response: %w", err)
}
fmt.Println(item.Status, item.TimeStart)

{% endlist %}

Response Handling

HTTP Status: 200

{
    "result": {
        "STATUS": "CLOSED",
        "TIME_START": "2025-03-27T08:00:01+02:00",
        "TIME_FINISH": "2025-03-27T19:00:01+02:00",
        "DURATION": "09:37:04",
        "TIME_LEAKS": "01:22:56",
        "ACTIVE": false,
        "IP_OPEN": "",
        "IP_CLOSE": "83.219.151.30",
        "LAT_OPEN": 53.548841000000003,
        "LON_OPEN": 9.9872739999999993,
        "LAT_CLOSE": 53.548841000000003,
        "LON_CLOSE": 9.9872739999999993,
        "TZ_OFFSET": 7200
    },
    "time": {
        "start": 1743057653.725821,
        "finish": 1743057654.0894129,
        "duration": 0.36359190940856934,
        "processing": 0.3278491497039795,
        "date_start": "2025-03-27T09:40:53+03:00",
        "date_finish": "2025-03-27T09:40:54+03:00",
        "operating_reset_at": 1743058253,
        "operating": 0.32782983779907227
    }
}

Returned Data

#| || Name type | Description || || result object | Root element of the response.

Contains an object describing the workday || || STATUS string | Status of the current workday.

Possible values:

  • OPENED — opened
  • CLOSED — closed
  • PAUSED — paused
  • EXPIRED — expired, meaning opened before the start of the current calendar day and not closed || || TIME_START datetime | Date and time the workday started.

The timezone corresponds to the timezone of the start of the workday || || TIME_FINISH datetime | Date and time the workday was closed.

Returns null for an unfinished workday || || DURATION string | Duration of the workday in HH:MM:SS format.

Returns 00:00:00 for an unfinished workday || || TIME_LEAKS string | Total duration of breaks during the day in HH:MM:SS format. || || ACTIVE boolean | Confirmation of the workday.

A value of false means that the change to the workday is awaiting confirmation from the supervisor || || IP_OPEN string | IP address from which the workday started || || IP_CLOSE string | IP address from which the workday was closed.

Returns null for an unfinished workday || || LAT_OPEN double | Geographic latitude of the point where the workday started || || LON_OPEN double | Geographic longitude of the point where the workday started || || LAT_CLOSE double | Geographic latitude of the point where the workday was closed || || LON_CLOSE double | Geographic longitude of the point where the workday was closed || || TZ_OFFSET integer | Timezone offset of the employee in which the workday was started.

The end time of the workday is adjusted to the timezone of the start of the day || || TIME_FINISH_DEFAULT datetime | Recommended value for the end of the day, which can be presented to the user as a default value.

Displayed only for workdays in the expired status EXPIRED || || time time | Information about the time taken to process the request || |#

Error Handling

HTTP Status: 400

{
    "error":"WRONG_DATETIME",
    "error_description":"Day close date should correspond to the day open date"
}

{% include notitle error handling %}

Possible Error Codes

#| || Code | Description | Value || || TIMEMAN_TOOL_DISABLED | Working time management is disabled. | The time tracking tool is disabled || || empty string | User not found | User with the specified USER_ID not found || || WRONG_DATETIME | Day close date should correspond to the day open date | The closing date of the workday must match the opening date || |#

{% include system errors %}

Continue Learning