> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stampfactory.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Stempelung

> Documented exception to the `data`-envelope standard (ADR 0005): the
payload stays flat for the mobile clients. `early` is only present when
the clock-in happened before the rostered start (milliseconds early).



## OpenAPI

````yaml POST /mobile
openapi: 3.1.0
info:
  title: Stampfactory API
  version: 1.0.0
  description: >-
    REST API für die Stampfactory Zeiterfassungs- und
    Personalverwaltungsplattform.


    ## Basis-URL


    Jeder Mandant hat eine eigene Subdomain: `https://{tenant}.stamp.eu/rest/…`.

    Custom Domains werden unterstützt; der Pfad-Präfix ist immer `/rest`.

    Authentifizierung über `POST /rest/login` (Bearer-Token, Laravel Sanctum).


    ## Datenformate (verbindlich, ADR 0005)


    | Typ | Format | Beispiel |

    |---|---|---|

    | Dauer (Anzeige) | String `HH:MM:SS.mmm`, Feldname ohne Suffix |
    `"08:00:00.000"` |

    | Dauer (Rohwert) | Integer Millisekunden, Feldname mit Suffix `_ms` |
    `28800000` |

    | Datum | ISO 8601 (`YYYY-MM-DD`) | `"2026-07-25"` |

    | Fachliche Zeitstempel (Stempelungen, Korrekturen) | ISO 8601 in
    Mandanten-Zeitzone | `"2026-07-25T08:00:00+02:00"` |

    | Technische Metadaten (`created_at`, `updated_at`) | ISO 8601 UTC |
    `"2026-07-25T06:00:00+00:00"` |

    | IDs | UUID bzw. TypeID-String | `"9d3f…"` |

    | Arbeitszeit-Flags | Integer-Bitmaske (`flags`), Bits siehe
    `WorkingTimeFlag` | `512` = Feiertag |

    | Monats-Perioden | `YYYY-MM` | `"2026-07"` |


    ## Responses


    Erfolgs-Responses liefern die fachliche Payload unter `data`

    (dokumentierte Ausnahmen: `POST /rest/terminal/{code}` und `/rest/mobile`).

    Listen sind, wo paginiert, im Laravel-Paginator-Format (`data` + `links` +
    `meta`).


    ## Fehlerformat


    Alle Fehler (4xx/5xx) folgen einem einheitlichen Envelope:


    ```json

    {
      "request_id": "…",
      "timestamp": "2026-07-25T06:00:00Z",
      "message": "Menschlich lesbare Meldung",
      "field_errors": { "feld": ["Meldung"] },
      "errors": [{ "title": "…", "detail": "…", "type": "https://docs.stampfactory.eu/errors#…", "_meta": { } }]
    }

    ```


    `field_errors` erscheint bei Validierungsfehlern (422). Endpoint-spezifische

    Zusatzdaten (z. B. `warnings`, `earliest`, `code`) stehen kanonisch in

    `errors[0]._meta`; Top-Level-Duplikate sind eine
    Übergangs-Kompatibilitätsschicht.

    Die `type`-URLs verlinken auf die Fehlerdokumentation.
servers:
  - url: https://{tenant}.stamp.eu/rest
    description: Production
    variables:
      tenant:
        default: demo
        description: Subdomain des Mandanten
security:
  - http: []
paths:
  /mobile:
    post:
      tags:
        - Stempelungen
      summary: POST /rest/mobile — Mobile clock-in/out (authenticated)
      description: |-
        Documented exception to the `data`-envelope standard (ADR 0005): the
        payload stays flat for the mobile clients. `early` is only present when
        the clock-in happened before the rostered start (milliseconds early).
      operationId: tenant.mobile.clock
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                latitude:
                  type:
                    - number
                    - 'null'
                  minimum: -90
                  maximum: 90
                longitude:
                  type:
                    - number
                    - 'null'
                  minimum: -180
                  maximum: 180
                accuracy:
                  type:
                    - number
                    - 'null'
                  minimum: 0
                queued_at:
                  type:
                    - string
                    - 'null'
                  format: date-time
                comment:
                  type:
                    - string
                    - 'null'
                  maxLength: 1000
                metadata:
                  type: object
                  properties:
                    platform:
                      type:
                        - string
                        - 'null'
                      enum:
                        - ios
                        - android
                        - web
                        - desktop
                    app_version:
                      type:
                        - string
                        - 'null'
                      maxLength: 20
                    device_model:
                      type:
                        - string
                        - 'null'
                      maxLength: 100
                    os_version:
                      type:
                        - string
                        - 'null'
                      maxLength: 50
      responses:
        '201':
          description: Stempelung erfasst
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  state:
                    type: string
                  timestamp:
                    type:
                      - string
                      - 'null'
                  location:
                    type: boolean
                  early:
                    type: integer
                  target_duration_seconds:
                    type: integer
                  weekly_target_seconds:
                    type: integer
                  weekly_seconds:
                    type: integer
                  today_work_seconds:
                    type: integer
                  today_pause_seconds:
                    type: integer
                  overtime_account_seconds:
                    type: integer
                  overtime_month_seconds:
                    type: integer
                  company_name:
                    type: string
                required:
                  - id
                  - state
                  - timestamp
                  - location
                  - target_duration_seconds
                  - weekly_target_seconds
                  - weekly_seconds
                  - today_work_seconds
                  - today_pause_seconds
                  - overtime_account_seconds
                  - overtime_month_seconds
                  - company_name
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          description: |-
            An error

            An error
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      message:
                        type: string
                        description: Error overview.
                        example: Keine Berechtigung für mobile Stempelung.
                    required:
                      - message
                  - type: object
                    properties:
                      message:
                        type: string
                        description: Error overview.
                        example: No employee record.
                    required:
                      - message
        '422':
          $ref: '#/components/responses/ValidationException'
components:
  responses:
    AuthenticationException:
      description: Unauthenticated
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error overview.
            required:
              - message
    ValidationException:
      description: Validation error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Errors overview.
              errors:
                type: object
                description: A detailed description of each field that failed validation.
                additionalProperties:
                  type: array
                  items:
                    type: string
            required:
              - message
              - errors
  securitySchemes:
    http:
      type: http
      description: Bearer-Token, erhalten über den Login-Endpunkt (POST /rest/login).
      scheme: bearer

````