Payroll

Usage

Fetch payroll-related data (family situations, supplements, policy periods):

import asyncio
import factorialhr

async def main():
    auth = factorialhr.AccessTokenAuth("your_access_token")
    async with factorialhr.ApiClient(auth=auth) as api:
        family = factorialhr.FamilySituationsEndpoint(api)
        for f in (await family.all()).data():
            print(f.name)
        supplements = factorialhr.SupplementsEndpoint(api)
        response = await supplements.get(params={"page": 1})
        for s in response.data():
            print(s.employee_id, s.amount)

asyncio.run(main())

class factorialhr.EmployeesIdentifier(*, id: int, employee_id: int, social_security_number: str | None = None, tax_id: str | None = None, country: CountryCode)[source]

Model for payroll_employees_identifier.

country: CountryCode: Country code of the employee (pt | it | de)

employee_id: int: Identifier of the employee

id: int: Payroll employee identifier

social_security_number: str | None: Social security number of the employee

tax_id: str | None: Tax id of the employee

class factorialhr.FamilySituation(*, id: int, employee_id: int, civil_status: CivilStatus | None = None, number_of_dependants: int | None = None)[source]

Model for payroll_family_situation.

civil_status: CivilStatus | None: Civil status of the employee

employee_id: int: Employee id of the family situation

id: int: ID of the family situation

number_of_dependants: int | None: Number of dependants of the employee

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

Endpoint for payroll/family_situations operations.

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

Get all family situations records.

Official documentation: payroll/family_situations

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[FamilySituation]

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

Create a new family situation.

Official documentation: payroll/family_situations

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:

FamilySituation

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

Get family situations with pagination metadata.

Official documentation: payroll/family_situations

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[FamilySituation]

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

Update a family situation.

Official documentation: payroll/family_situations

Parameters:

family_situation_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:

FamilySituation

class factorialhr.IntegrationsBaseCode(*, id: int, company_id: int, code: str, codeable_id: int, codeable_type: str, integration: Integration)[source]

Model for payroll_integrations_base_code.

code: str: Code value

codeable_id: int: Related object ID. Used together with codeable_type

codeable_type: str: Related object type. Used together with codeable_id (Employee | Company | LegalEntity | Location | TimeoffLeaveType)

company_id: int: Company ID where the code belongs to

id: int: Code identifier

integration: Integration: Integration name

class factorialhr.PolicyPeriod(*, id: int, name: str | None = None, starts_on: date, policy_id: int, company_id: int, ends_on: date, period: str, status: str | None = None, policy_name: str | None = None, calculation_started_at: date | None = None)[source]

Model for payroll_policy_period.

calculation_started_at: date | None: The date and time the calculation started

company_id: int: The id of the company

ends_on: date: The end date of the policy period

id: int: Policy period id

name: str | None: Policy name with start and end date

period: str: Period for the policy

policy_id: int: The id of the policy associated with the policy period

policy_name: str | None: Policy name

starts_on: date: The start date of the policy period

status: str | None: Policy period status

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

Endpoint for payroll/policy_periods operations.

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

Change status of a policy period.

Official documentation: payroll/policy_periods

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:

Result.

Return type:

PolicyPeriod

class factorialhr.Supplement(*, id: int, employee_id: int, company_id: int, contracts_compensation_id: int | None = None, contracts_taxonomy_id: int | None = None, amount_in_cents: int | None = None, unit: Unit, effective_on: str | None = None, created_at: bool | None = None, updated_at: bool | None = None, description: str | None = None, payroll_policy_period_id: int | None = None, employee_observations: Sequence[str] | None = None, raw_minutes_in_cents: int | None = None, minutes_in_cents: int | None = None, equivalent_minutes_in_cents: int | None = None, currency: str | None = None, legal_entity_id: int | None = None)[source]

Model for payroll_supplement.

amount_in_cents: int | None: The amount of the supplement in cents

company_id: int: The identifier of the company associated with the supplement

contracts_compensation_id: int | None: The contract compensation identifier associated with the supplement

contracts_taxonomy_id: int | None: The taxonomy identifier associated with the supplement

created_at: bool | None: The created at date when the supplement was created

currency: str | None: The currency used for the supplement, typically in ISO 4217 format

description: str | None: The description of the supplement

effective_on: str | None: The date on which the supplement becomes effective

employee_id: int: The identifier of the employee associated with the supplement

employee_observations: Sequence[str] | None: Observations on the employee made by the admin or manager

equivalent_minutes_in_cents: int | None: The equivalent value of minutes in cents for payroll processing

id: int: The identifier of the supplement

legal_entity_id: int | None: The legal entity identifier associated with the supplement

minutes_in_cents: int | None: The value of minutes in cents after adjustments

payroll_policy_period_id: int | None: The payroll policy period identifier associated with the supplement

raw_minutes_in_cents: int | None: The raw value of minutes in cents associated with the supplement

unit: Unit: The unit of the supplement

updated_at: bool | None: The last updated at date when the supplement was last updated

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

Endpoint for payroll/supplements operations.

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

Get all supplements records.

Official documentation: payroll/supplements

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[Supplement]

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

Create a new supplement.

Official documentation: payroll/supplements

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:

Supplement

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

Delete a supplement.

Official documentation: payroll/supplements

Parameters:

supplement_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:

Supplement

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

Get supplements with pagination metadata.

Official documentation: payroll/supplements

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[Supplement]

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

Get a specific supplement by ID.

Official documentation: payroll/supplements

Parameters:

supplement_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:

Supplement

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

Update a supplement.

Official documentation: payroll/supplements

Parameters:

supplement_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:

Supplement