> ## 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.

# DATEV verbinden

> Returns the DATEV OAuth2 authorization URL.
The frontend redirects the user to this URL.

The connection data (Beraternummer, Mandantennummer, etc.) is stored in
cache until the callback processes it. The callback happens on the
central callback domain and redirects back to the tenant frontend.



## OpenAPI

````yaml GET /datev/connect
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:
  /datev/connect:
    get:
      tags:
        - Sonstiges
      summary: GET /rest/datev/connect
      description: |-
        Returns the DATEV OAuth2 authorization URL.
        The frontend redirects the user to this URL.

        The connection data (Beraternummer, Mandantennummer, etc.) is stored in
        cache until the callback processes it. The callback happens on the
        central callback domain and redirects back to the tenant frontend.
      operationId: tenant.datev.connect
      parameters:
        - name: berater_nummer
          in: query
          required: true
          schema:
            type: string
            maxLength: 20
        - name: mandanten_nummer
          in: query
          required: true
          schema:
            type: string
            maxLength: 20
        - name: target_system
          in: query
          required: true
          schema:
            type: string
            enum:
              - lug
              - lodas
        - name: notification_email
          in: query
          schema:
            type:
              - string
              - 'null'
            format: email
            maxLength: 255
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                  redirect_uri:
                    type: string
                required:
                  - url
                  - redirect_uri
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '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

````