Cleverfy

ADMIN ONLY, DESTRUCTIVE. Undo a historical-data import batch: removes the time entries and cancels the absences that batch brought in, and nothing else. Confirm with the user before calling. Works in chunks: each result says what it did (cancelledNow, revertedTimeEntries), what it did not (needsConfirmation, refused, failed, deferred), what is left (remaining) and where it goes on (next). Call again with the same batchId and afterDate/afterId from next ONLY while a call makes progress and remaining > blocked; never repeat in a loop a call that undid nothing. blocked = imported entries with a correction pending, left untouched until a person resolves it. Cancelling an imported absence on dates with approved absences by hours changes the hours ledger: such absences come back in needsConfirmation and are NOT cancelled. Then STOP and ask the user: call with preview=true (a page; follow nextPreview), show them what changes, and only after they approve call with confirmedEffects for exactly the absences shown. Preview each page after writing the previous one; a fingerprint that comes back in needsConfirmation has new effects: show them and ask again. On refused or failed, stop and report them. Never compute or reuse a fingerprint yourself. A reverted batch cannot be reused; import again to get a new one. Requires OAuth scope import:write.

revert_import

Raw clock-records grid for a team over a date range: clock in/out, breaks, worked hours (its extraordinary_hours is that day's excess over the schedule, not legal overtime), modification count and verification metadata. Its complementary_hours is that day's excess of a part-time person, not the legal figure: it may be complementary, over the contract without a pact or with the split pending, and the person may have 0 complementary hours in the period; the figures of the period are in team_hours_summary. A supervisor sees only their own team; HR/admin must target an explicit teamId. Read-only. Requires OAuth scope reports:read.

team_records

Clock in the authenticated employee (start a work period). Requires OAuth scope clock:write.

clock_in

Clock out the authenticated employee (end the active work period). Requires OAuth scope clock:write.

clock_out

ADMIN ONLY. Generate a 6-digit kiosk PIN for each of up to 200 existing, active employees and return each PIN in clear ONCE (only a hash is stored: it can never be shown again). Employees that already have a PIN are skipped unless replaceExisting=true, which INVALIDATES their current PIN immediately — confirm with the user first. Use it for employees created before an import, or for import_employees rows that came back with pinError. Write the PINs where the user keeps them (e.g. their spreadsheet) and do not repeat them in the chat. Requires OAuth scope setup:write.

assign_kiosk_pins

ADMIN ONLY. Returns the mandatory step-by-step protocol for migrating historical clock records and absences from another time-tracking system into Cleverfy. CALL THIS FIRST, before import_time_entries or import_absences, whenever the user wants to migrate or import history from another vendor, and follow it to the letter: it starts by finding out which system and what the export files look like (ask for a sample), then how to match people safely, the row format, dry-run and reconciliation, confirmation, batching and undo. Call it again with `source` set once you know the system (e.g. "factorial", "sesame"): known systems come with their file quirks. Read-only. Requires OAuth scope import:write.

get_migration_guide

An employee's legal overtime (netted per month or flexible-bucket period, as in the hours report: a long day alone is not overtime; work on a day off counts from that day once the company declared it) over all recorded dates (not only this year; compensations take the oldest pending hours first): worked, compensated with rest and pending hours, whether the company allows compensating with rest, the rest ratio, the default hours per day, the buckets of earned days that can receive the days (only those: paid days off given in exchange for work; if there is none, an administrator has to create or mark one — never offer another policy) (policies[]; use their id in compensate_overtime), the days off worked still pending (day_off_dates, with the usual workday of each; only days off: hours clocked on an absence day count as overtime but are compensated by hours, at the general factor, never with days; the company compensates the days off with days from the employee file, not from here) and the latest compensations (history[]: id, kind hours|days|settled, work_date, closed_as rectified|kept, allocations with their tramos, days granted/available/reserved/used, can_revert, can_rectify, can_keep, closed_before (hours, days and tramos a rectification or a keep found), recharged_requests (the absences a revert charged again)). Each history row and each of its allocations carries tracking: whether its rest is tracked (untracked_reason not_earned_bucket for hours in a bag that is not a bucket of earned days), hours covered (rested), scheduled, requested and unscheduled, counts_for_limit_hours, limit_deadline (four months after the day worked: rest up to it takes the hours out of the cap, Art. 35.2), the nearest deadline (the company's, for the tracking and its notices) and whether it expired, marks (out_of_deadline with the hours not rested and those pending approval; with_difference: dates whose jornada was shorter, so they rested only that jornada's hours, dates the clocking took, or dates that were already another absence such as a vacation and rested nothing) and rest_before_work; each allocation also its pairs with the rest. limit says this year against the cap: realized, compensated, counted, recounted (compensated hours not rested within four months that count again) and the limit. Compensated hours in buckets of earned days stop counting when compensated and count again if they are not rested within four months of the day worked, whatever the company's deadline; those in other bags keep counting. not_compensable lists what the same history has that is not overtime and is never compensated as such: complementary_hours (a part-time contract: those its pact or declared voluntary hours cover; null when no day of it could be computed), uncovered_hours (over a part-time contract without a pact nor declared voluntary hours: pending qualification, not complementary; the law does not say whether they could be rested), split_pending_hours (over a part-time contract, how much the pact covers still unknown) and difference_hours (the difference over the schedule of senior management). HR/admins only. Read-only. Requires OAuth scope absences:read.

get_overtime_compensation

Starts a break (pausa) on the authenticated employee active time entry. The break type is the USER's choice and is legally meaningful — do NOT guess or default it. If the user has not explicitly stated which type of break, FIRST call list_break_types to fetch this tenant's available break types, present them to the user, and ask which one; then pass the chosen `code` as breakType. Requires an active clock-in. Requires OAuth scope clock:write.

start_break

ADMIN ONLY. SENDS EMAILS. Invite up to 200 existing employees (e.g. the kiosk employees just created with import_employees) to create their account in the Cleverfy app: each one receives an invitation email linked to their employee record, so accepting it takes no new seat and keeps their kiosk PIN. Uses the email on the employee record unless the row gives another, and keeps the role the employee already has unless the row gives one. ALWAYS call first with dryRun=true (default) and show the user who would get an email and who is skipped and why (no email, already has an account, email of another person, invitation already pending); only after the user explicitly approves sending emails call again with dryRun=false. A pending or expired invitation is only re-sent with resendPending=true, and only exactly as it was created: a row asking for another email or role is refused. Requires OAuth scope setup:write.

invite_employees

THE tool for the caller's OWN current clock status. Answers first-person questions like "¿estoy fichado?", "¿cuál es mi estado de fichaje?", "¿he fichado (hoy)?", "mi entrada/fichaje activo", "¿estoy en pausa?", "¿a qué hora entré/empecé?". Returns the caller's CURRENT open (uncompleted) time entry — which may have started on a PREVIOUS day and still be running — including status (working / on break / clocked out), clock-in time, minutes worked and whether they can start a break or clock out; returns clocked_out only when there is genuinely no open entry. Do NOT use whos_in for the caller's own status. Read-only. Requires OAuth scope clock:read.

get_active_entry

Returns the authenticated employee's own monthly worked-hours TOTALS (total hours, number of entries, on-site vs remote split, daily totals) for a given year/month (defaults to the current month). Use for aggregate "¿cuántas horas llevo este mes?" reporting. NOT for the caller's current/live clock status — for "¿estoy fichado?" or the active entry use get_active_entry. Self-service and read-only — always scoped to the caller. Requires OAuth scope reports:read.

my_hours_summary

Returns the authenticated employee own absence requests and their vacation/absence balance for a year. Each request has kind (days|hours); an hourly one has duration_minutes on its date (no start/end time), balance_days it charges, and once approved a result: credited_minutes / non_credited_minutes as work time (null = not known yet, with depends_on; 0 = known zero), never the same figure as the balance. Read-only. Requires OAuth scope absences:read.

my_absences

Returns the authenticated employee's own PAST time entries (a historical list/log), optionally filtered by a date range. Use it to review previous shifts or to find the timeEntryId and current times to pass to request_time_correction. NOT for the caller's current/live clock status — for "¿estoy fichado?" or the active entry use get_active_entry. Read-only. Requires OAuth scope clock:read.

my_time_entries

Real-time dashboard for a team today: per-employee status (working, on break, completed, not started), anomaly flags, aggregate counts and each day's hours within/over the schedule (extraordinary_hours here is today's excess over the schedule, not legal overtime: that is netted per reference period (the month, or the flexible bucket's period), see team_hours_summary). Its complementary_hours is that day's excess of a part-time person, not the legal figure: it may be complementary, over the contract without a pact or with the split pending, and the person may have 0 complementary hours in the period; the figures of the period are in team_hours_summary. Admins/HR target any team (teamId required); a supervisor always sees only their own team. Read-only. Requires OAuth scope presence:read.

team_dashboard

Team/presence overview: who ELSE is currently clocked in right now (working on-site/remote, on break, on leave), scoped to the caller's visibility (admins see the whole organization). Use for questions about OTHERS or the team like "¿quién está fichado?", "¿quién hay en la oficina?", "¿quién está trabajando ahora?". NOT for the caller's own clock status ("¿estoy fichado?", "mi fichaje activo") — use get_active_entry for that. Read-only. Requires OAuth scope presence:read.

whos_in

Reject a pending absence request by id, with a mandatory reason (a pending request never reached the hours count: nothing to confirm; its reserved balance is released). The rejection reason must come from the user — ask for it, do not fabricate. Only who may decide its current level: an approver of that level (the people designated, their delegates, HR on an HR level), whatever their role, or an admin/owner; anybody else gets NOT_YOUR_APPROVAL. Requires OAuth scope absences:approve.

reject_absence

Reject an employee time-entry correction request by id, with a mandatory reason. The rejection reason must come from the user — ask for it, do not fabricate. Admin/HR only. Requires OAuth scope modifications:write.

reject_modification

Reject a pending retrospective time-entry request by id, with a mandatory reason. The rejection reason must come from the user — ask for it, do not fabricate. Admin/HR only. Requires OAuth scope modifications:write.

reject_retrospective_entry

Summary of worked hours by employee and by department over a date range (defaults to the current month). Admins/HR see the whole organisation; a supervisor sees only their own team. overtime_hours is the legal overtime (netted per month or flexible-bucket period, as in the hours report). complementary_hours, uncovered_hours and split_pending_hours (part-time contracts) and difference_hours (senior management) are not overtime. complementary_hours are only those the pact or declared voluntary hours cover; uncovered_hours are over the contract without a pact nor declared voluntary hours: pending qualification, never call them complementary nor overtime (the law does not say what they are; they must be paid and the company decides how with its adviser); split_pending_hours are over the contract with how much the pact covers still unknown (voluntary hours to reassign, a pact that cannot be spread or days not computed). All three are what was computed: if uncomputable is not none, some day had no base to classify its hours (uncomputable_hours were registered on them) and the figure is not the whole period; null when no day could be. provisional means the figures can change once the schedule is complete. The totals add what was computed; incomplete and uncomputable_employees say how many people have days not computed. Read-only. Requires OAuth scope reports:read.

team_hours_summary

Absence/vacation balance for a target employee (entitled, available, used, reserved, plus a per-policy breakdown), to check entitlement before approving leave. HR/admins only. Read-only. Requires OAuth scope absences:read.

get_employee_balance

Request an absence/vacation for the authenticated employee (kicks off approval). absenceTypeId and policyId come from list_absence_types; dates are YYYY-MM-DD. For an absence BY HOURS pass durationMinutes on a single date: it is a duration, never a start/end time nor a day; the balance in days it charges and the minutes that count as work are separate figures (preview shows both). Call with preview=true first. If it would be approved at once and moves the hours count, it must be confirmed: show the user the effects and send their fingerprint as effectsFingerprint; never send one the user did not see. Requires OAuth scope absences:write.

request_absence

Request a correction to one of the authenticated employee time entries (queues for company approval) — works for past/completed entries AND for the still-open ACTIVE entry. Provide the timeEntryId (from my_time_entries, or get_active_entry for the active one) and the corrected clock-in as ISO 8601 with a timezone offset, plus a reason. The corrected clock-out is OPTIONAL: omit it to correct ONLY the clock-in of an ACTIVE entry that has not been clocked out yet — never fabricate a clock-out for an open entry. The reason must come from the user — ask for it, do not fabricate. Optionally pass `breaks` to also set the day's breaks (e.g. a lunch break): this REPLACES the entry's current breaks, so send the FULL desired set — if the day already has breaks, FIRST read them with my_time_entries and re-include each one (with its breakId) or it will be removed. Each break needs startTime, endTime and a policyCode from list_break_types; include a breakId (from my_time_entries) to keep an existing break, omit it for a new one. Requires OAuth scope modifications:write.

request_time_correction

Request creation of a time entry for a PAST day that has no record yet (e.g. "I worked last Tuesday 09:00-17:00 but forgot to clock in"). Queues for company approval. Provide date (YYYY-MM-DD), clockInTime and clockOutTime (ISO 8601 with a timezone offset), workMode ("on_site" or "remote") and a reason. The reason must come from the user — ask for it, do not fabricate. Optionally pass `breaks` (each NEW: startTime, endTime, policyCode from list_break_types; no breakId). For TODAY use clock_in; to fix an EXISTING entry use request_time_correction. Requires OAuth scope modifications:write.

request_retrospective_entry

Ends the open break (pausa) on the authenticated employee active time entry — automatically finds the break in progress. Requires OAuth scope clock:write.

end_break

Returns the available absence types and their policies (each policy carries its absence_type_id, and its work_credit: the rule in force deciding how many minutes of an absence BY HOURS count as work time, full/none/capped with cap per person and type, across policies, in its calendar window). Use this to obtain the absence_type_id and policy_id needed by request_absence. Read-only. Requires OAuth scope absences:read.

list_absence_types

Returns this tenant's available break types (pausas) — each with its code, name, and whether it requires a comment. Call this BEFORE start_break so the user can choose a type (never assume one): use the returned `code` as the breakType for start_break, or as the policyCode in request_time_correction. Read-only. Requires OAuth scope clock:read.

list_break_types

ADMIN ONLY. List the organization's work centers with their id, name, code, city, type and whether they are active, plus how many active employees each has. Use it to map the work center codes or names of a spreadsheet to ids BEFORE calling import_employees — match by code or name and ask the user when a match is ambiguous or missing; never invent ids. Centers that do not exist yet can be created with create_work_centers. Active centers only unless includeInactive=true. Read-only. Requires OAuth scope setup:write.

list_work_centers

Approve a pending employee time-entry correction by id, as the company/HR reviewer. Admin/HR only. Requires OAuth scope modifications:write.