tria-hr-api 1.1.2

Python client for interacting with the Tria HR API

Tria HR API Client

A Python client for interacting with the Tria HR API. This library provides easy access to attendance, organization units, and company data.

Installation

pip install triahr-client

Configuration

You can initialize the client in three different ways:

1. Using Configuration File

Create a config.ini file:

[Environment]
stage = https://stage.company.triahr.com
prod = https://company.triahr.com

[OAuth]
client_id = your_client_id
client_secret = your_client_secret

Initialize the client:

from triahr import TriaHRAPI

# Initialize using config file (defaults to 'stage' environment)
api = TriaHRAPI.from_config()

# Or specify a different environment
api = TriaHRAPI.from_config(environment='prod')

2. Direct Initialization

from triahr import TriaHRAPI

api = TriaHRAPI(
    base_url="https://stage.company.triahr.com",
    client_id="your_client_id",
    client_secret="your_client_secret"
)

3. Using JSON Credentials

This is particularly useful when using the library in Databricks:

from triahr import TriaHRAPI
import json

# When using Databricks secrets
credentials = json.loads(dbutils.secrets.get(scope="tria_hr", key="credentials"))
api = TriaHRAPI.from_json(
    base_url="https://stage.company.triahr.com",
    credentials_json=credentials
)

Required JSON format for credentials:

{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
}

Usage Examples

Test Connection

response = api.ping()
api.format_response(response)

Get Organization Units

# Get organization units for a specific company
org_units = api.organization_units(company_id="158")
api.format_response(org_units)

# Get attendance organization units
attendance_units = api.attendance_organization_units(company_id="158")
api.format_response(attendance_units)

Get Attendance Plans

# Get attendance plan for a single unit
attendance = api.attendance_plan(
    date_from="2024-01-01",
    date_to="2024-01-31",
    unit_id=123,
    mode="plan"  # or "reality" for published data
)
api.format_response(attendance)

# Get attendance plans for all units in a company
plans = api.attendance_plans(
    date_from="2024-01-01",
    date_to="2024-01-31",
    company_id="158",
    include_activated=True,     # include active units
    include_deactivated=False   # exclude deactivated units
)

Save Response to File

response = api.companies()
api.format_response(response, save_to_file="companies.json")

Custom API Requests

# Make a custom GET request
response = api.undefined_request(
    endpoint="/api/v1/custom-endpoint/",
    params={"param1": "value1"}
)

# Make a custom POST request
response = api.undefined_request(
    endpoint="/api/v1/custom-endpoint/",
    method="POST"
)

Available Methods

• ping(): Test API connection
• companies(): Get list of companies
• organization_units(company_id): Get organization units for a company
• attendance_organization_units(company_id): Get plannable attendance units
• attendance_plan(date_from, date_to, ...): Get attendance plan data for a single unit
• attendance_plans(date_from, date_to, company_id, ...): Get attendance plans for all units in a company
• undefined_request(endpoint, method, params): Make custom API requests

Authentication

The client handles OAuth2 authentication automatically, including token refresh. You only need to provide the client ID and secret.

Error Handling

The client will raise requests.exceptions.HTTPError for any API errors. Handle these appropriately in your application:

try:
    response = api.companies()
except requests.exceptions.HTTPError as e:
    print(f"API error: {e}")

Requirements

• Python ≥ 3.7
• requests ≥ 2.25.0