## Add one stamp (Kommen, Pause, Pause beenden, Gehen) to a day (own, or the team's with responsibility or hr:time:manage)

`POST /api/hr/v1/time-stamps`

Module: HR · operationId: `applyTimeStamp` · Tag: Working time · Auth: access token (`Authorization: Bearer <accessToken>`)

HR fits the stamp into the recorded time: `in` and `break-end` open a segment, `break` and
`out` close the open segment (also one from the day before – night shift). `break` inside a
finished segment splits it, and a following `break-end` moves the rest of it; at the exact
end of a segment `break`/`out` switch it between Pause and Gehen. A stamp that does not fit
fails with `409` and the code `stamp_<reason>` (`stamp_already_open`, `stamp_inside_segment`,
`stamp_later_segment`, `stamp_no_break`, `stamp_no_open_segment`, `stamp_too_long`,
`stamp_unchanged`) and `field` (`time` or `kind`). Like manual entries, a `reason` is required
for other people's time and own days older than `selfEditDays`; closed months fail with
`409 period_closed`, overlaps with `409 overlap`, future times with `400`. Returns the
rebuilt day.

### Request body

`application/json` (required)

- `date` (string (date), required): Day of the stamp (YYYY-MM-DD)
- `kind` (string, required): in = Kommen, break = Pause, break-end = Pause beenden, out = Gehen (one of `in`, `break`, `break-end`, `out`)
- `time` (string, required): Local time HH:MM in the tenant's time zone
- `employeeId` (string): Empty or `me` for the caller
- `note` (string): Stored on the segment the stamp opens
- `reason` (string): Required for other people's time and for own days older than the tenant's `selfEditDays`

Example:

```json
{
  "date": "2026-11-17",
  "kind": "break",
  "reason": "Pause nachgetragen",
  "time": "12:00"
}
```

### Responses

- **200** The day after the stamp (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `absence` (object): The absence on the day, if any
  - `fraction` (number): Share of the day the absence covers (1 or 0.5)
  - `id` (string): Id of the absence
  - `status` (string): State of the absence
  - `typeId` (string): Id of the absence type
- `actual` (integer): Worked minutes
- `break` (integer): Break minutes
- `counted` (boolean): The day lies before today (tenant time zone) and counts in the totals and the time account. Today shows its live target, actual and credit but is not counted yet; later days show their target only
- `credit` (integer): Minutes absences count as worked
- `date` (string (date)): The day (YYYY-MM-DD)
- `delta` (integer): actual + credit − target, in minutes; 0 on days not counted (today and later)
- `entries` (array of TimeEntry): Time entries of the day
  - `autoEnded` (boolean): HR ended the segment at midnight because nobody clocked out (setting `autoEndAtMidnight`). It counts no working time until it is corrected; any change clears the mark.
  - `breakMinutes` (integer): Break inside the segment in minutes (manual entries)
  - `createdAt` (string (date-time)): When the time entry was created
  - `createdBy` (string): Who created the time entry (e-mail of the caller)
  - `employeeId` (string): Id of the employee
  - `end` (string (date-time)): Missing while running
  - `endedForBreak` (boolean): The segment was closed by starting a break
  - `id` (string): Id of the time entry
  - `note` (string): Note on the entry
  - `source` (string): clock: stamped, manual: entered by hand (one of `clock`, `manual`)
  - `start` (string (date-time)): Start of the segment
  - `updatedAt` (string (date-time)): When the time entry was last changed
  - `updatedBy` (string): Who last changed the time entry (e-mail of the caller)
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `holiday` (Holiday)
  - `custom` (boolean): A holiday of the tenant's own (omitted when false)
  - `date` (string (date)): Date (YYYY-MM-DD)
  - `fraction` (number): 1 for a full day, 0.5 for a half day (e.g. 24.12.) (one of `0.5`, `1`)
  - `name` (string): Name of the holiday
- `running` (boolean): A segment of the day is still open
- `target` (integer): Scheduled minutes (minus holidays and unpaid absences)
- `violations` (array of Violation): Working-time rule warnings (ArbZG); never blocking
  - `breakMinutes` (integer): Break that counts under §4 ArbZG: interruptions of 15 minutes or more plus booked breaks (break_6h, break_9h)
  - `code` (string): auto_ended is no ArbZG rule: a segment HR ended at midnight whose times need checking (one of `break_6h`, `break_9h`, `max_10h`, `rest_11h`, `sunday_holiday`, `open_entry`, `auto_ended`)
  - `entryId` (string): The open or auto-ended entry (open_entry, auto_ended)
  - `excessMinutes` (integer): Worked time above the maximum (max_10h)
  - `message` (string): Human-readable text of the warning (German)
  - `requiredMinutes` (integer): Limit of the rule: required break (30/45), maximum worked time (600) or minimum rest (660)
  - `restMinutes` (integer): Rest since the previous work (rest_11h)
  - `since` (string (date-time)): End of the previous work (rest_11h) or start of the open or auto-ended entry (open_entry, auto_ended)
  - `workedMinutes` (integer): Worked time of the day (break_6h, break_9h, max_10h, sunday_holiday)

Example 200 answer:

```json
{
  "actual": 480,
  "break": 30,
  "counted": true,
  "credit": 0,
  "date": "2026-11-17",
  "delta": 0,
  "entries": [
    {
      "autoEnded": false,
      "breakMinutes": 0,
      "createdAt": "2026-11-18T07:02:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "end": "2026-11-17T11:00:00Z",
      "endedForBreak": true,
      "id": "1e3a5c7e-9a1c-4e3a-8c5e-9a1c3e5a7c40",
      "source": "manual",
      "start": "2026-11-17T06:30:00Z",
      "updatedAt": "2026-11-18T07:02:00Z",
      "updatedBy": "sophie.huber@muster-it.example",
      "version": 1
    },
    {
      "autoEnded": false,
      "breakMinutes": 0,
      "createdAt": "2026-11-18T07:03:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "end": "2026-11-17T15:00:00Z",
      "endedForBreak": false,
      "id": "3c5e7a9c-1e3a-4c5e-9a7c-1e3a5c7e9a41",
      "source": "manual",
      "start": "2026-11-17T11:30:00Z",
      "updatedAt": "2026-11-18T07:03:00Z",
      "updatedBy": "sophie.huber@muster-it.example",
      "version": 1
    }
  ],
  "running": false,
  "target": 480,
  "violations": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/time-stamps' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"date":"2026-11-17","kind":"break","reason":"Pause nachgetragen","time":"12:00"}'
```
