Time Planning

Usage

Work with planning versions and planned breaks:

import asyncio
import factorialhr

async def main():
    auth = factorialhr.AccessTokenAuth("your_access_token")
    async with factorialhr.ApiClient(auth=auth) as api:
        versions = factorialhr.PlanningVersionEndpoint(api)
        response = await versions.get(params={"limit": 10})
        for v in response.data():
            print(v.id, v.name)
        breaks = factorialhr.PlannedBreakEndpoint(api)
        for b in (await breaks.all()).data():
            print(b.planning_version_id, b.break_type)

asyncio.run(main())

class factorialhr.PlannedBreak(*, id: int, start_at: datetime | None = None, end_at: datetime | None = None, duration: int | None = None, break_type: BreakType, break_configuration_id: int, break_configuration_name: str, break_configuration_paid: bool, default_shift_id: int | None = None, shift_configuration_id: int | None = None, shift_id: int | None = None, day_configuration_id: int | None = None)[source]

Represents a planned break in time planning.

break_configuration_id: int: Break configuration identifier

break_configuration_name: str: Name of the break configuration

break_configuration_paid: bool: Whether the break is paid

break_type: BreakType: Type of the break

day_configuration_id: int | None: Day configuration identifier

default_shift_id: int | None: Default shift identifier

duration: int | None: Duration of the break in minutes

end_at: datetime | None: End date of the break

id: int: Identifier of the planned break

shift_configuration_id: int | None: Shift configuration identifier

shift_id: int | None: Shift identifier

start_at: datetime | None: Start date of the break

class factorialhr.PlannedBreakEndpoint(api: ApiClient)[source]

Endpoint for time_planning/planned_breaks operations.

async all(**kwargs) → ListApiResponse[PlannedBreak][source]

Get all planned breaks.

Official documentation: time_planning/planned_breaks

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[PlannedBreak]

async bulk_create(data: Mapping[str, Any], **kwargs) → Sequence[PlannedBreak][source]

Bulk create planned breaks.

Official documentation: time_planning/planned_breaks

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

Sequence[PlannedBreak]

async get(**kwargs) → MetaApiResponse[PlannedBreak][source]

Get planned breaks with pagination metadata.

Official documentation: time_planning/planned_breaks

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[PlannedBreak]

async get_by_id(break_id: int | str, **kwargs) → PlannedBreak[source]

Get a specific planned break by ID.

Official documentation: time_planning/planned_breaks

Parameters:

break_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

PlannedBreak

class factorialhr.PlanningVersion(*, id: int | None = None, effective_at: date, planning_tool: PlanningTool, number_of_rest_days_in_cents: int | None = None, employee_id: int, work_schedule_schedule_id: int | None = None)[source]

Model for time_planning_planning_version.

effective_at: date: Effective date of the planning version

employee_id: int: Employee ID

id: int | None: Planning version ID

number_of_rest_days_in_cents: int | None: Number of rest days in cents

planning_tool: PlanningTool: Type of planning tool

work_schedule_schedule_id: int | None: Work schedule ID

class factorialhr.PlanningVersionEndpoint(api: ApiClient)[source]

Endpoint for time_planning/planning_versions operations.

async all(**kwargs) → ListApiResponse[PlanningVersion][source]

Get all planning versions.

Official documentation: time_planning/planning_versions

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[PlanningVersion]

async bulk_create(data: Mapping[str, Any], **kwargs) → Sequence[PlanningVersion][source]

Bulk create planning versions.

Official documentation: time_planning/planning_versions

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

Sequence[PlanningVersion]

async create(data: Mapping[str, Any], **kwargs) → PlanningVersion[source]

Create a new planning version.

Official documentation: time_planning/planning_versions

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

PlanningVersion

async delete(version_id: int | str, **kwargs) → PlanningVersion[source]

Delete a planning version.

Official documentation: time_planning/planning_versions

Parameters:

version_id (int | str) – The unique identifier of the record to delete.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The deleted record.

Return type:

PlanningVersion

async get(**kwargs) → MetaApiResponse[PlanningVersion][source]

Get planning versions with pagination metadata.

Official documentation: time_planning/planning_versions

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[PlanningVersion]

async update(version_id: int | str, data: Mapping[str, Any], **kwargs) → PlanningVersion[source]

Update a planning version.

Official documentation: time_planning/planning_versions

Parameters:

version_id (int | str) – The unique identifier of the record to update.
data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated record.

Return type:

PlanningVersion