Timesheet¶

Timesheet API – gestione timesheet e time log in Zoho People.

Endpoint coperti:: GET /api/timetracker/gettimesheet – lista timesheet GET /api/timetracker/gettimesheetdetails – dettaglio timesheet POST /api/timetracker/createtimesheet – crea timesheet POST /api/timetracker/modifytimesheet – modifica / invia per approvazione POST /api/timetracker/deletetimesheet – elimina timesheet POST /api/timetracker/approvetimesheet – approva / rifiuta timesheet GET /api/timetracker/gettimelogdetails – dettaglio time log POST /api/timetracker/addtimelog – aggiungi time log POST /api/timetracker/edittimelog – modifica time log POST /api/timetracker/deletetimelog – elimina time log GET /api/timetracker/getpayrollreport – report payroll GET /api/timetracker/gettimetrackersettings – impostazioni generali

Scope richiesto: ZOHOPEOPLE.timetracker.ALL Rate limit: 20–50 req/min a seconda dell’endpoint.

class zoho_people.api.timesheet.TimesheetAPI(client)[source]¶

Bases: object

Gestione completa di timesheet e time log Zoho People.

Example

>>> # Lista timesheet approvati di aprile
>>> sheets = client.timesheet.list(
...     user="mario.rossi@azienda.it",
...     from_date="01-Apr-2026",
...     to_date="30-Apr-2026",
...     approval_status="approved",
... )

>>> # Crea un timesheet settimanale
>>> result = client.timesheet.create(
...     user="mario.rossi@azienda.it",
...     name="Settimana 17/2026",
...     from_date="20-04-2026",
...     to_date="26-04-2026",
...     send_for_approval=True,
... )

>>> # Aggiungi ore a un timesheet
>>> client.timesheet.add_timelog(
...     user="mario.rossi@azienda.it",
...     work_date="2026-04-25",
...     hours="08:00",
...     job_name="Sviluppo SDK",
...     billing_status="Billable",
... )

Parameters:: client (ZohoPeopleClient)

list(user, from_date=None, to_date=None, approval_status='all', employee_status='users', date_format=None, s_index=0, limit=200)[source]¶

Recupera la lista dei timesheet.

Parameters:

user (str) – Email, Employee ID, erecno o "all" per tutti.
from_date (str, optional) – Data inizio (nel formato aziendale o in date_format).
to_date (str, optional) – Data fine.
approval_status (str) – all | draft | pending | approved | rejected
employee_status (str) – users | nonusers | usersandnonusers | logindisabled
s_index (int) – Indice di inizio per la paginazione (default 0).
limit (int) – Numero di record per pagina (max 200).
date_format (str | None)

Returns:

Lista di timesheet con campi: recordId, timesheetName, status, totalHours, billableHours, fromDate, toDate, …

Return type:

list[dict]

get_all(user, **kwargs)[source]¶

Auto-paginazione: recupera TUTTI i timesheet dell’utente.

Parameters:: user (str)
Return type:: list[dict]

get_detail(timesheet_id)[source]¶

Recupera il dettaglio di un timesheet (time log inclusi).

Parameters:: timesheet_id (str) – ID del timesheet (recordId dalla lista).
Returns:: Dettaglio completo con time log, progetti, clienti.
Return type:: dict

create(user, name, from_date, to_date, description=None, billable_status='all', job_id='all', project_id='all', client_id='all', send_for_approval=False, date_format=None)[source]¶

Crea un nuovo timesheet.

Parameters:

user (str) – Email o Employee ID del dipendente.
name (str) – Nome del timesheet (es. "Settimana 17/2026").
from_date (str) – Data inizio.
to_date (str) – Data fine.
description (str, optional) – Descrizione del timesheet.
billable_status (str) – all | Billable | Non Billable
send_for_approval (bool) – Se True, invia subito per approvazione.
job_id (str)
project_id (str)
client_id (str)
date_format (str | None)

Returns:

{"timesheetId": [...], "message": "..."}

Return type:

dict

modify(timesheet_id, name=None, description=None, send_for_approval=None)[source]¶

Modifica un timesheet esistente o lo invia per approvazione.

Per ri-sottomettere un timesheet rifiutato usare send_for_approval=True.

Returns:

{"timesheetId": "...", "message": "..."}

Return type:

dict

Parameters:

timesheet_id (str)
name (str | None)
description (str | None)
send_for_approval (bool | None)

delete(timesheet_id)[source]¶

Elimina un timesheet.

Returns:: Risposta di conferma.
Return type:: dict
Parameters:: timesheet_id (str)

approve(timesheet_id, approval_status='approved', time_logs=None, comments=None, all_levels=False)[source]¶

Approva o rifiuta un timesheet (e opzionalmente i suoi time log).

Parameters:

timesheet_id (str) – ID del timesheet.
approval_status (str) – "approved" | "rejected"
time_logs (dict, optional) – Dict {timelog_id: "approved"|"rejected"} per approvazione parziale. Es: {"469505000000272225": "approved", "469505000000272083": "rejected"}
comments (str, optional) – Commento per l’approvazione/rifiuto.
all_levels (bool) – Se True, approva a tutti i livelli gerarchici.

Returns:

{"timesheetId": "...", "message": "..."}

Return type:

dict

get_timelog(timelog_id)[source]¶

Recupera il dettaglio di un singolo time log.

Returns:: Dettaglio con: workDate, hours, jobName, billingStatus, …
Return type:: dict
Parameters:: timelog_id (str)

add_timelog(user, work_date, hours, job_id=None, job_name=None, billing_status='Billable', work_item=None, description=None)[source]¶

Aggiunge un time log a un timesheet.

Almeno uno tra job_id e job_name è obbligatorio.

Parameters:

user (str) – Email o Employee ID del dipendente.
work_date (str) – Data di lavoro nel formato YYYY-MM-DD.
hours (str) – Ore lavorate nel formato HH:MM (es. "08:00").
job_id (str, optional) – ID del job/attività.
job_name (str, optional) – Nome del job/attività (alternativa a job_id).
billing_status (str) – "Billable" | "Non Billable"
work_item (str, optional) – Sottoattività / work item.
description (str, optional) – Descrizione delle ore lavorate.

Returns:

{"timeLogId": "...", "message": "..."}

Return type:

dict

edit_timelog(timelog_id, hours=None, work_date=None, billing_status=None, description=None)[source]¶

Modifica un time log esistente.

Returns:

Risposta di conferma.

Return type:

dict

Parameters:

timelog_id (str)
hours (str | None)
work_date (str | None)
billing_status (str | None)
description (str | None)

delete_timelog(timelog_id)[source]¶

Elimina un time log.

Returns:: Risposta di conferma.
Return type:: dict
Parameters:: timelog_id (str)

get_payroll_report(user, from_date, to_date, date_format=None)[source]¶

Recupera il report payroll (ore ordinarie, straordinari, ferie retribuite).

Parameters:

user (str) – Email, Employee ID, erecno o "all".
from_date (str) – Data inizio.
to_date (str) – Data fine.
date_format (str | None)

Returns:

Lista di record con: regularHour, OtHours, paidLeaveHours, totalAmount, …

Return type:

list[dict]

get_settings()[source]¶

Recupera le impostazioni generali del time tracker.

Returns:: Impostazioni: tipo log (ore/inizio-fine/timer), max ore/giorno, …
Return type:: dict

get_jobs(assigned_to=None, job_status='in-progress', s_index=0, limit=200)[source]¶

Recupera la lista dei job disponibili.

Parameters:

assigned_to (str, optional) – Email o Employee ID del dipendente. Se omesso → tutti i job.
job_status (str) – "in-progress" (default) | "completed" | "all"
s_index (int) – Indice di partenza per paginazione.
limit (int) – Max record (default 200).

Returns:

Lista di job con: jobId, jobName, projectName, clientName, jobStatus, jobBillableStatus, fromDate, toDate.

Return type:

list[dict]