{"openapi":"3.1.0","info":{"title":"Regitap API","version":"1.0.0","description":"Time tracking (registro de jornada, art. 34.9 Estatuto de los Trabajadores, Spain), vacations and daily tasks. One key per company acts as its admin. Rules the API can't bypass: the record is never deleted or edited (a correction is a request someone approves, with both names; the original stays), the server sets the time, location only at the tap, a company may cap its active workers (409 worker_cap_reached: stop and tell a human). PUT is idempotent and only changes the fields sent. Spanish guide: https://www.regitap.com/developers/api"},"servers":[{"url":"https://www.regitap.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"rgt_… key from Regitap → Ajustes → API."}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"webhooks":{"worker.reminder":{"post":{"summary":"Not clocked in at the planned start, or still working at the planned end (data.kind missing_start / missing_end). Show data.message to the person.","description":"Headers: Regitap-Event, Regitap-Delivery (id; ignore repeats) and Regitap-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with REGITAP_WEBHOOK_SECRET>. Reject if it doesn't match or t is older than 5 minutes. Answer 2xx within 10 s; failures are retried for about 2 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"worker.reminder"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"name":{"type":"string"}}},"message":{"type":["object","null"],"description":"For the person: title and body in Spanish, ready to show.","properties":{"title":{"type":"string"},"body":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Received"}}}},"correction.decided":{"post":{"summary":"A correction of theirs was decided, or someone corrected their record (requestedByWorker: false). Show data.message.","description":"Headers: Regitap-Event, Regitap-Delivery (id; ignore repeats) and Regitap-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with REGITAP_WEBHOOK_SECRET>. Reject if it doesn't match or t is older than 5 minutes. Answer 2xx within 10 s; failures are retried for about 2 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"correction.decided"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"name":{"type":"string"}}},"message":{"type":["object","null"],"description":"For the person: title and body in Spanish, ready to show.","properties":{"title":{"type":"string"},"body":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Received"}}}},"leave.decided":{"post":{"summary":"A leave request was approved or rejected. Show data.message.","description":"Headers: Regitap-Event, Regitap-Delivery (id; ignore repeats) and Regitap-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with REGITAP_WEBHOOK_SECRET>. Reject if it doesn't match or t is older than 5 minutes. Answer 2xx within 10 s; failures are retried for about 2 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"leave.decided"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"name":{"type":"string"}}},"message":{"type":["object","null"],"description":"For the person: title and body in Spanish, ready to show.","properties":{"title":{"type":"string"},"body":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Received"}}}},"summary.ready":{"post":{"summary":"Their monthly summary is ready (they see it through a record link). Show data.message.","description":"Headers: Regitap-Event, Regitap-Delivery (id; ignore repeats) and Regitap-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with REGITAP_WEBHOOK_SECRET>. Reject if it doesn't match or t is older than 5 minutes. Answer 2xx within 10 s; failures are retried for about 2 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"summary.ready"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"name":{"type":"string"}}},"message":{"type":["object","null"],"description":"For the person: title and body in Spanish, ready to show.","properties":{"title":{"type":"string"},"body":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Received"}}}},"absence.changed":{"post":{"summary":"An absence was added, approved or cancelled in Regitap (not the ones you sent). For your planning.","description":"Headers: Regitap-Event, Regitap-Delivery (id; ignore repeats) and Regitap-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with REGITAP_WEBHOOK_SECRET>. Reject if it doesn't match or t is older than 5 minutes. Answer 2xx within 10 s; failures are retried for about 2 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"absence.changed"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"name":{"type":"string"}}},"message":{"type":["object","null"],"description":"For the person: title and body in Spanish, ready to show.","properties":{"title":{"type":"string"},"body":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Received"}}}},"clock.recorded":{"post":{"summary":"Every clock-in, from wherever.","description":"Headers: Regitap-Event, Regitap-Delivery (id; ignore repeats) and Regitap-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with REGITAP_WEBHOOK_SECRET>. Reject if it doesn't match or t is older than 5 minutes. Answer 2xx within 10 s; failures are retried for about 2 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"clock.recorded"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"name":{"type":"string"}}},"message":{"type":["object","null"],"description":"For the person: title and body in Spanish, ready to show.","properties":{"title":{"type":"string"},"body":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Received"}}}},"task.started":{"post":{"summary":"A task started.","description":"Headers: Regitap-Event, Regitap-Delivery (id; ignore repeats) and Regitap-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with REGITAP_WEBHOOK_SECRET>. Reject if it doesn't match or t is older than 5 minutes. Answer 2xx within 10 s; failures are retried for about 2 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"task.started"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"name":{"type":"string"}}},"message":{"type":["object","null"],"description":"For the person: title and body in Spanish, ready to show.","properties":{"title":{"type":"string"},"body":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Received"}}}},"task.ended":{"post":{"summary":"A task ended (reason: ended, next_task when another one started, day_end when the workday ended).","description":"Headers: Regitap-Event, Regitap-Delivery (id; ignore repeats) and Regitap-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with REGITAP_WEBHOOK_SECRET>. Reject if it doesn't match or t is older than 5 minutes. Answer 2xx within 10 s; failures are retried for about 2 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"task.ended"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"name":{"type":"string"}}},"message":{"type":["object","null"],"description":"For the person: title and body in Spanish, ready to show.","properties":{"title":{"type":"string"},"body":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Received"}}}}},"paths":{"/workers":{"get":{"summary":"List workers (former ones too, with endDate).","responses":{"200":{"description":"Workers","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/workers/{ref}":{"put":{"summary":"Create or update a worker with what you have; only fields sent change. The name is enough to create; the rest can be completed in Regitap. Links someone already there by email or phone.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"idType":{"enum":["DNI","NIE","PASSPORT"]},"idNumber":{"type":"string"},"phone":{"type":"string","description":"E.164 (Spanish numbers are normalised)."},"email":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":["string","null"],"format":"date"},"contractType":{"type":"string"},"weeklyHours":{"type":["number","string"]},"timezone":{"type":["string","null"]},"team":{"type":["string","null"],"description":"Team ref (null = no team)."},"custom":{"type":"object","additionalProperties":{"type":"string"},"description":"Company custom fields by label."},"schedule":{"type":"object","required":["validFrom","week"],"properties":{"validFrom":{"type":"string","format":"date"},"week":{"type":"array","minItems":7,"maxItems":7,"items":{"type":"object","required":["ranges","breakMinutes","breakPaid"],"properties":{"ranges":{"type":"array","items":{"type":"string","pattern":"^\\d{2}:\\d{2}-\\d{2}:\\d{2}$"}},"breakMinutes":{"type":"integer"},"breakPaid":{"type":"boolean"}}},"description":"Monday to Sunday."}}}}}}}},"responses":{"200":{"description":"Updated or linked","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"id":{"type":"string"},"created":{"type":"boolean"},"linked":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/workers/{ref}/end":{"post":{"summary":"Baja (end of employment) from a date. Nothing is deleted.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["endDate"],"properties":{"endDate":{"type":"string","format":"date"},"reason":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Ended","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/workers/{ref}/status":{"get":{"summary":"Workday state now (OFF, WORKING, PAUSED), since when, seconds worked today, open past day, today's absence and tasks.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/workers/{ref}/clock":{"post":{"summary":"Clock in on behalf of the worker (their tap in your app). Ending the workday ends the task in progress.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["clientId"],"properties":{"clientId":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"Unique per tap: retrying with the same one returns the first result."},"location":{"description":"Where the phone was at the moment of the tap. Never tracked otherwise.","oneOf":[{"type":"object","required":["status","lat","lng"],"properties":{"status":{"const":"ok"},"lat":{"type":"number"},"lng":{"type":"number"},"accuracyM":{"type":["number","null"]}}},{"type":"object","required":["status"],"properties":{"status":{"enum":["denied","unavailable","not_requested"]}}}]},"offline":{"type":"boolean","default":false,"description":"The phone had no connection: deviceAt is used, flagged as offline."},"deviceAt":{"type":["string","null"],"format":"date-time","description":"The phone's time of the tap (only with offline: true; never in the future)."}}},{"type":"object","required":["action"],"properties":{"action":{"enum":["DAY_START","PAUSE_START","PAUSE_END","DAY_END"]}}}]}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"$ref":"#/components/responses/Error"}}}},"/workers/{ref}/events":{"get":{"summary":"Clock-ins that count (corrections applied), with their id: what a correction targets.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/corrections":{"get":{"summary":"Correction requests, newest first (status=pending by default, or all), with who asked and who decided.","parameters":[{"name":"status","in":"query","schema":{"enum":["pending","all"]}}],"responses":{"200":{"description":"Corrections","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Ask for a correction on behalf of a worker. Never approved when made: it waits for POST /corrections/{id}/decide (or a manager in Regitap). The original record stays.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["worker","kind","reason","requestedBy"],"properties":{"worker":{"type":"string","description":"Worker ref."},"kind":{"enum":["add","change","void"]},"eventId":{"type":["string","null"],"description":"change/void: the event to correct."},"action":{"type":["string","null"],"enum":["DAY_START","PAUSE_START","PAUSE_END","DAY_END",null]},"proposedAt":{"type":["string","null"],"format":"date-time"},"reason":{"type":"string","minLength":3,"maxLength":500},"requestedBy":{"type":"string","description":"Name of who asks (kept with the request)."}}}}}},"responses":{"201":{"description":"Requested","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"const":"PENDING"}}}}}},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/corrections/{id}/decide":{"post":{"summary":"Approve or reject on behalf of who decides. Approving adds the corrected event.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["approve","decidedBy"],"properties":{"approve":{"type":"boolean"},"note":{"type":["string","null"]},"decidedBy":{"type":"string"},"supervisor":{"type":["string","null"],"description":"Worker ref of who decides: Regitap checks they supervise that worker's team (403 not_supervisor otherwise). Omit for an admin's decision."}}}}}},"responses":{"200":{"description":"Decided","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/teams":{"get":{"summary":"Teams with their supervisors and members (worker refs).","responses":{"200":{"description":"Teams","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/teams/{ref}":{"put":{"summary":"Create or update a team. A worker is in one team: listing them in members moves them. Supervisors approve their members' corrections and vacations; a supervisor's go to an admin. Omit members/supervisors to keep them.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"supervisors":{"type":"array","items":{"type":"string"}},"members":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Archive a team (its members stay, without team).","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/places/{ref}":{"put":{"summary":"Create or update a place (a client's address, a site, an office) with a radius: clock-ins and tasks inside count as at the place.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","address","lat","lng"],"properties":{"name":{"type":"string"},"address":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"},"radiusM":{"type":["integer","null"]},"isCenter":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Archive a place.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/tasks":{"get":{"summary":"Tasks of a day.","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"worker","in":"query","schema":{"type":"string"},"description":"Worker ref."}],"responses":{"200":{"description":"Tasks","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"type":["string","null"]},"worker":{"type":["string","null"]},"date":{"type":"string","format":"date"},"title":{"type":"string"},"address":{"type":["string","null"]},"plannedStart":{"type":["string","null"]},"plannedMinutes":{"type":["integer","null"]},"notes":{"type":["string","null"]},"status":{"enum":["PENDING","STARTED","DONE","CANCELLED"]},"startedAt":{"type":["string","null"],"format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"}}}}}}}}}}}},"/tasks/{ref}":{"get":{"summary":"One task.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"responses":{"200":{"description":"Task","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"type":["string","null"]},"worker":{"type":["string","null"]},"date":{"type":"string","format":"date"},"title":{"type":"string"},"address":{"type":["string","null"]},"plannedStart":{"type":["string","null"]},"plannedMinutes":{"type":["integer","null"]},"notes":{"type":["string","null"]},"status":{"enum":["PENDING","STARTED","DONE","CANCELLED"]},"startedAt":{"type":["string","null"],"format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"}}}}}},"404":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Create or update a task (a job of one worker on one day). Starting the first one starts the workday; between tasks the workday goes on.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["worker","date","title"],"properties":{"worker":{"type":"string","description":"Worker ref."},"date":{"type":"string","format":"date"},"title":{"type":"string"},"address":{"type":["string","null"]},"place":{"type":["string","null"],"description":"Place ref."},"plannedStart":{"type":["string","null"],"description":"HH:MM"},"plannedMinutes":{"type":["integer","null"]},"notes":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"type":["string","null"]},"worker":{"type":["string","null"]},"date":{"type":"string","format":"date"},"title":{"type":"string"},"address":{"type":["string","null"]},"plannedStart":{"type":["string","null"]},"plannedMinutes":{"type":["integer","null"]},"notes":{"type":["string","null"]},"status":{"enum":["PENDING","STARTED","DONE","CANCELLED"]},"startedAt":{"type":["string","null"],"format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"type":["string","null"]},"worker":{"type":["string","null"]},"date":{"type":"string","format":"date"},"title":{"type":"string"},"address":{"type":["string","null"]},"plannedStart":{"type":["string","null"]},"plannedMinutes":{"type":["integer","null"]},"notes":{"type":["string","null"]},"status":{"enum":["PENDING","STARTED","DONE","CANCELLED"]},"startedAt":{"type":["string","null"],"format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"}}}}}},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Cancel a task that hasn't started (409 started otherwise).","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"type":["string","null"]},"worker":{"type":["string","null"]},"date":{"type":"string","format":"date"},"title":{"type":"string"},"address":{"type":["string","null"]},"plannedStart":{"type":["string","null"]},"plannedMinutes":{"type":["integer","null"]},"notes":{"type":["string","null"]},"status":{"enum":["PENDING","STARTED","DONE","CANCELLED"]},"startedAt":{"type":["string","null"],"format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"}}}}}},"409":{"$ref":"#/components/responses/Error"}}}},"/absences":{"get":{"summary":"Absences touching [from, to] (at most a year), wherever they were made: yours (ref), added in Regitap or approved requests (ref null). Cancelled ones with cancelled: true.","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"worker","in":"query","schema":{"type":"string"},"description":"Worker ref."}],"responses":{"200":{"description":"Absences","content":{"application/json":{"schema":{"type":"object","properties":{"absences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"worker":{"type":["string","null"]},"kind":{"enum":["vacation","personal_day","sick_leave","paid_leave","unpaid_leave","other"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"note":{"type":["string","null"]},"cancelled":{"type":"boolean"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"}}}},"/absences/{ref}":{"put":{"summary":"Create or update a day off, vacation or other absence (both dates included). Those days have no planned hours and no reminders; vacation and personal days use up the year's days.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["worker","kind","from","to"],"properties":{"worker":{"type":"string","description":"Worker ref."},"kind":{"enum":["vacation","personal_day","sick_leave","paid_leave","unpaid_leave","other"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"note":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"worker":{"type":["string","null"]},"kind":{"enum":["vacation","personal_day","sick_leave","paid_leave","unpaid_leave","other"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"note":{"type":["string","null"]},"cancelled":{"type":"boolean"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"worker":{"type":["string","null"]},"kind":{"enum":["vacation","personal_day","sick_leave","paid_leave","unpaid_leave","other"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"note":{"type":["string","null"]},"cancelled":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Cancel it (not deleted). If it came from an approved request, the request is cancelled and the days given back.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":["string","null"]},"worker":{"type":["string","null"]},"kind":{"enum":["vacation","personal_day","sick_leave","paid_leave","unpaid_leave","other"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"note":{"type":["string","null"]},"cancelled":{"type":"boolean"}}}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/workers/{ref}/record-link":{"post":{"summary":"Only if workers clock in inside your software: a one-time link (10 minutes) for that person to see their own record, monthly summaries and leave, and ask for corrections and leave, for 1 hour, without a Regitap account. Open it for them at once; never store it or email it.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"responses":{"201":{"description":"Link","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/webhook":{"get":{"summary":"The company's webhook URL (null: none) and the events.","responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"summary":"Set or change the webhook URL (public https). Returns the signing secret: store it as REGITAP_WEBHOOK_SECRET. Changing the URL keeps the secret; rotateSecret: true makes a new one.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"rotateSecret":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"secret":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Stop sending.","responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/webhook/test":{"post":{"summary":"Send a ping now and get what your software answered.","responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"delivered":{"type":"boolean"},"status":{"type":["integer","null"]},"error":{"type":["string","null"]}}}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/tasks/{ref}/start":{"post":{"summary":"The worker starts the task (starts the workday if needed; ends any other task in progress).","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["clientId"],"properties":{"clientId":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"Unique per tap: retrying with the same one returns the first result."},"location":{"description":"Where the phone was at the moment of the tap. Never tracked otherwise.","oneOf":[{"type":"object","required":["status","lat","lng"],"properties":{"status":{"const":"ok"},"lat":{"type":"number"},"lng":{"type":"number"},"accuracyM":{"type":["number","null"]}}},{"type":"object","required":["status"],"properties":{"status":{"enum":["denied","unavailable","not_requested"]}}}]},"offline":{"type":"boolean","default":false,"description":"The phone had no connection: deviceAt is used, flagged as offline."},"deviceAt":{"type":["string","null"],"format":"date-time","description":"The phone's time of the tap (only with offline: true; never in the future)."}}}}}},"responses":{"200":{"description":"Started","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"outsidePlace":{"type":"boolean"}}}}}},"409":{"$ref":"#/components/responses/Error"}}}},"/tasks/{ref}/end":{"post":{"summary":"The worker ends the task. askEndDay: true = it was the last one today; ask the person whether the workday is over, never end it for them.","parameters":[{"name":"ref","in":"path","required":true,"description":"Your own id for this record (1-100 chars: A-Z a-z 0-9 . _ : -).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,100}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["clientId"],"properties":{"clientId":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"Unique per tap: retrying with the same one returns the first result."},"location":{"description":"Where the phone was at the moment of the tap. Never tracked otherwise.","oneOf":[{"type":"object","required":["status","lat","lng"],"properties":{"status":{"const":"ok"},"lat":{"type":"number"},"lng":{"type":"number"},"accuracyM":{"type":["number","null"]}}},{"type":"object","required":["status"],"properties":{"status":{"enum":["denied","unavailable","not_requested"]}}}]},"offline":{"type":"boolean","default":false,"description":"The phone had no connection: deviceAt is used, flagged as offline."},"deviceAt":{"type":["string","null"],"format":"date-time","description":"The phone's time of the tap (only with offline: true; never in the future)."}}}}}},"responses":{"200":{"description":"Ended","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"askEndDay":{"type":"boolean"}}}}}},"409":{"$ref":"#/components/responses/Error"}}}}}}