openapi: 3.0.0
info:
  title: TANSS API
  version: 10.15.0
  contact:
    email: support@tanss.de
  license:
    name: Proprietary
    url: https://tanss.de
  x-logo:
    url: https://api-doc.tanss.de/logo.svg
    altText: TANSS
  description: |
    > The complete reference for integrating with **TANSS** — tickets, time tracking,
    > device management, and customer operations through a single REST surface.

    | Base URL  | `https://<your-tanss-host>`                                                 |
    |-----------|------------------------------------------------------------------------------|
    | Auth      | `POST /api/v1/login` → send `apiToken: Bearer <jwt>` header on every request |
    | Version   | **10.15.0**                                                                  |
    | Envelope  | All responses follow `{ meta, content }`                                     |

    #### Reading this reference

    The sidebar is grouped into eleven modules. Each operation documents its path
    parameters, request body, response shape, and error codes — with copy-paste
    `curl` examples and an in-browser HTTP client.

    #### Authentication in 30 seconds

    ```bash
    # 1. Log in
    curl -X POST https://<your-tanss-host>/api/v1/login \
      -H 'Content-Type: application/json' \
      -d '{"username": "…", "password": "…"}'

    # 2. Reuse content.apiKey (already includes the "Bearer " prefix)
    curl https://<your-tanss-host>/api/v1/tickets/own \
      -H "apiToken: Bearer eyJ…"
    ```

    The JWT is valid for ~4 hours; a 2-minute idle timeout applies on top of that.
    Refresh by re-calling `POST /api/v1/login`, or by exchanging the returned
    `content.refresh` token at `POST /api/v1/login/refresh`.
servers:
  - url: https://{host}
    description: TANSS host
    variables:
      host:
        default: your-tanss-host
        description: Hostname of your TANSS instance (replace before sending requests)
security:
  - ApiTokenAuth: []
tags:
  - name: security
    description: Security related infos
  - name: tickets
    description: ticket module calls
  - name: ticket lists
    description: ticket list calls
  - name: projects
    description: |
      Project endpoints — separately-licensed `PROJECT` module. A project is a top-level
      ticket that groups one or more sub-tickets; these routes manage projects, their
      phases, and the relationship between projects and their child tickets.
  - name: ticket content
    description: ticket documents/screenshots
  - name: ticket states
    description: ticket states routes
  - name: ticket workflows
    description: ticket workflow content & landing pages
  - name: ticket priorities
    description: ticket priority configuration
  - name: ticket roles
    description: role assignments on tickets
  - name: tickets - history & meta
    description: |
      Audit-trail and metadata for tickets: change history, hash for
      external embedding, and cloud token validation.
  - name: timestamp
    description: |
      timestamp module

      These routes will be called from a "normal employee login" token.

      Only the route POST api/v1/timestamps is also available using a "timestamps token" by calling api/timestamps/v1 instead.
  - name: timestamp - config
    description: |
      Configuration around time tracking: pause configurations,
      day-closing endpoints, and per-employee initial balance.
  - name: calls
    description: |
      These API calls belong to the "phone call api". They can't be used from a "normal employee login", instead an
      external API token must be created for the role "PHONE" (Telefonie).
  - name: calls (user context)
    description: |
      Routes that are used to get phone calls (usable in the user "default" context)
  - name: remote supports
    description: |
      These API calls belong to the "remote support api". They can't be used from a "normal employee login", instead an
      external API token must be created for the role "REMOTE_SUPPORT" (Fernwartung).
  - name: monitoring
    description: |
      These API calls belong to the "monitoring api". They can't be used from a "normal employee login", instead an
      external API token must be created for the role "MONITORING".
  - name: erp
    description: |
      These API calls belong to the "erp api". They can't be used from a "normal employee login", instead an
      external API token must be created for the role "ERP".
  - name: chats
    description: |
      Chat implementation
  - name: offer
    description: |
      Offer generation and templates
  - name: erp selections
    description: ERP material selections used in offers.
  - name: offer templates
    description: Offer templates, footers and global settings.
  - name: availability
    description: |
      Informations about employee availability
  - name: employees
    description: |
      Informations about employees
  - name: employees - salutations
    description: |
      Salutation lookup table (Mr./Ms./…). Reference data used on
      employee and contact records.
  - name: employees - titles
    description: |
      Title lookup table (Dr., Prof., …). Reference data used on
      employee and contact records.
  - name: employees - departments
    description: |
      Department definitions used to group employees and structure the
      org chart.
  - name: employees - personal data
    description: |
      Personal employee attributes: avatars, birthdays, own state,
      properties, and reachability.
  - name: employees - links & relations
    description: |
      Cross-references between employees and other entities — generic
      employee links, freelancer assignments, and "not wanted technician"
      relationships.
  - name: permission packages
    description: Permission package management.
  - name: permissions
    description: Individual permission assignment.
  - name: mails
    description: |
      Misc. routes regarding sending / receiving of mails
  - name: email settings
    description: Mailbox / e-mail account configuration.
  - name: tags
    description: |
      Tag management
  - name: callback
    description: |
      Information regarding callbacks
  - name: search
    description: |
      Routes for searching in misc. areas (company, employee etc.)
  - name: templates
    description: |
      Entity templates — create, query and apply reusable templates.
  - name: textModules
    description: |
      Reusable text modules (canned text snippets).
  - name: util routes
    description: |
      Miscellaneous utility endpoints (cache, avatars/logos, JWTs for external programs, temporary cache).
  - name: scheduled tasks
    description: |
      System tasks that run periodically via the scheduler (executions, triggering, scheduler control).
  - name: popup notifications
    description: Pop-up notifications shown to the logged-in user.
  - name: checklists
    description: |
      Routes for misc. checklist operations
  - name: checklists - events
    description: |
      Checklist event automations (actions triggered by checklist items).
  - name: checklists - items
    description: |
      Checklist items and their multi-select options.
  - name: supports
    description: |
      Routes for misc. support entry operations
  - name: supportTypes
    description: |
      Routes for support type operations
  - name: additional charges
    description: Additional charge entries on supports.
  - name: support rules
    description: Automated support rules (conditions, events, triggers).
  - name: not charged reasons
    description: Reasons why a support was not charged.
  - name: timers
    description: |
      Routes for misc. timer operations
  - name: pc
    description: |
      Device Management: pc/server

      These routes are also available using a "deviceManagement" token with the prefix /api/deviceManagement/v1/pcs instead of /api/v1/pcs
  - name: periphery
    description: |
      Device Management: periphery

      These routes are also available using a "deviceManagement" token with the prefix /api/deviceManagement/v1/peripheries instead of /api/v1/peripheries
  - name: components
    description: |
      Device Management: components

      These routes are also available using a "deviceManagement" token with the prefix /api/deviceManagement/v1/components instead of /api/v1/components
  - name: services
    description: |
      Device Management: services

      These routes are also available using a "deviceManagement" token with the prefix /api/deviceManagement/v1/services instead of /api/v1/services
  - name: ips
    description: |
      Device Management: ip addresses

      These routes are also available using a "deviceManagement" token with the prefix /api/deviceManagement/v1/ips instead of /api/v1/ips
  - name: company
    description: |
      Routes for companies
  - name: company - master data
    description: |
      Reference data tied to companies: bankaccounts, geocodes, and
      configurable company-type lookups.
  - name: company - relations
    description: |
      Company-to-company relationships, cost-center assignments,
      technician recommendations, and search.
  - name: company category
    description: |
      Routes for company categories and types.

      A category is the overall "topic" and may contain several other actual company "types"
  - name: documents
    description: Routes for company documents.
  - name: entity files
    description: File attachments linked to any entity.
  - name: files & links
    description: Files-and-links storage (media & URLs).
  - name: webHooks
    description: |
      Routes used for WebHook notifications
  - name: ticket board
    description: |
      Routes used for Ticket Boards
  - name: operating systems
    description: |
      Device management: Routes used for managing operating systems

      These routes are also available using a "deviceManagement" token with the prefix /api/deviceManagement/v1/os instead of /api/v1/os
  - name: manufacturer
    description: |
      Device management: Routes used for managing manufacturer

      These routes are also available using a "deviceManagement" token with the prefix /api/deviceManagement/v1/manufacturers instead of /api/v1/manufacturers
  - name: cpus
    description: |
      Device management: Routes used for managing cpus

      These routes are also available using a "deviceManagement" token with the prefix /api/deviceManagement/v1/cpus instead of /api/v1/cpus
  - name: hddTypes
    description: |
      Device management: Routes used for managing hdd types

      These routes are also available using a "deviceManagement" token with the prefix /api/deviceManagement/v1/hddTypes instead of /api/v1/hddTypes
  - name: identify
    description: |
      Identifies misc. items, i.e. get a id by name. Examples:

      - Gets a manufacturer id by name
      - Gets a cpu type id by name
  - name: emailAccounts
    description: |
      Routes regarding E-Mail accounts of a company
  - name: vacationRequests
    description: |
      Routes regarding vacation requests
  - name: vacationRequests - balance & config
    description: |
      Configuration around vacation accounting: vacation-day balances
      per year and the planning additional-type lookup table.
  - name: activityFeed
    description: |
      Routes used for activity feed
  - name: domains
    description: |
      Domain routes
  - name: assignments
    description: |
      Assignment endpoints — flag, role, and relation assignments across tickets, companies and devices.
  - name: escalations
    description: |
      Escalation rules — automated state changes triggered by SLA / time conditions.
  - name: escalation categories
    description: Categories used to group escalation rules.
  - name: ticket types
    description: |
      ticket types endpoints
  - name: administration
    description: |
      Administrative / configuration endpoints (priorities, templates, system settings, etc.).
  - name: accounting types
    description: Accounting types and their prices.
  - name: currencies
    description: Currency lookup table.
  - name: holidays
    description: Holiday lookup table and holiday updates.
  - name: cars
    description: Company car lookup table.
  - name: payment methods
    description: Payment method lookup table.
  - name: text templates
    description: |
      Reusable text modules and text variables for emails, tickets, etc.
  - name: preferences
    description: |
      User and system preferences, config values, and working-hours
      client definitions.
  - name: working hours
    description: Working-hours client definitions and assignments.
  - name: search & maintenance
    description: |
      Search index maintenance (Solr reimport/reset/test), cache
      invalidation, and WebSocket session diagnostics.
  - name: administration - export & ui-helpers
    description: |
      Backend support for UI flows: PDF export endpoints and the mail
      picker helper.
  - name: ai
    description: |
      AI-assisted endpoints (experimental).
  - name: asset management
    description: |
      Asset management — links, types, relationships across devices and companies.
  - name: contracts
    description: |
      Customer contracts (SLA, maintenance, subscription).
  - name: sla
    description: SLA definitions, conditions and permissions.
  - name: tasks
    description: Contract tasks and their recurrence series.
  - name: daily services
    description: |
      Each technician's daily-service / standby roster.
  - name: device management
    description: |
      Top-level device-management endpoints (in addition to the per-device-type tags below).
  - name: git
    description: |
      Git introspection (internal).
  - name: ical
    description: |
      iCal feed endpoints.
  - name: knowledge base
    description: |
      Knowledge-base entries and search.
  - name: logging
    description: |
      Diagnostic / observability endpoints.
  - name: mail robot
    description: |
      Inbound-mail parsing rules — turns raw mails into tickets / comments.
  - name: passkey
    description: |
      WebAuthn passkey registration and management (employee login).
  - name: planning
    description: |
      Capacity and resource planning.
  - name: portal
    description: |
      General customer-portal endpoints.
  - name: recurrence
    description: |
      Recurring tickets and recurring events.
  - name: roles
    description: |
      Role catalog and assignments.
  - name: service portal
    description: |
      Endpoints serving the customer-facing TANSS service portal.
  - name: software licenses
    description: |
      software licenses endpoints
  - name: software license types
    description: Software license type definitions and tree view.
  - name: tanss portal
    description: |
      TANSS portal API endpoints (branded customer portal).
  - name: workflow contracts
    description: |
      Contract templates and workflow-driven contracts.
paths:
  /api/v1/login:
    post:
      operationId: post_api_v1_login
      tags:
        - security
      security: []
      summary: Log in and obtain an API token
      description: |
        Exchanges username + password credentials for a pair of JWTs that
        authenticate all subsequent API calls.

        A successful response carries two tokens:

        | Token              | Field              | Lifetime  | Purpose                                                               |
        |--------------------|--------------------|-----------|-----------------------------------------------------------------------|
        | **API token**      | `content.apiKey`   | 4 hours   | Sent on every authenticated request as `apiToken: Bearer <jwt>`.      |
        | **Refresh token**  | `content.refresh`  | 5 days    | Exchange for a fresh API token without re-submitting credentials.     |

        The `apiKey` value already includes the literal `Bearer ` prefix — send it
        verbatim under the `apiToken` header (note: this is the literal header
        name, **not** the standard `Authorization` header).

        On top of the 4-hour absolute lifetime, the API enforces a 2-minute idle
        timeout: any window of more than ~120 seconds without a request
        invalidates the session. Re-call this endpoint, or call
        `POST /api/v1/login/refresh` with the refresh token, to obtain a new pair.
      requestBody:
        description: login credentials (as json)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsLoginCredentials'
            example:
              username: sb
              password: secret password
              token: ''
      responses:
        '200':
          description: successful login attempt
          content:
            application/json:
              example:
                meta:
                  text: Welcome, your ApiToken is 4 hours valid.
                content:
                  employeeId: 1
                  apiKey: Bearer xyzXyZ
                  expire: 1563963819
                  refresh: Bearer exyzXYZ
                  employeeType: CUSTOMER
        '403':
          description: unsuccessful login attempt
          content:
            application/json:
              example:
                meta:
                  text: Unsuccessful login attempt
                content:
                  detailMessage: LOGIN_ERROR_INVALID_USERNAME_OR_PASSWORD
  /api/v1/tickets/own:
    get:
      operationId: get_api_v1_tickets_own
      tags:
        - ticket lists
      summary: List of own tickets
      description: |
        Returns open tickets where the logged-in employee is the assigned technician —
        the default "my work queue" view in a technician UI.

        Closed and archived tickets are excluded by status. For involvement via an
        explicit role (e.g. co-technician, observer) rather than as the main
        assignee, use `GET /api/v1/tickets/withRole` instead.
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/general:
    get:
      operationId: get_api_v1_tickets_general
      tags:
        - ticket lists
      summary: List of unassigned tickets
      description: |
        Returns open tickets that currently have no technician assigned.

        Tickets created without an assignee — for example, inbound mails or customer
        portal submissions — land here until someone picks them up. A typical
        dispatcher flow is to read this list, then claim a ticket by updating its
        `assigneeId` via `PUT /api/v1/tickets/{ticketId}`.
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/company/{companyId}:
    get:
      operationId: get_api_v1_tickets_company_companyId
      tags:
        - ticket lists
      summary: List of tickets for a company
      description: |
        Returns all tickets associated with the given company. Intended for
        customer-facing portals or for technicians filtering their view by client.

        By default the result spans both open and closed tickets — use the
        configurable list endpoint (`PUT /api/v1/tickets`) if you need state
        filters, pagination, or sort options.
      parameters:
        - in: path
          name: companyId
          description: id of the company for the tickets
          example: 100023
          schema:
            type: integer
          required: true
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/technician:
    get:
      operationId: get_api_v1_tickets_technician
      tags:
        - ticket lists
      summary: List of tickets assigned to other technicians
      description: |
        Returns open tickets assigned to technicians other than the logged-in
        employee. Designed for dispatcher and team-lead views that need visibility
        into colleagues' workloads.

        For the logged-in employee's own queue, use `GET /api/v1/tickets/own`.
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/repair:
    get:
      operationId: get_api_v1_tickets_repair
      tags:
        - ticket lists
      summary: List of repair tickets
      description: |
        Returns tickets flagged as repair work. Repair tickets are typically created
        from device-management workflows (e.g. a hardware service request) and
        follow a status flow distinct from regular service tickets.

        Use this view in workshop or service-desk contexts where physical-device
        work needs to be tracked separately from general support tickets.
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/notIdentified:
    get:
      operationId: get_api_v1_tickets_notIdentified
      tags:
        - ticket lists
      summary: List of unidentified tickets
      description: |
        Returns tickets that could not be auto-associated with a company — typically
        inbound mails whose sender address did not match any known contact or
        customer domain.

        These tickets sit in limbo until an admin manually assigns them to a company
        (via `PUT /api/v1/tickets/{ticketId}`) so the normal workflow can resume.
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/projects:
    get:
      operationId: get_api_v1_tickets_projects
      tags:
        - projects
      summary: List of projects
      description: |
        Returns project-level tickets. In TANSS a project is a top-level ticket
        that groups one or more sub-tickets; this endpoint returns only the project
        parents.

        To fetch the sub-tickets attached to a project, use the configurable list
        endpoint (`PUT /api/v1/tickets`) and filter by the project's `id` as
        `parentTicketId`.
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/localAdminOverview:
    get:
      operationId: get_api_v1_tickets_localAdminOverview
      tags:
        - ticket lists
      summary: List of tickets under local-admin oversight
      description: |
        Returns tickets visible to *local ticket admins* — customer-side staff who
        manage tickets on behalf of their own organisation.

        Use this in customer portals or admin overview screens; the list spans all
        tickets the local admin has oversight on, not only those they personally
        created or assigned.
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/withRole:
    get:
      operationId: get_api_v1_tickets_withRole
      tags:
        - ticket lists
      summary: List of tickets where the technician holds a role
      description: |
        Returns tickets where the logged-in employee holds an explicit role — main
        technician, co-technician, observer, etc. — rather than only those assigned
        via the default `assigneeId`.

        Useful for surfacing involvement that does not show up in
        `GET /api/v1/tickets/own`, such as tickets the technician is supporting on
        or watching without being the primary owner.
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets:
    post:
      operationId: post_api_v1_tickets
      tags:
        - tickets
      summary: Create a ticket
      description: |
        Creates a new ticket. The request body must contain at minimum a
        `companyId`, `subject`, and a `remitterId` (the contact who reported the
        issue) — unless `remitterCheck=false` is passed to bypass the remitter
        requirement (useful when importing or when the originating contact is
        unknown).

        When creating a project, sub-tickets can be supplied inline via
        `subTickets[]` and will be attached as children in a single call.
        Tag assignments can be sent under `tags[]`.

        Returns the fully-saved `Ticket-Complete` shape, including the
        server-assigned `id` and any computed fields.
      requestBody:
        description: ticket object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ticket-Save'
            example:
              companyId: 1
              remitterId: 1
              title: Example title
              content: Example content
              extTicketId: string
              assignedToEmployeeId: 1
              assignedToDepartmentId: 1
              statusId: 1
              linkTypeId: 1
              linkId: 1
              deadlineDate: 1748256000
              project: false
              projectId: 1
              typeId: 1
              repair: false
      parameters:
        - in: query
          name: remitterCheck
          description: |
            When `false`, skips the validation that a remitter must be present.
            Defaults to `true`.
          example: true
          required: false
          schema:
            type: boolean
      responses:
        '201':
          description: ticket was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Ticket-Complete'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tickets
      tags:
        - ticket lists
      summary: Configurable ticket list
      description: |
        Retrieves a ticket list using arbitrary filter, sort, and pagination
        criteria supplied in the request body (`TicketConfiguration`). This is the
        general-purpose list endpoint behind most UI ticket views.

        When one of the specialised list endpoints (`/own`, `/general`,
        `/technician`, `/repair`, `/notIdentified`, `/projects`, `/withRole`,
        `/localAdminOverview`, `/company/{companyId}`) matches your use case
        exactly, prefer it — those are faster, take no body, and don't require
        you to compose a filter object.
      requestBody:
        description: query parameters for retrieving ticket
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketConfiguration'
            example:
              staff: []
              notAssignedToEmployees: []
              companies: []
              departments: []
              isRepair: false
              remitterId: 1
              ids: []
              projectId: 1
              phaseId: 1
              includeDoneTickets: false
      responses:
        '200':
          $ref: '#/components/responses/TicketListResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}:
    get:
      operationId: get_api_v1_tickets_ticketId
      tags:
        - tickets
      summary: Gets a ticket by id
      description: Fetches a ticket by id and returns all aspects of the ticket
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket to retrieve.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ticket was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Ticket-List'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_tickets_ticketId
      tags:
        - tickets
      summary: Deletes a ticket by id
      description: |
        This call will delete a ticket.

        If the parameter "targetTicketId" is given, will also move entities such as chats or callbacks to a target ticket
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket to delete.
          example: 4711
          required: true
          schema:
            type: integer
        - in: query
          name: targetTicketId
          example: 4711
          required: false
          description: if given, will also move entities such as chats or callbacks to a target ticket
          schema:
            type: integer
      responses:
        '204':
          description: ticket was successfully deleted
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tickets_ticketId
      tags:
        - tickets
      summary: Updates a ticket
      description: Updated a ticket
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket to update.
          example: 4711
          required: true
          schema:
            type: integer
        - in: query
          name: remitterCheck
          description: can be given to omit the check that a remitter is required when storing tickets
          example: false
          required: false
          schema:
            type: boolean
      requestBody:
        description: updated ticket object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ticket-Complete'
            example:
              companyId: 1
              remitterId: 1
              title: Example title
              content: Example content
              extTicketId: string
              assignedToEmployeeId: 1
              assignedToDepartmentId: 1
              statusId: 1
              linkTypeId: 1
              linkId: 1
              deadlineDate: 1748256000
              project: false
              projectId: 1
              typeId: 1
              repair: false
      responses:
        '202':
          description: ticket was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Ticket-List'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/history/{ticketId}:
    get:
      operationId: get_api_v1_tickets_history_ticketId
      tags:
        - tickets - history & meta
      summary: Gets a ticket history
      description: |
        This route will fetch a list of comments, supports and mails from a ticket
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose history should be fetched.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ticket history
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Ticket-History'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/comments:
    post:
      operationId: post_api_v1_tickets_ticketId_comments
      tags:
        - tickets
      summary: Creates a comment
      description: This call will create a comment for a given ticket
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket the comment is created on.
          example: 4711
          required: true
          schema:
            type: integer
        - in: query
          name: pinned
          example: true
          required: false
          schema:
            type: boolean
          description: comment can optionally be "pinned" to the ticket
      requestBody:
        description: comment to be created
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsComment'
            example: {}
      responses:
        '201':
          description: comment was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsComment'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/documents:
    get:
      operationId: get_api_v1_tickets_ticketId_documents
      tags:
        - ticket content
      summary: Gets all ticket documents
      description: Gets all the documents attached to a ticket
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose documents should be returned.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: list of ticket documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTicketFile'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/documents/{documentId}:
    get:
      operationId: get_api_v1_tickets_ticketId_documents_documentId
      tags:
        - ticket content
      summary: Gets a ticket document
      description: |
        This call will produce a direct download link for downloading this document.

        The generated url can only be used once withing 15 minutes.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket the document belongs to.
          example: 4711
          required: true
          schema:
            type: integer
        - in: path
          name: documentId
          example: 42
          required: true
          schema:
            type: integer
          description: id of the document
      responses:
        '200':
          description: download link for the document
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsFilePassResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/screenshots:
    get:
      operationId: get_api_v1_tickets_ticketId_screenshots
      tags:
        - ticket content
      summary: Gets all ticket images
      description: Gets all the images attached to a ticket
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose images should be returned.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: list of ticket images
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTicketImage'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/screenshots/{imageId}:
    get:
      operationId: get_api_v1_tickets_ticketId_screenshots_imageId
      tags:
        - ticket content
      summary: Gets a ticket image
      description: |
        This call will produce a direct download link for downloading this image.

        The generated url can only be used once withing 15 minutes.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket the image belongs to.
          example: 4711
          required: true
          schema:
            type: integer
        - in: path
          name: imageId
          example: 42
          required: true
          schema:
            type: integer
          description: id of the image
      responses:
        '200':
          description: download link for the image
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsFilePassResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/upload:
    post:
      operationId: post_api_v1_tickets_ticketId_upload
      tags:
        - ticket content
      summary: upload a document/image
      description: |
        This route lets you upload a document or image into a ticket.

        E-mails can be uploaded as well, the system will try to parse them and store them as e-mails.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket the file should be uploaded to.
          example: 4711
          required: true
          schema:
            type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - files
                - descriptions
              properties:
                files:
                  type: string
                  format: binary
                  description: REQUIRED! binary data of the uploaded file(s)
                descriptions:
                  type: string
                  format: binary
                  description: REQUIRED! description of the uploaded file(s)
                internal:
                  type: boolean
                  description: optional flag to mark the uploaded file(s) as internal
      responses:
        '200':
          description: upload was succesful
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsDataFile'
              example: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/calls/v1:
    post:
      operationId: post_api_calls_v1
      security:
        - PhoneToken: []
      tags:
        - calls
      summary: Creates/imports a phone call into the database
      description: |
        This api call is used to import a phone call into the database.
      requestBody:
        description: call object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPhoneCall'
            example:
              id: 42
              callId: string
              telephoneSystemId: 1
              date: 1748256000
              fromPhoneNumber: +49 30 1234567
              toPhoneNumber: +49 30 1234567
              direction: INTERNAL
              connectionEstablished: false
              durationTotal: 3600
              durationCall: 3600
              group: string
      responses:
        '201':
          description: call was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPhoneCall'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_calls_v1
      security:
        - PhoneToken: []
      tags:
        - calls
      summary: Get a list of phone calls
      description: |
        Retrieves a list of phone calls from the database, using misc. filter settings
      requestBody:
        description: filter settings
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPhoneCallConfiguration'
            example:
              timeframe:
                from: 1
                to: 1
              showTrysAsWell: false
              numberFilters: []
              employeeId: 1
              companyId: 1
              numberInfos: false
              directions: []
      responses:
        '200':
          description: list of all retrived phone calls
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPhoneCall'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/calls/v1/{id}:
    get:
      operationId: get_api_calls_v1_id
      security:
        - PhoneToken: []
      tags:
        - calls
      summary: Get phone call by id
      description: Gets a specific phone call from the database based on the phone call id
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the phone call to be fetched
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: call was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPhoneCall'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_calls_v1_id
      security:
        - PhoneToken: []
      tags:
        - calls
      summary: Update phone call
      description: This api call updates an existing phone call
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the phone call to be updated
          example: 42
          schema:
            type: integer
      requestBody:
        description: Updated phone call object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPhoneCall'
            example:
              id: 42
              callId: string
              telephoneSystemId: 1
              date: 1748256000
              fromPhoneNumber: +49 30 1234567
              toPhoneNumber: +49 30 1234567
              direction: INTERNAL
              connectionEstablished: false
              durationTotal: 3600
              durationCall: 3600
              group: string
      responses:
        '200':
          description: Updated phone call object
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPhoneCall'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/calls/v1/identify:
    post:
      operationId: post_api_calls_v1_identify
      security:
        - PhoneToken: []
      tags:
        - calls
      summary: identifies a phone call
      description: Tries to identify a phone call and resolve company and employeeId. Identified data will be given in the fields `fromPhoneNrInfos` and `toPhoneNrInfos`
      requestBody:
        description: call object to be identified
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPhoneCall-Identify'
            example:
              fromPhoneNumber: +49 30 1234567
              toPhoneNumber: +49 30 1234567
      responses:
        '200':
          description: the identified phone call
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPhoneCall'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/calls/v1/employeeAssignment:
    get:
      operationId: get_api_calls_v1_employeeAssignment
      security:
        - PhoneToken: []
      tags:
        - calls
      summary: Get all employee assignments
      description: Get all assignments between idStrings and TANSS employees
      responses:
        '200':
          description: list of all employee assignments
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPhoneEmployee'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_calls_v1_employeeAssignment
      security:
        - PhoneToken: []
      tags:
        - calls
      summary: Creates a new employee assignment
      description: Create a new assignment between an "idString" and a TANSS employee id
      requestBody:
        description: Phone employee assignment
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPhoneEmployee'
            example:
              employeeId: 1
              username: max.mustermann
      responses:
        '201':
          description: Created phone employee assignment
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPhoneEmployee'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_calls_v1_employeeAssignment
      security:
        - PhoneToken: []
      tags:
        - calls
      summary: Deletes an employee assignment
      description: Deletes an assignment between an "idString" and a TANSS employee id from the database
      requestBody:
        description: Phone employee assignment to be deleted
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPhoneEmployee'
            example:
              employeeId: 1
              username: max.mustermann
      responses:
        '204':
          description: Deleted phone employee assignment
        '404':
          description: phone employee assignment not found
  /api/calls/v1/notification:
    post:
      operationId: post_api_calls_v1_notification
      security:
        - PhoneToken: []
      tags:
        - calls
      summary: Creates a call notification
      description: |
        This api call is used to generate a notification for an incoming or outgoing call.

        This is used to display a pop-up to the given participants.
      requestBody:
        description: call object for this notification
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPhoneCall'
            example:
              id: 42
              callId: string
              telephoneSystemId: 1
              date: 1748256000
              fromPhoneNumber: +49 30 1234567
              toPhoneNumber: +49 30 1234567
              direction: INTERNAL
              connectionEstablished: false
              durationTotal: 3600
              durationCall: 3600
              group: string
      responses:
        '200':
          description: notification response was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPhoneCall'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/phoneCalls:
    put:
      operationId: put_api_v1_phoneCalls
      tags:
        - calls (user context)
      summary: Get a list of phone calls
      description: |
        Retrieves a list of phone calls from the database, using misc. filter settings
      requestBody:
        description: filter settings
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPhoneCallConfiguration'
            example:
              timeframe:
                from: 1
                to: 1
              showTrysAsWell: false
              numberFilters: []
              employeeId: 1
              companyId: 1
              numberInfos: false
              directions: []
      responses:
        '200':
          description: list of all retrived phone calls
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPhoneCall'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/phoneCalls/{id}:
    get:
      operationId: get_api_v1_phoneCalls_id
      tags:
        - calls (user context)
      summary: Get phone call by id
      description: Gets a specific phone call from the database based on the phone call id
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the phone call to be fetched
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: call was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPhoneCall'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/phoneCalls/identify:
    post:
      operationId: post_api_v1_phoneCalls_identify
      tags:
        - calls (user context)
      summary: identifies a phone call
      description: Tries to identify a phone call and resolve company and employeeId. Identified data will be given in the fields `fromPhoneNrInfos` and `toPhoneNrInfos`
      requestBody:
        description: call object to be identified
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPhoneCall-Identify'
            example:
              fromPhoneNumber: +49 30 1234567
              toPhoneNumber: +49 30 1234567
      responses:
        '200':
          description: the identified phone call
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPhoneCall'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/remoteSupports/v1:
    post:
      operationId: post_api_remoteSupports_v1
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Creates/imports a remote support into the database
      description: |
        Stores/imports a remote support of an external system into the TANSS database.
        * if `userId` is given, the api can try to "translate" it to a TANSS employee (use route `/api/remoteSupports/v1/assignEmployee` to set the matchings)
        * if `deviceId` is given, the api can try to "translate" it into a TANSS company and assignment (use route `/api/remoteSupports/v1/assignDevice` to set the matchings)
      requestBody:
        description: remote object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsRemoteMaintenance'
            example:
              id: 42
              remoteMaintenanceId: string
              typeId: 1
              userId: string
              userName: max.mustermann
              employeeId: 1
              deviceId: string
              deviceName: string
              companyId: 1
              linkTypeId: 1
              linkId: 1
              startTime: 1748256000
              endTime: 1748256000
              comment: Example content
      responses:
        '201':
          description: remote support was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsRemoteMaintenance'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_remoteSupports_v1
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Get list of remote supports
      description: Gets a list of remote supports calls based on misc. filter settings
      requestBody:
        description: filter settings
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsRemoteMaintenanceConfiguration'
            example:
              timeframe:
                from: 1
                to: 1
              employeeId: 1
              companyId: 1
              typeId: 1
              text: Example content
      responses:
        '200':
          description: list of all retrived remote supports
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsRemoteMaintenance'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/remoteSupports/v1/{remoteSupportId}:
    get:
      operationId: get_api_remoteSupports_v1_remoteSupportId
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Get remote support by id
      description: |
        Gets a remote support from the database (based on the id)
      parameters:
        - in: path
          name: remoteSupportId
          required: true
          description: Id of the remote support to be fetched
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: remote support was successfully fetched
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsRemoteMaintenance'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_remoteSupports_v1_remoteSupportId
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Updates a remote support
      description: Updates a remote support by id and sets the new values
      parameters:
        - in: path
          name: remoteSupportId
          required: true
          description: Id of the remote support to be updated
          schema:
            type: integer
          example: 1
      requestBody:
        description: new values for the remote support object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsRemoteMaintenance'
            example:
              id: 42
              remoteMaintenanceId: string
              typeId: 1
              userId: string
              userName: max.mustermann
              employeeId: 1
              deviceId: string
              deviceName: string
              companyId: 1
              linkTypeId: 1
              linkId: 1
              startTime: 1748256000
              endTime: 1748256000
              comment: Example content
      responses:
        '200':
          description: updated remote support object
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsRemoteMaintenance'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_remoteSupports_v1_remoteSupportId
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Delete remote support
      description: Deletes a remote support by id. This can only be done for "external" remote support (type >= 1000)
      parameters:
        - in: path
          name: remoteSupportId
          required: true
          description: Id of the remote support to be deleted
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: object was successfully deleted
        '403':
          description: return a "forbidden" if external id is not present or not from an "external" remote support system
  /api/remoteSupports/v1/assignDevice:
    get:
      operationId: get_api_remoteSupports_v1_assignDevice
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Gets all device assignments
      description: |
        This call gets all device assignments of the given remote support "type". A list is returned containing all information
        how to match a `deviceId` for the given remote support type to a TANSS company / assignment.
        The "type" is fix and is stored in the used Api token.
      responses:
        '200':
          description: a list of all device assignments
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsRemoteMaintenanceDeviceAssignment'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_remoteSupports_v1_assignDevice
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Creates a device assignment
      description: |
        This call creates an entry in a "translation table" that allows identification of a remote support to a company / assignment
        based of the `deviceId`
      requestBody:
        description: object containing the assignment of "`deviceId` -> `company` / `linkTypeId` / `linkId`"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsRemoteMaintenanceDeviceAssignment'
            example:
              deviceId: string
              companyId: 1
              linkTypeId: 1
              linkId: 1
      responses:
        '201':
          description: assignment object created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsRemoteMaintenanceDeviceAssignment'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_remoteSupports_v1_assignDevice
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Deletes a device assignment
      description: |
        This call deletes an entry in a "translation table" that allows identification of a remote support to a company / assignment
        based of the `deviceId`
      requestBody:
        description: object containing the assignment of "`type` + `deviceId` -> `company` / `linkTypeId` / `linkId`"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsRemoteMaintenanceDeviceAssignmentId'
            example:
              deviceId: string
      responses:
        '204':
          description: assignment object deleted successfully
        '403':
          description: error if assignment was not found
  /api/remoteSupports/v1/assignEmployee:
    get:
      operationId: get_api_remoteSupports_v1_assignEmployee
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Gets all technician assignments
      description: |
        This call gets all employee assignments for the current remote support "type".
        The "type" is fix and is stored in the used Api token.
      responses:
        '200':
          description: list of all remote support type employee assignments
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsRemoteMaintenanceEmployeeAssignment'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_remoteSupports_v1_assignEmployee
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Creates a technician assignment
      description: |
        This call creates an entry in a "translation table" that allows identification of a TANSS employee based on a `userId`
        of a remote support
      requestBody:
        description: object containing the assignment of "`type` + `userId` -> `employeeId`"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsRemoteMaintenanceEmployeeAssignment'
            example:
              userId: string
              employeeId: 1
      responses:
        '201':
          description: assignment object created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsRemoteMaintenanceEmployeeAssignment'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_remoteSupports_v1_assignEmployee
      security:
        - RemoteSupportToken: []
      tags:
        - remote supports
      summary: Delets a technician assignment
      description: |
        This call deletes an entry in a "translation table" that allows identification of a TANSS employee based on a `userId`
        of a remote support
      requestBody:
        description: object containing the assignment of "`type` + `userId` -> `employeeId`"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsRemoteMaintenanceEmployeeAssignmentId'
            example:
              userId: string
      responses:
        '204':
          description: assignment object deleted successfully
        '403':
          description: error if entity not found
  /api/monitoring/v1/ticket:
    post:
      operationId: post_api_monitoring_v1_ticket
      security:
        - MonitoringToken: []
      tags:
        - monitoring
      summary: Creates a ticket, using the monitoring api
      description: |
        A monitoring system can create tickets. This is mainly the same process as creating a ticket via the API (`POST /api/v1/tickets`), but has the following special behaviours:

        * You don't have to know the `companyId` or assignment (`linkTypeId` / `linkId`), as the api can retrieve them from the given `groupName`
        * The `groupName` can be assigned to companies or assignment - this is done via the route `/api/monitoring/v1/assignGroup`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Ticket-Save'
                - type: object
                  properties:
                    groupName:
                      type: string
                      description: A group name can be entered, to identify the "source" or "device" of the ticket.
            example: {}
      responses:
        '201':
          description: ticket was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Ticket-Complete'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/monitoring/v1/assignGroup:
    post:
      operationId: post_api_monitoring_v1_assignGroup
      security:
        - MonitoringToken: []
      tags:
        - monitoring
      summary: Assigns a groupName to a company or device
      description: |
        Monitoring systems send "groups" to determine, for which device a ticket shall be created. A "translation table" can
        be filled with assignments of goup names to specific devices - the following api call does this.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsMonitoringGroupNameMatching'
            example:
              groupName: Server XY - Festplattensensor
              companyId: 13323
              linkTypeId: 1
              linkId: 1413
      responses:
        '201':
          description: assignment was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsMonitoringGroupNameMatching'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_monitoring_v1_assignGroup
      security:
        - MonitoringToken: []
      tags:
        - monitoring
      summary: Delete a group assignment
      description: |
        Monitoring systems send "groups" to determine for which device a ticket shall be created. A "translation table" can
        be filled with assignments of goup names to specific devices.

        This call deletes such an assignment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsMonitoringGroupNameMatchingId'
            example:
              groupName: Server XY - Festplattensensor
      responses:
        '204':
          description: assignment was deleted
        '403':
          description: assignment was not found
    get:
      operationId: get_api_monitoring_v1_assignGroup
      security:
        - MonitoringToken: []
      tags:
        - monitoring
      summary: Gets all group assignments
      description: |
        Monitoring systems send "groups" to determine, for which device a ticket shall be created. A "translation table" can
        be filled with assignments of goup names to specific devices.

        This call lists all existing group assignments.
      responses:
        '200':
          description: a list of all group assignments
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsMonitoringGroupNameMatching'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/monitoring/v1/ticketsFromGroup:
    get:
      operationId: get_api_monitoring_v1_ticketsFromGroup
      security:
        - MonitoringToken: []
      tags:
        - monitoring
      summary: Gets ticket(s), based on a given group
      description: |
        If a monitoring system wants to check if a ticket does exist based on a given group name, this can be checked here
      parameters:
        - in: query
          name: groupName
          required: true
          description: Name of the group, which the ticket shall be retrieved for
          schema:
            type: string
          example: Server-01 - CPU
        - in: query
          name: closedTickets
          description: The default behaviour ist that only "open" tickets will be returned. Set this to "true" if you want to retrieve closed tickets as well
          schema:
            type: boolean
          example: true
      responses:
        '200':
          description: If found, the tickets are returned here (gets a list of tickets)
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ticket-List'
        '204':
          description: If no ticket was found, an empty body is returned
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/monitoring/v1/ticket/{ticketId}:
    get:
      operationId: get_api_monitoring_v1_ticket_ticketId
      security:
        - MonitoringToken: []
      tags:
        - monitoring
      summary: Gets a ticket (created by the monitoring api) by id
      description: |
        Fetches a ticket by id and returns all aspects of the ticket.
        Only tickets which were created by the monitoring api routes can be fetched.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket that should be fetched
          required: true
          schema:
            type: integer
          example: 4711
      responses:
        '200':
          description: ticket was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Ticket-List'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_monitoring_v1_ticket_ticketId
      security:
        - MonitoringToken: []
      tags:
        - monitoring
      summary: Updates a ticket (created by the monitoring api) by id
      description: |
        Updates a ticket by id.
        Only tickets which were created by the monitoring api routes can be editied.
      parameters:
        - in: path
          name: ticketId
          required: true
          description: Id of the ticket that should be updated
          schema:
            type: integer
          example: 4711
      responses:
        '200':
          description: ticket was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Ticket-List'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/invoices:
    get:
      operationId: get_api_erp_v1_invoices
      security:
        - ErpToken: []
        - ApiTokenAuth: []
      tags:
        - erp
      summary: Get invoices
      description: |
        Returns the list of invoices for the given customer by delegating to the legacy PHP ERP backend; used by ERP integrations to read invoice data from TANSS. Intended for ERP integrations only — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: query
          name: customer
          description: Customer number whose invoices are returned.
          required: false
          schema:
            type: string
            default: ''
          example: K100023
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/customers:
    get:
      operationId: get_api_erp_v1_customers
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get customers
      description: |
        Returns the customer list by forwarding the request to the legacy PHP ERP backend (`api/v1/erp/customers`); used by ERP integrations to read TANSS-side customer data through the bridge. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_erp_v1_customers
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Post customers
      description: |
        Creates or updates customer data by forwarding the request body to the legacy PHP ERP backend (`api/v1/erp/customers`); used by ERP integrations to push customer master data into TANSS via the bridge. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      requestBody:
        description: Raw string body (no JSON wrapping).
        required: true
        content:
          application/json:
            schema:
              type: string
            example: Beispiel GmbH
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/tickets:
    post:
      operationId: post_api_erp_v1_tickets
      security:
        - ErpToken: []
      tags:
        - erp
      summary: create a new ticket
      description: This call creates a new ticket in the database
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ticket-Save'
      responses:
        '200':
          description: ticket created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 201
                      text:
                        type: string
                        example: Object successfully created
                  content:
                    $ref: '#/components/schemas/Ticket-List'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/tickets/status:
    get:
      operationId: get_api_erp_v1_tickets_status
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get all ticket states
      description: |
        Returns the list of all ticket states configured in TANSS, so an ERP system can map ticket status during sync. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/tickets/types:
    get:
      operationId: get_api_erp_v1_tickets_types
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get all ticket types
      description: |
        Returns all active ticket types configured in TANSS, so an ERP system can pick a valid type when creating tickets via the sync. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/tickets/{ticketId}/upload:
    post:
      operationId: post_api_erp_v1_tickets_ticketId_upload
      security:
        - ErpToken: []
      tags:
        - erp
      summary: upload a document/image into a ticket
      description: |
        This route lets you upload a document or image into a ticket.
      parameters:
        - in: path
          name: ticketId
          required: true
          description: id of the ticket the file(s) are uploaded into
          schema:
            type: integer
          example: 4711
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - files
                - descriptions
              properties:
                files:
                  type: string
                  format: binary
                  description: REQUIRED! binary data of the uploaded file(s)
                descriptions:
                  type: string
                  format: binary
                  description: REQUIRED! description of the uploaded file(s)
                internal:
                  type: boolean
                  description: optional flag to mark the uploaded file(s) as internal
      responses:
        '200':
          description: upload was successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsDataFile'
              example: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/companies/employees:
    get:
      operationId: get_api_erp_v1_companies_employees
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get employee from own company
      description: |
        Returns employees for the given company. If `companyNumber` is supplied, employees of all companies sharing that number are returned; otherwise `companyId` is used (falling back to the own company when zero). Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: query
          name: companyId
          description: Optional company ID whose employees are returned (0 = own company).
          required: false
          schema:
            type: integer
            default: 0
          example: 100023
        - in: query
          name: companyNumber
          description: Optional company number; returns employees of all companies sharing it.
          required: false
          schema:
            type: string
            default: ''
          example: K-10042
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/companies/departments:
    get:
      operationId: get_api_erp_v1_companies_departments
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get company departments
      description: |
        Returns the full list of company departments (Abteilungen) configured in TANSS, so that an ERP system can map employees and tickets to the correct department during sync. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/companyCategories:
    get:
      operationId: get_api_erp_v1_companyCategories
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get company categories
      description: |
        Returns the list of company categories (Firmen-Kategorien) including the company types associated with each category, so an ERP system can map customer classifications during sync. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/departments/{departmentId}/employees:
    get:
      operationId: get_api_erp_v1_departments_departmentId_employees
      security:
        - ErpToken: []
      tags:
        - erp
      summary: gets all employees of a department
      description: This call lists all employees of a given department
      parameters:
        - in: path
          name: departmentId
          required: true
          description: Id of the department
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: list of employees in this department
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee-Short'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/companies/searchId/{displayId}:
    get:
      operationId: get_api_erp_v1_companies_searchId_displayId
      security:
        - ErpToken: []
      tags:
        - erp
      summary: search for a company
      description: This call searches for a customers based on the ERP customer number
      parameters:
        - in: path
          name: displayId
          required: true
          description: external customer number, which is used by the ERP system
          schema:
            type: string
          example: SAP-1023
      responses:
        '200':
          description: list of companies
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Company-Detail'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/employees/{employeeId}/departments:
    get:
      operationId: get_api_erp_v1_employees_employeeId_departments
      security:
        - ErpToken: []
      tags:
        - erp
      summary: gets all departments of a employee
      description: This call gets all the associated departments of an employee
      parameters:
        - in: path
          name: employeeId
          schema:
            type: integer
          required: true
          description: Id of the employee
          example: 5
      responses:
        '200':
          description: a list of departments
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Department-Short'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/companies/employees/departments:
    get:
      operationId: get_api_erp_v1_companies_employees_departments
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get department employee
      description: |
        Returns a map of department lists keyed by employee ID for all active employees of the own company. Used by ERP integrations to discover the department memberships of internal staff in one call. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/checklists:
    get:
      operationId: get_api_erp_v1_checklists
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get checklists
      description: |
        Returns the list of checklists in TANSS, optionally filtered by company and/or department, so an ERP system can pick a checklist to assign to a ticket or other linked entity. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: query
          name: companyId
          description: Optional company ID to filter checklists by (0 = no filter).
          required: false
          schema:
            type: string
            default: '0'
          example: '100023'
        - in: query
          name: departmentId
          description: Optional department ID to filter checklists by (0 = no filter).
          required: false
          schema:
            type: string
            default: '0'
          example: '1'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/checklists/assignment/{linkTypeId}/{linkId}/{checklistId}:
    post:
      operationId: post_api_erp_v1_checklists_assignment_linkTypeId_linkId_checklistId
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Assigns a checklist to a ticket
      description: |
        This route will assign a checklist to a ticket
      parameters:
        - in: path
          name: linkTypeId
          required: true
          description: linkTypeId (11 = ticket)
          schema:
            type: integer
          example: 1
        - in: path
          name: linkId
          required: true
          description: id of the ticket
          schema:
            type: integer
          example: 4711
        - in: path
          name: checklistId
          required: true
          description: id of the checklist
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: checklist assigned correctly
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChecklist-With-Assignment-Infos'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps:
    get:
      operationId: get_api_v1_timestamps
      tags:
        - timestamp
      summary: gets a list of timestamps from a given period
      parameters:
        - in: query
          name: from
          description: timestamp of start of period. if omitted,the beginning of the current day will be used
          example: 1748256000
          schema:
            type: integer
            format: timestamp
        - in: query
          name: till
          description: timestamp of end of period. if omitted,the end of the current day will be used
          example: 1748256000
          schema:
            type: integer
            format: timestamp
      responses:
        '200':
          description: list of timestamps
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Timestamp'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_timestamps
      tags:
        - timestamp
      summary: writes a timestamp into the database
      parameters:
        - in: query
          name: autoPause
          description: if true, a pause will automatically be inserted, if the minimum pause is not met for this day (see "pause config" routes)
          example: true
          schema:
            type: boolean
          required: false
      requestBody:
        description: timestamp object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Timestamp'
            example:
              state: PAUSE_START
              type: WORK
      responses:
        '201':
          description: timestamp was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Timestamp'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/{timestampId}:
    put:
      operationId: put_api_v1_timestamps_timestampId
      tags:
        - timestamp
      summary: edits a single timestamp
      description: with this call, you can edit a single timestamp
      parameters:
        - in: path
          name: timestampId
          description: id of the timestamp
          example: 42
          schema:
            type: integer
          required: true
      requestBody:
        description: timestamp object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Timestamp'
            example:
              id: 42
              employeeId: 1
              date: 1748256000
              state: 'ON'
              type: WORK
      responses:
        '200':
          description: timestamp was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Timestamp'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/{employeeId}/day/{day}:
    put:
      operationId: put_api_v1_timestamps_employeeId_day_day
      tags:
        - timestamp
      summary: writes the timstamps of a whole day into the database at once
      description: This call automatically saves all timestamps of a single day into the databse (automatically determines which of those shall be inserted, updated or deleted)
      parameters:
        - in: path
          name: employeeId
          description: id of the employee
          example: 5
          schema:
            type: integer
          required: true
        - in: path
          name: day
          description: the day whose timestamps are saved (format YYYY-mm-dd)
          example: '2025-05-26'
          schema:
            type: string
            format: YYYY-mm-dd
          required: true
      requestBody:
        description: list of timestamps of the user for this day
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Timestamp'
            example:
              - id: 42
                employeeId: 1
                date: 1748256000
                state: 'ON'
                type: WORK
      responses:
        '200':
          description: new list of timestamps for the given day for this employee
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Timestamp'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/info:
    get:
      operationId: get_api_v1_timestamps_info
      tags:
        - timestamp
      summary: gets the timestamp infos for a given time period
      parameters:
        - in: query
          name: from
          description: timestamp of start of period. if omitted,the beginning of the current day will be used
          example: 1748256000
          schema:
            type: integer
            format: timestamp
        - in: query
          name: till
          description: timestamp of end of period. if omitted,the end of the current day will be used
          example: 1748256000
          schema:
            type: integer
            format: timestamp
      responses:
        '200':
          description: a list of timestamp info objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampInfo-With-Changes-Requested'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/statistics:
    get:
      operationId: get_api_v1_timestamps_statistics
      tags:
        - timestamp
      summary: |
        gets the timestamp infos for a given time period (with statistical values)
      description: |
        gets the timestamp infos for a given time period. Also extends misc. statistical values to the response, for example
        infos about documented support, vacation, illness or absences.
      parameters:
        - in: query
          name: from
          description: timestamp of start of period. if omitted,the beginning of the current day will be used
          example: 1748256000
          schema:
            type: integer
            format: timestamp
        - in: query
          name: till
          description: timestamp of end of period. if omitted,the end of the current day will be used
          example: 1748256000
          schema:
            type: integer
            format: timestamp
        - in: query
          name: employeeIds
          description: |
            id of all employees of whom the statistics shall be generated (comma sperated). Important you must have the
            permission to view the statistics for this employee
          example: 1099,2034
          schema:
            type: string
      responses:
        '200':
          description: a list of timestamp info objects (with statistical values)
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampInfo-With-History'
                example:
                  meta:
                    linkedEntities:
                      employees:
                        '1099':
                          initials: TU
                          name: Test user
                    properties:
                      extras:
                        count:
                          value: 2
                    listProperties:
                      workingTimeModels:
                        '0':
                          extras:
                            model:
                              id: 0
                              name: DEFAULT
                              days:
                                WEDNESDAY:
                                  pause: 60
                                  hours:
                                    - workingHourInfoId: 0
                                      number: 1
                                      begin: '0:00'
                                      end: '08:00'
                                      factor: 1
                                    - workingHourInfoId: 0
                                      number: 2
                                      begin: '17:00'
                                      end: '24:00'
                                      factor: 1
                                  beginOfDay:
                                    hrs: 8
                                    mins: 0
                                  endOfDay:
                                    hrs: 17
                                    mins: 0
                                  workTimeInMinutes: 480
                                TUESDAY:
                                  pause: 60
                                  hours:
                                    - workingHourInfoId: 0
                                      number: 1
                                      begin: '0:00'
                                      end: '08:00'
                                      factor: 1
                                    - workingHourInfoId: 0
                                      number: 2
                                      begin: '17:00'
                                      end: '24:00'
                                      factor: 1
                                  beginOfDay:
                                    hrs: 8
                                    mins: 0
                                  endOfDay:
                                    hrs: 17
                                    mins: 0
                                  workTimeInMinutes: 480
                                THURSDAY:
                                  pause: 60
                                  hours:
                                    - workingHourInfoId: 0
                                      number: 1
                                      begin: '0:00'
                                      end: '08:00'
                                      factor: 1
                                    - workingHourInfoId: 0
                                      number: 2
                                      begin: '17:00'
                                      end: '24:00'
                                      factor: 1
                                  beginOfDay:
                                    hrs: 8
                                    mins: 0
                                  endOfDay:
                                    hrs: 17
                                    mins: 0
                                  workTimeInMinutes: 480
                                MONDAY:
                                  pause: 60
                                  hours:
                                    - workingHourInfoId: 0
                                      number: 1
                                      begin: '0:00'
                                      end: '08:00'
                                      factor: 1
                                    - workingHourInfoId: 0
                                      number: 2
                                      begin: '17:00'
                                      end: '24:00'
                                      factor: 1
                                  beginOfDay:
                                    hrs: 8
                                    mins: 0
                                  endOfDay:
                                    hrs: 17
                                    mins: 0
                                  workTimeInMinutes: 480
                                SUNDAY:
                                  pause: 0
                                  hours:
                                    - workingHourInfoId: 0
                                      number: 1
                                      begin: '0:00'
                                      end: '24:00'
                                      factor: 1
                                  workTimeInMinutes: 0
                                FRIDAY:
                                  pause: 60
                                  hours:
                                    - workingHourInfoId: 0
                                      number: 1
                                      begin: '0:00'
                                      end: '08:00'
                                      factor: 1
                                    - workingHourInfoId: 0
                                      number: 2
                                      begin: '17:00'
                                      end: '24:00'
                                      factor: 1
                                  beginOfDay:
                                    hrs: 8
                                    mins: 0
                                  endOfDay:
                                    hrs: 17
                                    mins: 0
                                  workTimeInMinutes: 480
                                SATURDAY:
                                  pause: 0
                                  hours:
                                    - workingHourInfoId: 0
                                      number: 1
                                      begin: '0:00'
                                      end: '24:00'
                                      factor: 1
                                  workTimeInMinutes: 0
                  content:
                    - employeeId: 1099
                      date: '2019-07-19'
                      weekDay: FRIDAY
                      workingTimeModelId: 0
                      timestamps:
                        - id: 140
                          employeeId: 1099
                          date: 1563516356
                          state: 'ON'
                          type: WORK
                      history:
                        - timestampId: 140
                          date: 1565183334
                          changeByUserId: 2
                          fromState: 'OFF'
                          fromType: WORK
                          fromDate: 1563516346
                          toState: 'ON'
                          toType: WORK
                          toDate: 1563516346
                      types:
                        WORK:
                          begin: 1563516356
                          end: 1563573599
                          seconds: 57243
                          state: ONGOING
                        DOCUMENTED_SUPPORT:
                          begin: 1563514200
                          end: 1563525900
                          seconds: 11700
                      editMode: MAY_REQUEST
                      changesRequested:
                        - id: 140
                          employeeId: 1099
                          date: 1563516456
                          state: 'ON'
                          type: WORK
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/dayClosing:
    post:
      operationId: post_api_v1_timestamps_dayClosing
      tags:
        - timestamp - config
      summary: does one or more "day closings" for the timestamp module
      description: |
        "closes" a day by storing the calculated values into the database. This can only
        be done by employees who have access to the selected employee and therefore can execute
        a "day closing" for the timestamp module
      requestBody:
        description: Array of day closing identifiers (each representing the employee and date)
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TimestampDayClosingId'
            example:
              - employeeId: 1
                date: '2025-05-26'
      responses:
        '201':
          description: a list of calculated (and created) timestamps
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampDayClosing'
        '403':
          description: an error occurs if the day closing objects already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage-Error'
    delete:
      operationId: delete_api_v1_timestamps_dayClosing
      tags:
        - timestamp - config
      summary: remove / undo one or more "day closings" for the timestamp module
      description: |
        if calculations have to be re-done (i.e. values have changed), then the "day closing"
        objects have to be re-reated. They have to be deleted first, which can be done via this route.
        After this, they can be created again (via the POST route)
      requestBody:
        description: Array of day closing identifiers (each representing the employee and date)
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TimestampDayClosingId'
            example:
              - employeeId: 1
                date: '2025-05-26'
      responses:
        '204':
          description: a list of deleted timestamps
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampDayClosing'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/dayClosing/tillDate:
    get:
      operationId: get_api_v1_timestamps_dayClosing_tillDate
      tags:
        - timestamp - config
      summary: gets all infos about last dayclosings for employees
      description: |
        This route gets a list of all employees which you have (statistic) access to and return the last dayClosing
        for this employee.

        If the employee doesn't have a dayClosing yet, the date is 0.

        Name of the employees are give in the linked entities.
      responses:
        '200':
          description: a list of day closjng objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampDayClosing'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_timestamps_dayClosing_tillDate
      tags:
        - timestamp - config
      summary: created dayClosings to a given date
      description: |
        This route will create all "missing" dayClosings for a given list of employees till a given date.

        The list of created dayClosing objects will be returned.
      requestBody:
        description: Parameters defining the request (date end list of employees)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimestampDayClosingTillDateParameters'
            example:
              tillDate: '2020-06-17'
              employeeIds:
                - 2
                - 3
                - 103
      responses:
        '201':
          description: a list of created dayClosing objects and errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TimestampDayClosingTillDateResult'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/employee/{employeeId}/initialBalance:
    post:
      operationId: post_api_v1_timestamps_employee_employeeId_initialBalance
      tags:
        - timestamp - config
      summary: sets the initial balance for this employee
      description: |
        When transferring balances from a foreign system, the balance could have an initial
        value. This can be set by using this call.

        Requires the permission to change other employees timestamps directly
      parameters:
        - in: path
          name: employeeId
          description: id of the employee
          example: 5
          schema:
            type: integer
          required: true
      requestBody:
        description: Array of day closing identifiers (each representing the employee and date)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimestampDayClosing-Only-Balance'
      responses:
        '201':
          description: initial value set correctly
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: integer
                    description: initial value (in minutes)
                    example: -60
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/pauseConfigs:
    get:
      operationId: get_api_v1_timestamps_pauseConfigs
      tags:
        - timestamp - config
      summary: gets a list of all pause configs
      description: |
        Defines a configuration for automatical pause subtraction.

        This is needed because longer working periods must contain certain pauses.

        In this section, those pause config objects are maintained.
      responses:
        '200':
          description: list of pause configs
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampPauseConfig'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_timestamps_pauseConfigs
      tags:
        - timestamp - config
      summary: creates a pause config
      requestBody:
        description: pause config object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimestampPauseConfig'
            example:
              id: 42
              minimumPause: 1
      responses:
        '201':
          description: pause object was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TimestampPauseConfig'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/pauseConfigs/{id}:
    put:
      operationId: put_api_v1_timestamps_pauseConfigs_id
      tags:
        - timestamp - config
      summary: updates a pause config
      parameters:
        - in: path
          name: id
          description: id of the pause config
          example: 42
          schema:
            type: integer
          required: true
      requestBody:
        description: pause config object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimestampPauseConfig'
            example:
              id: 42
              minimumPause: 1
      responses:
        '202':
          description: pause object was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TimestampPauseConfig'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_timestamps_pauseConfigs_id
      tags:
        - timestamp - config
      summary: deletes a pause config
      parameters:
        - in: path
          name: id
          description: id of the pause config
          example: 42
          schema:
            type: integer
          required: true
      responses:
        '204':
          description: deleted pause config
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/chats:
    post:
      operationId: post_api_v1_chats
      tags:
        - chats
      summary: Creates a new chat
      description: |
        Creates a new chat in TANSS. The chat must contain at least one participant and one message
      requestBody:
        description: chat object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsChat-Detail'
            example:
              id: 42
              createdByEmployeeId: 1
              creationDate: 1748256000
              description: Example content
              linkTypeId: 1
              linkId: 1
              status: OPEN
              closedByEmployeeId: 1
              expectedResponseTime: 1748256000
      responses:
        '201':
          description: chat was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChat-Detail'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_chats
      tags:
        - chats
      summary: Get a list of chats
      description: |
        Retrieves a list of chats from the database, using misc. filter settings
      requestBody:
        description: filter settings
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsChatConfiguration'
            example:
              chatIds: []
              onlyExpectedTimeExpired: false
              employeeId: 1
              status: OPEN
              searchString: string
              linkTypeId: 1
              linkId: 1
              linkIds: []
              creatorId: 1
              loadMessages: NONE
              fillLinkedEntities: false
              minimumCreationDate: 1748256000
      responses:
        '200':
          description: list of all retrived chats
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsChat-Detail'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/chats/{chatId}:
    get:
      operationId: get_api_v1_chats_chatId
      tags:
        - chats
      summary: Gets a chat
      description: |
        Gets infos for a given chat (inlcuding messages, logs and participants)
      parameters:
        - in: path
          name: chatId
          required: true
          description: Id of the chat to be fetched
          schema:
            type: integer
          example: 1
        - in: query
          name: withMessages
          required: false
          description: If "false" is given here, no messages will be loaded
          schema:
            type: boolean
          example: true
      responses:
        '200':
          description: chat detail information
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChat-Detail'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/chats/closeRequests:
    get:
      operationId: get_api_v1_chats_closeRequests
      tags:
        - chats
      summary: Gets chat close requests
      description: |
        Return the following inforations:
        * Which chats were closed by another employee
        * Which chats were closed and had unread chat messages
      responses:
        '200':
          description: list of chat close requests and list of chats with unread messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      closeRequests:
                        type: array
                        items:
                          $ref: '#/components/schemas/TnsChat'
                      chatsWithUnreadMessages:
                        type: array
                        items:
                          $ref: '#/components/schemas/TnsChat'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/chats/messages:
    post:
      operationId: post_api_v1_chats_messages
      tags:
        - chats
      summary: Creates a new chat message
      description: |
        Creates a new chat message. The message must at least contain the chat id and a content.
      requestBody:
        description: chat message to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsChatMessage-Create'
            example:
              chatId: 1
              content: Example content
              expectedResponse: 1
      responses:
        '201':
          description: message was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChatMessage'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/chats/participants:
    post:
      operationId: post_api_v1_chats_participants
      tags:
        - chats
      summary: Adds a participant
      description: |
        Adds a participant (employee or department) to a chat
      requestBody:
        description: chat participant object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsChatParticipant'
            example:
              chatId: 1
              employeeId: 1
              departmentId: 1
      responses:
        '201':
          description: participant added
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChatParticipant'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_chats_participants
      tags:
        - chats
      summary: Deletes a participant
      description: |
        Deletes a participant (employee or department) from a chat
      parameters:
        - in: query
          name: chatId
          required: true
          description: Id of the chat
          schema:
            type: integer
          example: 1
        - in: query
          name: employeeId
          required: true
          description: Either the id of the employee ...
          schema:
            type: integer
          example: 1
        - in: query
          name: departmentId
          description: ... or the id of the department
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: participant removed
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/chats/close/{chatId}:
    post:
      operationId: post_api_v1_chats_close_chatId
      tags:
        - chats
      summary: Closes a chat
      description: |
        Closes a chat. If the chat is not created by yourself, a close requests is create at first
      parameters:
        - in: path
          name: chatId
          required: true
          description: Id of the chat
          schema:
            type: integer
          example: 1
      responses:
        '201':
          description: chat closed. The actual result is given in the field "status" (either CLOSED or CLOSE_REQUESTED)
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChatCloseResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_chats_close_chatId
      tags:
        - chats
      summary: Accept/decline close request
      description: |
        This routes accepts or declines a chat closing request.

        This can only be done for own chats (created by yourself)
      parameters:
        - in: path
          name: chatId
          required: true
          description: Id of the chat
          schema:
            type: integer
          example: 1
        - in: query
          name: accept
          required: true
          description: true = accept cloe request / false = decline close request
          schema:
            type: boolean
          example: true
      responses:
        '201':
          description: accepted or declined close request
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChatCloseAcceptDeclineResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/chats/reOpen/{chatId}:
    post:
      operationId: post_api_v1_chats_reOpen_chatId
      tags:
        - chats
      summary: re-opens a chat
      description: |
        Re-opens a chat. Can only be done for chats with access and closed chats
      parameters:
        - in: path
          name: chatId
          required: true
          description: Id of the chat
          schema:
            type: integer
          example: 1
      responses:
        '201':
          description: chat re-opened.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChatReOpenResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/erpSelections:
    post:
      operationId: post_api_v1_offers_erpSelections
      tags:
        - erp selections
      summary: Creates a new erp selection
      description: |
        Creates a new erp selection which is used in offer templates.
        This erp selection contains all materials to be saved as well
      requestBody:
        description: erp selection to be saved (including materials)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsOfferErpSelection'
            example:
              id: 42
              variableName: string
              prompt: string
      responses:
        '201':
          description: erp selection was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsOfferErpSelection'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/erpSelections/{erpSelectionId}:
    get:
      operationId: get_api_v1_offers_erpSelections_erpSelectionId
      tags:
        - erp selections
      summary: Fetches an erp selection
      description: |
        Fetches information regarding a specific erp selection (including material)
      parameters:
        - in: path
          name: erpSelectionId
          required: true
          description: Id of the erp selection to be fetched
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: erp selection object
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsOfferErpSelection'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_offers_erpSelections_erpSelectionId
      tags:
        - erp selections
      summary: Updates an erp selection
      description: |
        Updates an erp selection and saves all attached materials as well
      parameters:
        - in: path
          name: erpSelectionId
          required: true
          description: Id of the erp selection to be updated
          example: 42
          schema:
            type: integer
      requestBody:
        description: erp selection to be saved (including materials)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsOfferErpSelection'
            example:
              id: 42
              variableName: string
              prompt: string
      responses:
        '202':
          description: updated erp selection object
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsOfferErpSelection'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_offers_erpSelections_erpSelectionId
      tags:
        - erp selections
      summary: Deletes an erp selection
      description: Deletes an erp selection
      parameters:
        - in: path
          name: erpSelectionId
          required: true
          description: Id of the erp selection to be deleted
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Deleted erp selection
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/templates:
    get:
      operationId: get_api_v1_offers_templates
      tags:
        - offer templates
      summary: Gets list of offer templates
      description: |
        This route gets a list of all offer termplates
      responses:
        '200':
          description: list of offer templates
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsOfferTemplate'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_offers_templates
      tags:
        - offer templates
      summary: Creates an offer template
      description: |
        Creates a new offer template
      requestBody:
        description: offer templates
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsOfferTemplate'
            example:
              id: 42
              name: Example name
              creationDate: 1748256000
              createdByEmployeeId: 1
              previousId: 1
              validInDays: 1
      responses:
        '201':
          description: offer template was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsOfferTemplate'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/templates/{templateId}:
    get:
      operationId: get_api_v1_offers_templates_templateId
      tags:
        - offer templates
      summary: Gets an offer templates
      description: |
        This route gets a detailled view of an offer template
      parameters:
        - in: path
          name: templateId
          required: true
          description: Id of the offer template
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: list of offer templates
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsOfferTemplate-Vars'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_offers_templates_templateId
      tags:
        - offer templates
      summary: Updates an offer templates
      description: |
        This route updates an offer template
      parameters:
        - in: path
          name: templateId
          required: true
          description: Id of the offer template
          example: 1
          schema:
            type: integer
      requestBody:
        description: offer template
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsOfferTemplate'
            example:
              id: 42
              name: Example name
              creationDate: 1748256000
              createdByEmployeeId: 1
              previousId: 1
              validInDays: 1
      responses:
        '202':
          description: updatet offer template
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsOfferTemplate'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_offers_templates_templateId
      tags:
        - offer templates
      summary: Deletes an offer template
      description: Deletes an offer template
      parameters:
        - in: path
          name: templateId
          required: true
          description: Id of the offer template to be deleted
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Deleted offer template
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/erpSelections/matPicker:
    get:
      operationId: get_api_v1_offers_erpSelections_matPicker
      tags:
        - erp selections
      summary: material picker
      description: |
        This route gets a list of materials for the "material picker" which is used to fill material in an "erp selection"
      parameters:
        - in: query
          name: searchText
          description: if result should be filtered, the search text goes here
          example: Festplatte
          schema:
            type: string
        - in: query
          name: source
          required: true
          description: determines the source for this picker
          example: TANSS
          schema:
            $ref: '#/components/schemas/TnsOfferErpSelectionMaterialSource'
      responses:
        '200':
          description: list of materials
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsMaterial'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/erpSelections/matPicker/{erpSelectionId}:
    get:
      operationId: get_api_v1_offers_erpSelections_matPicker_erpSelectionId
      tags:
        - erp selections
      summary: material picker for erp selection
      description: |
        This route gets a list of materials for the "material picker" which is used to fill material in an "erp selection"
      parameters:
        - in: path
          name: erpSelectionId
          required: true
          description: Id of the erp selection
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: list of materials for an erp selection
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsMaterial-With-Source'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers:
    put:
      operationId: put_api_v1_offers
      tags:
        - offer
      summary: Gets list of offers
      requestBody:
        description: filter settings for the offer list
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsOfferConfiguration'
            example:
              companyId: 1
              templateId: 1
      description: |
        This route gets a list of offers (by a given filter, trasmitted in the request body)
      responses:
        '200':
          description: offer created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsOffer-List'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_offers
      tags:
        - offer
      summary: Creates an offer
      description: |
        This route creates a new offer
      requestBody:
        description: offer object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsOffer-Details'
            example:
              id: 42
              name: Example name
              date: 1748256000
              createdByEmployeeId: 1
              linkTypeId: 1
              linkId: 1
              validTill: 1
      responses:
        '201':
          description: offer created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsOffer-Details'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offer/{offerId}:
    get:
      operationId: get_api_v1_offer_offerId
      tags:
        - offer
      summary: Gets an offer
      description: |
        This route gets a detailled view of an offer (including vars and material)
      parameters:
        - in: path
          name: offerId
          required: true
          description: Id of the offer
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: offer details
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsOffer-Details'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_offer_offerId
      tags:
        - offer
      summary: Updates an offer
      description: |
        This route updates an offer (including vars and material)
      parameters:
        - in: path
          name: offerId
          required: true
          description: Id of the offer
          example: 1
          schema:
            type: integer
      requestBody:
        description: offer object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsOffer-Details'
            example:
              id: 42
              name: Example name
              date: 1748256000
              createdByEmployeeId: 1
              linkTypeId: 1
              linkId: 1
              validTill: 1
      responses:
        '202':
          description: updatet offer
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsOffer-Details'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_offer_offerId
      tags:
        - offer
      summary: Deletes an offer
      description: Deletes an offer
      parameters:
        - in: path
          name: offerId
          required: true
          description: Id of the offer to be deleted
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Deleted offer
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/availability:
    get:
      operationId: get_api_v1_availability
      tags:
        - availability
      summary: Fetches availability infos
      description: |
        This requests fetches information about employee availability
      parameters:
        - in: query
          name: employeeIds
          required: true
          description: Ids of the employees (comma separated)
          example: 5,6,7
          schema:
            type: string
      responses:
        '200':
          description: availability infos, one per employee
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsAvailabilityInfo'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/technicians:
    get:
      operationId: get_api_v1_employees_technicians
      tags:
        - employees
      summary: Gets all technicians
      description: |
        Gets all technicians of this system.

        Needs to be a technician or freelancer in order to view this list
      parameters:
        - in: query
          name: freelancerCompanyId
          required: false
          description: If this parameter is given, also fetches the freelancers of this company (0 if all freelancers shall be retrieved)
          schema:
            type: integer
          example: 100023
      responses:
        '200':
          description: list of technicians (or freelancers)
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee-Short'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/test/smtp:
    post:
      operationId: post_api_v1_mails_test_smtp
      tags:
        - email settings
      summary: Test email smtp settings
      description: |
        Route for testing smtp server settings. This route sends a mail to the specified receiver.

        Need the permission to access the OSK in order to use this route.
      requestBody:
        description: email settings object to be used for sending
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsEmailSettings-Smtp'
            example:
              smtpAddress: string
              smtpHost: string
              smtpUser: string
              smtpPassword: '********'
              smtpAuth: false
              smtpEncryptionType: NONE
              smtpSenderName: string
      parameters:
        - in: query
          name: receiver
          description: receiver of the test message
          required: true
          schema:
            type: string
          example: empfaenger@example.com
      responses:
        '201':
          description: mail successfully sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsEmailSettings-Smtp'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tags:
    post:
      operationId: post_api_v1_tags
      tags:
        - tags
      summary: Creates a new tag
      description: |
        Creates a new tag.

        Must have the permission to manage tags in the system in order to use this route!
      requestBody:
        description: tag object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTag-Without-GroupTag'
            example:
              id: 42
              name: Example name
              backgroundColor: '#0044d4'
              fontColor: '#0044d4'
              description: Example content
              image: string
              groupTagId: 1
              groupTagInheritance: false
      responses:
        '201':
          description: tag was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTag'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_tags
      tags:
        - tags
      summary: Get all tags
      description: |
        Gets a list of all tags

        Must be technician or freelancer in order to use this route!
      responses:
        '200':
          description: tag list
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTag'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tags/{id}:
    get:
      operationId: get_api_v1_tags_id
      tags:
        - tags
      summary: Gets a tag
      description: |
        Gets an existing tag.
      parameters:
        - in: path
          name: id
          required: true
          description: id of the tag
          schema:
            type: integer
          example: 7
      responses:
        '200':
          description: tag was successfully fetched
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTag'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tags_id
      tags:
        - tags
      summary: Edits a tag
      description: |
        Edits an existing tag.

        Must have the permission to manage tags in the system in order to use this route!
      requestBody:
        description: tag object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTag'
            example:
              id: 42
              name: Example name
              backgroundColor: '#0044d4'
              fontColor: '#0044d4'
              description: Example content
              image: string
              groupTagId: 1
              groupTagInheritance: false
      parameters:
        - in: path
          name: id
          required: true
          description: id of the tag
          schema:
            type: integer
          example: 7
      responses:
        '202':
          description: tag was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTag'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_tags_id
      tags:
        - tags
      summary: Deletes a tag
      description: |
        Deletes an existing tag.

        Must have the permission to manage tags in the system in order to use this route!
      parameters:
        - in: path
          name: id
          required: true
          description: id of the tag to be deleted
          schema:
            type: integer
          example: 7
      responses:
        '204':
          description: tag was successfully deleted
        '404':
          description: tag not found
  /api/v1/tags/groups/{id}:
    get:
      operationId: get_api_v1_tags_groups_id
      tags:
        - tags
      summary: List tags in a group
      description: |
        Returns all tags that belong to the given group tag.

        A *group tag* is a tag that acts as a parent — useful for organising tags
        by topic (e.g. priority, customer-type, hardware-class). This endpoint
        returns the children of one such group.
      parameters:
        - in: path
          name: id
          required: true
          description: id of the parent (group) tag
          schema:
            type: integer
          example: 7
      responses:
        '200':
          description: list of tags in the group
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTag'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tags/selection/{linkType}:
    put:
      operationId: put_api_v1_tags_selection_linkType
      tags:
        - tags
      summary: Get tags applicable to a selection
      description: |
        Given a `linkType` (ticket, device, etc.) and a list of entity ids in the
        request body, returns the tags that are *applicable* to that selection —
        typically the tags currently shared by all selected entities and/or the
        tags that can still be added to them.

        Uses `PUT` rather than `GET` because the selection (the list of entity
        ids) is sent in the request body.
      parameters:
        - in: path
          name: linkType
          required: true
          description: the entity type the selection refers to (`TICKET`, `DEVICE`, …)
          schema:
            type: string
            enum:
              - TICKET
              - COMPANY
              - EMPLOYEE
              - DEVICE
          example: TICKET
      requestBody:
        description: selection payload — the list of entity ids to evaluate
        required: true
        content:
          application/json:
            schema:
              type: object
              description: |
                Implementation-specific selection object. Typically contains an
                array of ids (`ticketIds`, `deviceIds`, …) and optional filter
                flags — verify the exact shape against the schema.
            example:
              text: Example content
              extras: {}
              linkedEntities: {}
              assignments:
                infos: {}
              properties:
                fields: {}
                extras: {}
                permissions: {}
                editable: false
                message: Example content
              pagination:
                itemsPerPage: 1
                totalItems: 1
                page: 1
              listProperties: {}
      responses:
        '200':
          description: list of tags applicable to the given selection
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTag'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tags/assignment:
    post:
      operationId: post_api_v1_tags_assignment
      tags:
        - tags
      summary: Assigns a tag
      description: |
        Assigns a tag to an entity.

        Must be technician/freelancer and have access to the assignment!
      requestBody:
        description: tag assignment object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTagAssignment'
            example:
              tagId: 1
              linkTypeId: 1
              linkId: 1
      responses:
        '201':
          description: tag was successfully assigned
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTagAssignment'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_tags_assignment
      tags:
        - tags
      summary: Removes a tag
      description: |
        Removes a tag from an assignment.

        Must be technician/freelancer and have access to the assignment!
      parameters:
        - in: query
          name: tagId
          required: true
          description: id of the tag
          schema:
            type: integer
          example: 7
        - in: query
          name: linkTypeId
          required: true
          description: linkType of the assignment
          schema:
            type: integer
          example: 1
        - in: query
          name: linkId
          required: true
          description: id of the assignment
          schema:
            type: integer
          example: 4711
      responses:
        '204':
          description: tag was successfully removed
        '404':
          description: assignment not found
    get:
      operationId: get_api_v1_tags_assignment
      tags:
        - tags
      summary: List of tags to an assignment
      description: |
        Gets alist of all tags who are assigned to an entity (for example ticket).

        Must be technician/freelancer and have access to the assignment!
      parameters:
        - in: query
          name: linkTypeId
          required: true
          description: linkType of the assignment
          schema:
            type: integer
          example: 1
        - in: query
          name: linkId
          required: true
          description: id of the assignment
          schema:
            type: integer
          example: 4711
      responses:
        '200':
          description: list of assigned tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTag'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tags_assignment
      tags:
        - tags
      summary: Assigns multiple tags
      description: |
        Assigns multiplke tags at one for a specific device/assignment. All tag ids are given.

        The system automatically determines wbhich of those tags shall be created or removed.

        Must be technician/freelancer and have access to the assignment!
      requestBody:
        description: tag assignment object
        required: true
        content:
          application/json:
            schema:
              description: ids of all tags in for this device/assignment
              type: array
              items:
                type: integer
              example:
                - 1
                - 20
                - 45
      parameters:
        - in: query
          name: linkTypeId
          required: true
          description: linkType of the assignment
          schema:
            type: integer
          example: 1
        - in: query
          name: linkId
          required: true
          description: id of the assignment
          schema:
            type: integer
          example: 4711
      responses:
        '201':
          description: tags were successfully assigned or remove. Returns a list with the new tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTag'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tags/assignments:
    delete:
      operationId: delete_api_v1_tags_assignments
      tags:
        - tags
      summary: Remove all tag assignments from an entity
      description: |
        Bulk-removes every tag assignment from the given entity in one call.
        Use this when you want to clear all tags from a ticket / device / etc.
        rather than removing individual assignments via
        `DELETE /api/v1/tags/assignment`.

        Must be a technician or freelancer with access to the assignment.
      parameters:
        - in: query
          name: linkTypeId
          required: true
          description: linkType of the assignment (numeric id, e.g. 1 = ticket)
          schema:
            type: integer
          example: 1
        - in: query
          name: linkId
          required: true
          description: id of the entity whose tag assignments should be cleared
          schema:
            type: integer
          example: 4711
      responses:
        '204':
          description: all tag assignments were successfully removed
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tags/assignment/log:
    get:
      operationId: get_api_v1_tags_assignment_log
      tags:
        - tags
      summary: List of tags logs to an assignment
      description: |
        Gets alist of all tag logs to an entity (for example ticket). Here you can see when tags habe been assigned or removed.

        Must be technician/freelancer and have access to the assignment!
      parameters:
        - in: query
          name: linkTypeId
          required: true
          description: linkType of the assignment
          schema:
            type: integer
          example: 1
        - in: query
          name: linkId
          required: true
          description: id of the assignment
          schema:
            type: integer
          example: 4711
      responses:
        '200':
          description: list of assigned tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTagLog'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/callbacks:
    post:
      operationId: post_api_v1_callbacks
      tags:
        - callback
      summary: Creates a callback
      description: |
        Creates a new callback in TANSS
      requestBody:
        description: callback object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsCallback'
            example:
              fromEmployeeId: 1
              toEmployeeId: 1
              toDepartmentId: 1
              date: 1748256000
              companyId: 1
              companyName: Example GmbH
              employeeId: 1
              employeeName: string
              phoneNumber: +49 30 1234567
              info: string
              state: UNSEEN
              priority: 2
              callbackAfterTime: 1748256000
              callbackUntilTime: 1748256000
              linkTypeId: 1
              linkId: 1
      responses:
        '201':
          description: callback was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsCallback'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_callbacks
      tags:
        - callback
      summary: Get a list of callbacks
      description: |
        Retrieves a list of callback from the database, using misc. filter settings
      requestBody:
        description: filter settings
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsCallbackConfiguration'
            example:
              timeframe:
                from: 1
                to: 1
              state: UNSEEN
              states: []
              fromEmployeeId: 1
              toEmployeeId: 1
              toAllEmployeesWithAccessTo: false
              toDepartmentIds: 1
              companyIds: 1
              employeeIds: 1
              loadLinkedEntites: false
              withLog: false
      responses:
        '200':
          description: list of all retrived callbacks
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsCallback-With-Log'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/callbacks/{callbackId}:
    get:
      operationId: get_api_v1_callbacks_callbackId
      tags:
        - callback
      summary: Gets a callback
      description: |
        Gets a single callback
      parameters:
        - in: path
          name: callbackId
          required: true
          description: Id of the callback to be fetched
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: callbacks was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsCallback-With-Log'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_callbacks_callbackId
      tags:
        - callback
      summary: Updates a callback
      description: |
        Updates a callback
      parameters:
        - in: path
          name: callbackId
          required: true
          description: Id of the callback to be updated
          example: 1
          schema:
            type: integer
      requestBody:
        description: callback object to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsCallback'
            example:
              fromEmployeeId: 1
              toEmployeeId: 1
              toDepartmentId: 1
              date: 1748256000
              companyId: 1
              companyName: Example GmbH
              employeeId: 1
              employeeName: string
              phoneNumber: +49 30 1234567
              info: string
              state: UNSEEN
              priority: 2
              callbackAfterTime: 1748256000
              callbackUntilTime: 1748256000
              linkTypeId: 1
              linkId: 1
      responses:
        '201':
          description: callbacks was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsCallback-With-Log'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/search:
    put:
      operationId: put_api_v1_search
      tags:
        - search
      summary: global search
      description: |
        Executes a global search, defined via the configuration object in the request body
      requestBody:
        description: defines the search parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSearchConfiguration'
            example:
              areas:
                - COMPANY
              query: example
              configs:
                company: {}
                employee: {}
                ticket: {}
      responses:
        '200':
          description: search result
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSearchResult'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists:
    get:
      operationId: get_api_v1_checklists
      tags:
        - checklists
      summary: Gets a list of selectable checklists
      description: |
        This route will get all checklists that can be selected i.e. to be assigned to a ticket
      parameters:
        - in: query
          name: companyId
          required: false
          description: (optional) company id to filter the checklists
          example: 1
          schema:
            type: integer
        - in: query
          name: departmentId
          required: false
          description: (optional) department id to filter the checklists
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: list of checklists
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsChecklist-Small'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists/assignment/{linkTypeId}/{linkId}/{checklistId}:
    post:
      operationId: post_api_v1_checklists_assignment_linkTypeId_linkId_checklistId
      tags:
        - checklists
      summary: Assigns a checklist to a ticket
      description: |
        This route will assign a checklist to a ticket
      parameters:
        - in: path
          name: linkTypeId
          required: true
          description: linkTypeId (11 = ticket)
          example: 1
          schema:
            type: integer
        - in: path
          name: linkId
          required: true
          description: id of the ticket
          example: 4711
          schema:
            type: integer
        - in: path
          name: checklistId
          required: true
          description: id of the checklist
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: checklist assigned correctly
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChecklist-With-Assignment-Infos'
        '404':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_checklists_assignment_linkTypeId_linkId_checklistId
      tags:
        - checklists
      summary: Removes a checklist from a ticket
      description: |
        This route will remove a checklist checklist assignment from a ticket
      parameters:
        - in: path
          name: linkTypeId
          required: true
          description: linkTypeId (11 = ticket)
          example: 1
          schema:
            type: integer
        - in: path
          name: linkId
          required: true
          description: id of the ticket
          example: 4711
          schema:
            type: integer
        - in: path
          name: checklistId
          required: true
          description: id of the checklist
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: checklist was removed correctly
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists/assignment/{linkTypeId}/{linkId}:
    get:
      operationId: get_api_v1_checklists_assignment_linkTypeId_linkId
      tags:
        - checklists
      summary: Gets checklists for a ticket
      description: |
        This route will get all checklists for a specific assignment (i.e. ticket)
      parameters:
        - in: path
          name: linkTypeId
          required: true
          description: linkTypeId (11 = ticket)
          example: 1
          schema:
            type: integer
        - in: path
          name: linkId
          required: true
          description: id of the ticket
          example: 4711
          schema:
            type: integer
      responses:
        '200':
          description: list of assigned checklists
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsChecklist-With-Assignment-Infos'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists/{checklistId}/process:
    get:
      operationId: get_api_v1_checklists_checklistId_process
      tags:
        - checklists
      summary: Gets checklist for ticket
      description: |
        This route will be used for processing a checklist.

        It will fetch the checklist, along with all the values for the current assignment (i.e. ticket).

        If you want to process checklist, this is the main part for fetching all neccessary infos.
      parameters:
        - in: path
          name: checklistId
          required: true
          description: id of the checklist
          example: 1
          schema:
            type: integer
        - in: query
          name: linkTypeId
          required: true
          description: linkTypeId (11 = ticket)
          example: 1
          schema:
            type: integer
        - in: query
          name: linkId
          required: true
          description: id of the ticket
          example: 4711
          schema:
            type: integer
      responses:
        '200':
          description: detailled infos for the checklist withing the ticket
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChecklist-With-Process-Infos'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists/check:
    put:
      operationId: put_api_v1_checklists_check
      tags:
        - checklists
      summary: Check an item
      description: |
        This route will check (or uncheck) an item in a checklist
      requestBody:
        description: infos regarding the item to be checked
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsChecklistItemCheckBody'
            example:
              checklistId: 1
              itemId: 1
              mainChecklistId: 1
              linkTypeId: 1
              linkId: 1
              value: 1
              multiSelectId: 1
              vars: {}
      responses:
        '200':
          description: item checked
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsChecklist-With-Process-Infos'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/list:
    put:
      operationId: put_api_v1_supports_list
      tags:
        - supports
      summary: Get a support list
      requestBody:
        description: query parameters for retrieving supports
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSupportConfiguration'
            example:
              supportLocations: []
              timeframe:
                from: 1
                to: 1
              supportIconTypes: []
              employees: []
              internalSupport: ALL
              companyCategories: []
              companyCategoriesMatchType: AND
              excludeOwnCompany: false
      responses:
        '200':
          description: a list of support entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsSupport'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports:
    post:
      operationId: post_api_v1_supports
      tags:
        - supports
      summary: Creates a support/appointment
      requestBody:
        description: support object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSupport-Create'
            example:
              id: 42
              linkTypeId: 1
              linkId: 1
              companyId: 1
              remitterId: 1
              employeeId: 1
              typeId: 1
              date: 1748256000
              duration: 3600
              durationNotCharged: 3600
              reasonNotChargedText: Example content
              text: Example content
              booked: false
              erpNumber: string
              internal: false
              location: OFFICE
              durationApproach: 3600
              kmApproach: 1
              durationDeparture: 3600
              kmDeparture: 1
              ticketId: 1
      responses:
        '200':
          description: the create support/appointment
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSupport'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/{supportId}:
    get:
      operationId: get_api_v1_supports_supportId
      tags:
        - supports
      summary: Gets a support/appointment
      parameters:
        - in: path
          name: supportId
          required: true
          schema:
            type: integer
          description: id of the support that shall be fetched
          example: 5004
      responses:
        '200':
          description: the support/appointment
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSupport'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_supports_supportId
      tags:
        - supports
      summary: Edits a support/appointment
      parameters:
        - in: path
          name: supportId
          required: true
          schema:
            type: integer
          description: id of the support that shall be updated
          example: 5004
      requestBody:
        description: support object to be saved. The best way is only to give the fields that have changed.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSupport'
            example:
              id: 42
              linkTypeId: 1
              linkId: 1
              companyId: 1
              employeeId: 1
              typeId: 1
              date: 1748256000
              duration: 3600
              durationNotCharged: 3600
              reasonNotChargedText: Example content
              text: Example content
              booked: false
              erpNumber: string
              internal: false
              location: OFFICE
              durationApproach: 3600
              kmApproach: 1
              durationDeparture: 3600
              kmDeparture: 1
              ticketId: 1
      responses:
        '201':
          description: the updated support/appointment
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSupport'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/signature/{supportId}:
    post:
      operationId: post_api_v1_supports_signature_supportId
      tags:
        - supports
      summary: Uploads a signature for supports
      parameters:
        - in: path
          name: supportId
          required: true
          schema:
            type: integer
          description: id of the support that the signature shall be uploaded
          example: 5004
        - in: query
          name: supportIds
          required: false
          schema:
            type: string
          description: if the signature is used for multiple supports, give them here (separated by commas)
          example: 5004,5005,5006
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - signature
              properties:
                signature:
                  type: string
                  format: binary
                  description: REQUIRED! binary data of the uploaded signature (must be JPG or PNG)
      responses:
        '201':
          description: created signature objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsSupportSignature'
              example:
                meta: {}
                content:
                  - supportId: 5004
                    itemNumber: 1
                    date: 1748256000
                    employeeId: 5
                    accumulated: false
                  - supportId: 5005
                    itemNumber: 1
                    date: 1748256000
                    employeeId: 5
                    accumulated: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supportTypes:
    get:
      operationId: get_api_v1_supportTypes
      tags:
        - supportTypes
      summary: Gets all support types
      responses:
        '200':
          description: list of all support types
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsSupportType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_supportTypes
      tags:
        - supportTypes
      summary: Creates a support type
      requestBody:
        description: support type object to be saved.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSupportType'
            example:
              id: 42
              name: Example name
              hidden: false
              notCharged: false
              notChargedReasonId: 1
              description: Example content
      responses:
        '201':
          description: the created support type object
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSupportType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supportTypes/{id}:
    get:
      operationId: get_api_v1_supportTypes_id
      tags:
        - supportTypes
      summary: Gets a support type by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: id of the support type that shall be fetched
          example: 42
      responses:
        '200':
          description: the support type with the given id
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSupportType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_supportTypes_id
      tags:
        - supportTypes
      summary: Updates a support type
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: id of the support type that shall be updated
          example: 42
      requestBody:
        description: support type object to be updated.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSupportType'
            example:
              id: 42
              name: Example name
              hidden: false
              notCharged: false
              notChargedReasonId: 1
              description: Example content
      responses:
        '201':
          description: the created support type object
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSupportType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_supportTypes_id
      tags:
        - supportTypes
      summary: Deletes a support type
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: id of the support type that shall be deleted
          example: 42
      responses:
        '204':
          description: support type deleted successfully
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supportTypes/active:
    get:
      operationId: get_api_v1_supportTypes_active
      tags:
        - supportTypes
      summary: Gets all active support types
      responses:
        '200':
          description: list of all active support types
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsSupportType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard:
    get:
      operationId: get_api_v1_ticketBoard
      tags:
        - ticket board
      summary: Gets the ticket board with all panels
      description: |
        Returns the calling employee's ticket board: every panel they own (`ONLY_FOR_MYSELF`) plus every global panel (`EVERYBODY`) for which their department, employee assignment, or company-type membership matches the panel's visibility scope. Each panel comes with its linked-entity decorations (employees, departments, tags, ...) already resolved.
      responses:
        '200':
          description: ticket board
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    $ref: '#/components/schemas/TnsTicketBoard'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/panel:
    get:
      operationId: get_api_v1_ticketBoard_panel
      tags:
        - ticket board
      summary: Gets an empty ticket board panel
      description: |
        Returns a blank object skeleton used by the UI as the starting point for creating a new panel. When `mode=edit` is passed, the response is additionally enriched with all assignable companies, departments, employees, tags, ticket types and statuses so the editor can populate its selectors in one round-trip.
      parameters:
        - in: query
          name: mode
          description: If mode = "edit" you get all possible employees, departments, tags, ticket types and tickets status which can be assigned
          schema:
            type: string
          example: edit
      responses:
        '200':
          description: ticket board retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    $ref: '#/components/schemas/TnsTicketBoardPanel'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_ticketBoard_panel
      tags:
        - ticket board
      summary: Creates a new ticket board panel
      description: |
        Creates a new ticket board panel owned by the calling employee (`employeeId` is forced to the session user, `created`/`modified` are stamped server-side). `name` and `registerType` are required; the supplied filter row is persisted alongside the panel and the ticket board cache is cleared. Requires the `CREATE_OWN_TICKET_BOARD_PANELS` permission.
      requestBody:
        description: Ticket board panel
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTicketBoardPanel'
            example:
              id: 42
              name: Example name
              projectId: 1
              employeeId: 1
              panelType: DEFAULT
              registerType: NONE
              includeProjects: false
              includeSubTickets: false
              includeWaitingStates: false
              visibility: ONLY_FOR_MYSELF
              companies:
                - panelId: 1
                  companyId: 1
              employees:
                - panelId: 1
                  employeeId: 1
              departments:
                - panelId: 1
                  departmentId: 1
              tags:
                - panelId: 1
                  tagId: 1
              ticketTypes:
                - panelId: 1
                  typeId: 1
              ticketStatus:
                - panelId: 1
                  statusId: 1
      responses:
        '201':
          description: ticket board created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    $ref: '#/components/schemas/TnsTicketBoardPanel'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_ticketBoard_panel
      tags:
        - ticket board
      summary: Updates a ticket board panel
      description: |
        Updates an existing ticket board panel and re-syncs its scoped relations (companies, departments, employees, tags, ticket types/status, visibilities). Non-administrators may only update panels they own; `modified` is stamped server-side and the ticket board cache is invalidated.
      requestBody:
        description: Ticket board panel
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTicketBoardPanel'
            example:
              id: 42
              name: Example name
              projectId: 1
              employeeId: 1
              panelType: DEFAULT
              registerType: NONE
              includeProjects: false
              includeSubTickets: false
              includeWaitingStates: false
              visibility: ONLY_FOR_MYSELF
              companies:
                - panelId: 1
                  companyId: 1
              employees:
                - panelId: 1
                  employeeId: 1
              departments:
                - panelId: 1
                  departmentId: 1
              tags:
                - panelId: 1
                  tagId: 1
              ticketTypes:
                - panelId: 1
                  typeId: 1
              ticketStatus:
                - panelId: 1
                  statusId: 1
      responses:
        '202':
          description: ticket board updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    $ref: '#/components/schemas/TnsTicketBoardPanel'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/panel/{id}:
    get:
      operationId: get_api_v1_ticketBoard_panel_id
      tags:
        - ticket board
      summary: Gets a ticket board panel
      description: |
        Returns a single ticket board panel by id, with its transient relations and linked entities populated. Access is granted to administrators, the panel's owner, and (for global panels) any user that passes the ticket board access check. When `mode=edit` is supplied the response also includes the catalogues of assignable companies/departments/employees/tags/ticket types/status.
      parameters:
        - in: path
          name: id
          description: Panel id
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: ticket board panel
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    $ref: '#/components/schemas/TnsTicketBoardPanel'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_ticketBoard_panel_id
      tags:
        - ticket board
      summary: Deletes a ticket board panel
      description: |
        Deletes a ticket board panel along with its scoped relations and per-user filter rows. Non-administrators may only delete panels they own; the change is logged and the ticket board cache is cleared.
      parameters:
        - in: path
          name: id
          description: Panel id
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: Deleted successfully
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/panel/{id}/registers:
    get:
      operationId: get_api_v1_ticketBoard_panel_id_registers
      tags:
        - ticket board
      summary: Gets all registers from a ticket board panel
      description: |
        Returns the panel's registers — the column groupings shown inside the panel (e.g. one register per ticket status, type, tag or project phase, depending on `registerType`) together with the tickets currently assigned to each register, already filtered by the calling employee's panel filter. The optional `registerType` query parameter can override the panel's configured register type.
      parameters:
        - in: path
          name: id
          description: Panel id
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: ticket board registers
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    $ref: '#/components/schemas/TnsTicketBoardPanelRegisters'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/project/{id}:
    get:
      operationId: get_api_v1_ticketBoard_project_id
      tags:
        - ticket board
      summary: Gets a ticket board from a project
      description: |
        Returns a project-scoped ticket board: a object containing exactly one synthesised panel built from the given project (panel type `PROJECT`, register type `PROJECT_PHASE`, named `#projectId - ticketName`). Used by the project view to show that project's tickets grouped by phase without persisting a real panel row.
      parameters:
        - in: path
          name: id
          description: Project id
          required: true
          schema:
            type: integer
          example: 900
      responses:
        '200':
          description: ticket board
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    $ref: '#/components/schemas/TnsTicketBoard'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/project/{id}/registers:
    get:
      operationId: get_api_v1_ticketBoard_project_id_registers
      tags:
        - ticket board
      summary: Gets all registers from a ticket board project
      description: |
        Returns the registers for the project's synthesised ticket board panel (`registerType = PROJECT_PHASE`): one register per project phase with all of that project's tickets grouped accordingly. Tickets are filtered through the calling employee's filter for this synthetic panel.
      parameters:
        - in: path
          name: id
          description: Project id
          required: true
          schema:
            type: integer
          example: 900
      responses:
        '200':
          description: ticket board registers
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    $ref: '#/components/schemas/TnsTicketBoardPanelRegisters'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/project/globalPanels:
    get:
      operationId: get_api_v1_ticketBoard_project_globalPanels
      tags:
        - ticket board
      summary: Get global ticket panels
      description: |
        Returns every ticket board panel with visibility `EVERYBODY` — the shared "tenant-wide" panels available to all users. The same data as `/api/v1/ticketBoard/globalPanels`; this variant lives under the `ticketBoard` project path and is used by the project-board view to render the global panels alongside the project-specific board.
      responses:
        '200':
          description: list of global panels
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTicketBoardPanel'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timers:
    get:
      operationId: get_api_v1_timers
      tags:
        - timers
      summary: Get all timers of current user
      description: This route will get all timers of the currently logged in user
      responses:
        '200':
          description: list of timers
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Timer'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_timers
      tags:
        - timers
      summary: Creates a timer
      description: This route will create a timer for the currently logged in user
      responses:
        '201':
          description: timer was created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Timer'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_timers
      tags:
        - timers
      summary: Deletes a timer
      description: This route will delete a timer
      requestBody:
        description: timer object to be deleted. The only important field is the "id"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Timer'
            example:
              id: 42
              employeeId: 1
              companyId: 1
              title: Example title
              duration: 3600
              callbackId: 1
              ticketId: 1
              linkTypeId: 1
              linkId: 1
      responses:
        '204':
          description: timer was delete
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timers/{timerId}:
    get:
      operationId: get_api_v1_timers_timerId
      tags:
        - timers
      summary: Get a specific timer
      description: This route will get a specific timer, given by an id
      parameters:
        - in: path
          name: timerId
          required: true
          description: Id of the timer.
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: single timer object
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Timer'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_timers_timerId
      tags:
        - timers
      summary: Starts/stops timer
      description: This route will either start or stop a timer
      parameters:
        - in: path
          name: timerId
          required: true
          description: Id of the timer.
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: single timer object of the given timer that was started or stopped
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Timer'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timers/notes/{timerId}:
    get:
      operationId: get_api_v1_timers_notes_timerId
      tags:
        - timers
      summary: Get all timer fragments
      description: This route will get all timer fragments of a given timer (start- / stop-dates)
      parameters:
        - in: path
          name: timerId
          description: id of the timer
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: timer fragments
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimerFragment'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timers/notes:
    delete:
      operationId: delete_api_v1_timers_notes
      tags:
        - timers
      summary: Deletes a timer fragment
      description: This route will delete a timer fragment
      requestBody:
        description: timer fragment to be deleted. The only important field is the "startTime" and "timerId"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimerFragment'
            example:
              timerId: 1748256000
              startTime: 1748256000
              stopTime: 1748256000
              note: example
      responses:
        '204':
          description: delete operation succeful
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_timers_notes
      tags:
        - timers
      summary: Updates a timer fragment
      description: This route will update a timer fragment and is used to store / update a "note" in the fragment
      requestBody:
        description: timer fragment to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimerFragment'
            example:
              timerId: 1748256000
              startTime: 1748256000
              stopTime: 1748256000
              note: example
      responses:
        '202':
          description: fragment was updates successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TimerFragment'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/pcs/{pcId}:
    get:
      operationId: get_api_v1_pcs_pcId
      tags:
        - pc
      summary: Gets a pc by id
      description: Fetches a pc or server by a given id
      parameters:
        - in: path
          name: pcId
          description: ID of the pc or server to fetch.
          required: true
          schema:
            type: integer
          example: 55
      responses:
        '200':
          description: pc/server was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputer-With-Details'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_pcs_pcId
      tags:
        - pc
      summary: Updates a pc
      description: |
        Updates a pc or server.

        Will also update attached ip address information or guarantee.
      parameters:
        - in: path
          name: pcId
          description: ID of the pc or server to update.
          required: true
          schema:
            type: integer
          example: 55
      requestBody:
        description: pc object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPersonalComputer-With-Ip-Guarantee'
            example:
              id: 42
              inventoryNumber: INV001-2021-05-21
              active: true
              companyId: 100000
              name: SERVER-001
              serviceTechnicianId: 1
              employeeId: 1
              date: 1748256000
              location: Server-Raum
              manufacturerId: 1
              model: Acer Altos 11000
              serialNumber: GDSZRTWE3827210463284231
              osId: 1
              software: Div. Software wurde installiert, ...
              remark: 'Folgendes ist beim Server zu beachten: ...'
              showRemark: false
              mainboardManufacturerId: 1
              mainboardManufacturerRevision: ''
              mainboardSerialNumber: ''
              bios: ''
              biosRelease: ''
              cpuManufacturerId: 1
              cpuTypeId: 1
              cpuFrequency: 4200
              cpuNumber: 4
      responses:
        '201':
          description: pc/server was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputer-With-Details'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_pcs_pcId
      tags:
        - pc
      summary: Deletes a pc
      description: |
        Deletes a pc or server.
      parameters:
        - in: path
          name: pcId
          description: ID of the pc or server to delete.
          required: true
          schema:
            type: integer
          example: 55
      responses:
        '204':
          description: pc was deleted successfully
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/pcs:
    post:
      operationId: post_api_v1_pcs
      tags:
        - pc
      summary: Creates a pc
      description: |
        Creates a pc or server.

        Will also store attached ip address information or guarantee.
      requestBody:
        description: pc object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPersonalComputer-With-Ip-Guarantee'
            example:
              id: 42
              inventoryNumber: INV001-2021-05-21
              active: true
              companyId: 100000
              name: SERVER-001
              serviceTechnicianId: 1
              employeeId: 1
              date: 1748256000
              location: Server-Raum
              manufacturerId: 1
              model: Acer Altos 11000
              serialNumber: GDSZRTWE3827210463284231
              osId: 1
              software: Div. Software wurde installiert, ...
              remark: 'Folgendes ist beim Server zu beachten: ...'
              showRemark: false
              mainboardManufacturerId: 1
              mainboardManufacturerRevision: ''
              mainboardSerialNumber: ''
              bios: ''
              biosRelease: ''
              cpuManufacturerId: 1
              cpuTypeId: 1
              cpuFrequency: 4200
              cpuNumber: 4
      responses:
        '201':
          description: pc/server was successfully inserted
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputer-With-Details'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_pcs
      tags:
        - pc
      summary: Gets a list of pcs
      description: |
        Gets a list of pcs or server.
      requestBody:
        description: query parameters for the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPersonalComputerConfiguration'
            example:
              companyId: 1
              branches: COMPANY_ONLY
              active: ACTIVE_ONLY
      responses:
        '200':
          description: pc/server list response
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPersonalComputer-With-Details'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/peripheries/{peripheryId}:
    get:
      operationId: get_api_v1_peripheries_peripheryId
      tags:
        - periphery
      summary: Gets a periphery by id
      description: Fetches a periphery by a given id
      parameters:
        - in: path
          name: peripheryId
          description: ID of the periphery to fetch.
          required: true
          schema:
            type: integer
          example: 33
      responses:
        '200':
          description: pceriphery was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPeriphery-With-Ip-Guarantee'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_peripheries_peripheryId
      tags:
        - periphery
      summary: Updates a periphery
      description: |
        Updates a periphery

        Will also update attached ip address information or guarantee.
      parameters:
        - in: path
          name: peripheryId
          description: ID of the periphery to update.
          required: true
          schema:
            type: integer
          example: 33
      requestBody:
        description: periphery object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPeriphery-With-Ip-Guarantee'
            example:
              id: 42
              companyId: 1
              date: 1748256000
              peripheryTypeId: 1
              manufacturerId: 1
              type: string
              location: string
              remark: string
              internalRemark: string
              serialNumber: string
              inventoryNumber: string
              version: string
              active: false
              employeeId: 1
              pcId: 1
              billingNumber: string
              articleNumber: string
      responses:
        '201':
          description: pc/server was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPeriphery-With-Ip-Guarantee'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_peripheries_peripheryId
      tags:
        - periphery
      summary: Deletes a periphery
      description: |
        Deletes a periphery
      parameters:
        - in: path
          name: peripheryId
          description: ID of the periphery to delete.
          required: true
          schema:
            type: integer
          example: 33
      responses:
        '204':
          description: periphery was deleted successfully
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/peripheries:
    post:
      operationId: post_api_v1_peripheries
      tags:
        - periphery
      summary: Creates a periphery
      description: |
        Creates a periphery

        Will also store attached ip address information or guarantee.
      requestBody:
        description: periphery object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPeriphery-With-Ip-Guarantee'
            example:
              id: 42
              companyId: 1
              date: 1748256000
              peripheryTypeId: 1
              manufacturerId: 1
              type: string
              location: string
              remark: string
              internalRemark: string
              serialNumber: string
              inventoryNumber: string
              version: string
              active: false
              employeeId: 1
              pcId: 1
              billingNumber: string
              articleNumber: string
      responses:
        '201':
          description: periphery was successfully inserted
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPeriphery-With-Ip-Guarantee'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_peripheries
      tags:
        - periphery
      summary: Gets a list of peripheries
      description: |
        Gets a list of peripheries
      requestBody:
        description: query parameters for the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPeripheryConfiguration'
            example:
              companyId: 1
              branches: COMPANY_ONLY
              active: ACTIVE_ONLY
      responses:
        '200':
          description: periphery list response
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPeriphery-With-Ip-Guarantee'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/peripheries/types:
    get:
      operationId: get_api_v1_peripheries_types
      tags:
        - periphery
      summary: Get periphery types
      description: |
        Gets a list of all periphery types
      responses:
        '200':
          description: periphery type list
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPeripheryType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_peripheries_types
      tags:
        - periphery
      summary: Create periphery type
      description: |
        Creates a new periphery types
      requestBody:
        description: periphery type to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPeripheryType'
            example:
              id: 1
              name: Drucker
              image: drucker.png
      responses:
        '201':
          description: periphery type created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPeripheryType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/peripheries/types/{typeId}:
    put:
      operationId: put_api_v1_peripheries_types_typeId
      tags:
        - periphery
      summary: Update periphery type
      description: |
        Updates a periphery type
      requestBody:
        description: periphery type to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPeripheryType'
            example:
              id: 1
              name: Drucker
              image: drucker.png
      parameters:
        - in: path
          name: typeId
          required: true
          description: type id to be updated
          schema:
            type: integer
          example: 1
      responses:
        '201':
          description: periphery type updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPeripheryType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_peripheries_types_typeId
      tags:
        - periphery
      summary: Delete periphery type
      description: |
        Deletes a periphery type
      parameters:
        - in: path
          name: typeId
          required: true
          description: type id to be deleted
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: periphery type deleted
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/peripheries/{peripheryId}/buildIn/{linkTypeId}/{linkId}:
    post:
      operationId: post_api_v1_peripheries_peripheryId_buildIn_linkTypeId_linkId
      tags:
        - periphery
      summary: Assign periphery
      description: |
        Assigns a periphery to another pc or periphery
      parameters:
        - in: path
          name: peripheryId
          description: id of the periphery to be assigned
          required: true
          schema:
            type: integer
          example: 33
        - in: path
          name: linkTypeId
          description: link type of the "target" assignment (i.e. 1 = pc)
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: linkId
          description: link id of the "target" assignment (i.e. id of the pc)
          required: true
          schema:
            type: integer
          example: 55
      responses:
        '201':
          description: pceriphery was successfully assigned
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_peripheries_peripheryId_buildIn_linkTypeId_linkId
      tags:
        - periphery
      summary: Delete periphery assignment
      description: |
        Deletes a periphery assignment to another pc or periphery
      parameters:
        - in: path
          name: peripheryId
          description: id of the periphery to be removed
          required: true
          schema:
            type: integer
          example: 33
        - in: path
          name: linkTypeId
          description: link type of the "target" assignment (i.e. 1 = pc)
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: linkId
          description: link id of the "target" assignment (i.e. id of the pc)
          required: true
          schema:
            type: integer
          example: 55
      responses:
        '204':
          description: periphery assignment was successfully removed
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/components/{componentId}:
    get:
      operationId: get_api_v1_components_componentId
      tags:
        - components
      summary: Gets a component by id
      description: Fetches a component by a given id
      parameters:
        - in: path
          name: componentId
          description: ID of the component to fetch.
          required: true
          schema:
            type: integer
          example: 12
      responses:
        '200':
          description: component was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsComponent'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_components_componentId
      tags:
        - components
      summary: Updates a component
      description: |
        Updates a component
      parameters:
        - in: path
          name: componentId
          description: ID of the component to update.
          required: true
          schema:
            type: integer
          example: 12
      requestBody:
        description: component object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsComponent'
            example:
              id: 42
              inventoryNumber: INV002-2021-04-27
              componentTypeId: 1
              pcId: 1234
              peripheryId: 1
              manufacturerId: 21
              type: IronWolf NAS HDD ST4000VN008
              serialNumber: HDFGT10374627
              megabytes: 4000000
              hddTypeId: 1
              scsiId: ''
              onBoard: false
              companyId: 0
              remark: ''
              active: true
              date: 1622498400
              billingNumber: ''
              articleNumber: 3406-25L
              storageId: 1
              purchasePrice: 90
              sellingPrice: 120
              description: ''
      responses:
        '201':
          description: component was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsComponent'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_components_componentId
      tags:
        - components
      summary: Deletes a component
      description: |
        Deletes a conponent
      parameters:
        - in: path
          name: componentId
          description: ID of the component to delete.
          required: true
          schema:
            type: integer
          example: 12
      responses:
        '204':
          description: component was deleted successfully
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/components:
    post:
      operationId: post_api_v1_components
      tags:
        - components
      summary: Creates a component
      description: |
        Creates a component
      requestBody:
        description: component object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsComponent'
            example:
              id: 42
              inventoryNumber: INV002-2021-04-27
              componentTypeId: 1
              pcId: 1234
              peripheryId: 1
              manufacturerId: 21
              type: IronWolf NAS HDD ST4000VN008
              serialNumber: HDFGT10374627
              megabytes: 4000000
              hddTypeId: 1
              scsiId: ''
              onBoard: false
              companyId: 0
              remark: ''
              active: true
              date: 1622498400
              billingNumber: ''
              articleNumber: 3406-25L
              storageId: 1
              purchasePrice: 90
              sellingPrice: 120
              description: ''
      responses:
        '201':
          description: component was successfully inserted
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsComponent'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_components
      tags:
        - components
      summary: Gets a list of components
      description: |
        Gets a list of components
      requestBody:
        description: query parameters for the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsComponentConfiguration'
            example:
              companyId: 1
              branches: COMPANY_ONLY
              active: ACTIVE_ONLY
      responses:
        '200':
          description: component list response
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsComponent'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/components/types:
    get:
      operationId: get_api_v1_components_types
      tags:
        - components
      summary: Gets a list of component types
      description: |
        Gets a list of component types
      responses:
        '200':
          description: component type list
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsComponentType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_components_types
      tags:
        - components
      summary: Create component type
      description: |
        Creates a new component type
      requestBody:
        description: component type to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsComponentType'
            example:
              id: 3
              type: Festplatte
              shortName: HDD
              shown: false
      responses:
        '201':
          description: component type created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsComponentType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/components/types/{typeId}:
    put:
      operationId: put_api_v1_components_types_typeId
      tags:
        - components
      summary: Update component type
      description: |
        Updates a component type
      parameters:
        - in: path
          name: typeId
          required: true
          description: type id to be updated
          schema:
            type: integer
          example: 1
      requestBody:
        description: component type to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsComponentType'
            example:
              id: 3
              type: Festplatte
              shortName: HDD
              shown: false
      responses:
        '201':
          description: component type updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsComponentType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_components_types_typeId
      tags:
        - components
      summary: Delete component type
      description: |
        Delete a component type
      parameters:
        - in: path
          name: typeId
          required: true
          description: type id to be deleted
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: component type deleted
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies:
    post:
      operationId: post_api_v1_companies
      tags:
        - company
      summary: Creates a new company
      description: |
        Creates a new company in TANSS. The caller must have the `MANAGE_COMPANIES` permission and access to all companies; if a `headquarterId` is given, access to that headquarter is verified as well. Duplicates by (name, street, city) are rejected and the next free customer id is assigned automatically.

        To create a "personal customer" (company + single employee modeled as one person), set `personalCustomer: true` and pass a fully populated `personalCustomerEmployee` — the company name is then derived from "Lastname, Firstname" and the employee is persisted and attached to the new company.
      requestBody:
        description: company object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Company-Post'
            example:
              displayId: 100023
              name: Beispiel GmbH
              matchcode: BEISPIEL-BERLIN
              street: Hauptstraße 12
              postcode: '10115'
              city: Berlin
              country: DE
              note: Neu angelegt am 26.05.2026
              headquarterId: 0
              email: info@beispiel.de
              website: https://beispiel.de
              supportInfo: 'Interner Hinweis: Premium-Wartung'
              telephone: +49 30 1234567
      responses:
        '201':
          description: company was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Company-Post'
              example:
                meta: {}
                content:
                  id: 100023
                  displayId: 100023
                  name: Beispiel GmbH
                  matchcode: BEISPIEL-BERLIN
                  street: Hauptstraße 12
                  postcode: '10115'
                  city: Berlin
                  country: DE
                  headquarterId: 0
                  email: info@beispiel.de
                  website: https://beispiel.de
                  telephone: +49 30 1234567
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/{companyId}/employees:
    get:
      operationId: get_api_v1_companies_companyId_employees
      tags:
        - company
      summary: Gets all employees of a company
      parameters:
        - in: path
          name: companyId
          required: true
          description: Id of the company
          example: 100023
          schema:
            type: integer
      responses:
        '200':
          description: list of employees
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee-Short'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tanssEvents/rules:
    post:
      operationId: post_api_v1_tanssEvents_rules
      tags:
        - webHooks
      summary: creates a rule
      description: |
        This route will create a "TANSS event rule", which is primarily used for webhhok notifications.
      requestBody:
        description: tanss event rule object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTanssEventRule'
            example:
              id: 42
              name: Example name
              active: false
      responses:
        '201':
          description: rule was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTanssEventRule'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tanssEvents_rules
      tags:
        - webHooks
      summary: get a list of rules
      description: |
        This route will return a list of rules, matching a filter, which is sent in the body
      requestBody:
        description: tanss event rule filter
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTanssEventRuleConfiguration'
            example:
              linkType: PC
              linkIds: []
      responses:
        '200':
          description: rule list
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTanssEventRule'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tanssEvents/rules/{id}:
    put:
      operationId: put_api_v1_tanssEvents_rules_id
      tags:
        - webHooks
      summary: updates a rule
      description: |
        This route will update a "TANSS event rule"
      parameters:
        - in: path
          name: id
          required: true
          description: id of the rule
          example: 42
          schema:
            type: integer
      requestBody:
        description: tanss event rule object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTanssEventRule'
            example:
              id: 42
              name: Example name
              active: false
      responses:
        '201':
          description: rule was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTanssEventRule'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_tanssEvents_rules_id
      tags:
        - webHooks
      summary: gets a rule
      description: |
        This route retrieve a "TANSS event rule"
      parameters:
        - in: path
          name: id
          required: true
          description: id of the rule
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: details about the rule
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTanssEventRule'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_tanssEvents_rules_id
      tags:
        - webHooks
      summary: deletes a rule
      description: |
        This route delete a "TANSS event rule"
      parameters:
        - in: path
          name: id
          required: true
          description: id of the rule
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: rule was deleted
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tanssEvents/rules/test/action:
    put:
      operationId: put_api_v1_tanssEvents_rules_test_action
      tags:
        - webHooks
      summary: test a rule
      description: |
        This route will let you trigger an action, so you can view the result of the action (i.e. WebHook notification)
      requestBody:
        description: tanss event test information
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTanssEventRuleActionTestOptions'
            example:
              linkType: PC
              linkId: 1
              ticketNotificationOptions:
                reason: STATUS_CHANGED
                commentId: 1
                mailId: 1
                supportId: 1
              action:
                actionType: WEBHOOK
                params: {}
      responses:
        '201':
          description: rule was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTanssEvent'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/services:
    post:
      operationId: post_api_v1_services
      tags:
        - services
      summary: Creates a service
      description: |
        Creates a service

        Services are used in pcs or periphery (on ip addresses) to launch an external software
      requestBody:
        description: service object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsService'
            example:
              id: 42
              text: Example content
              symbol: string
              command: string
              active: false
              callType: BATCH
      responses:
        '201':
          description: service was successfully inserted
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsService'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_services
      tags:
        - services
      summary: Gets a list of all services
      description: |
        Gets a list of all defined services
      responses:
        '200':
          description: list of services response
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsService'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/services/{id}:
    get:
      operationId: get_api_v1_services_id
      tags:
        - services
      summary: Gets a service by id
      description: Fetches a service given id
      parameters:
        - in: path
          name: id
          description: ID of the service to fetch.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: service was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsService'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_services_id
      tags:
        - services
      summary: Updates a service
      description: |
        Updates a services.
      parameters:
        - in: path
          name: id
          description: ID of the service to update.
          required: true
          schema:
            type: integer
          example: 42
      requestBody:
        description: service object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsService'
            example:
              id: 42
              text: Example content
              symbol: string
              command: string
              active: false
              callType: BATCH
      responses:
        '201':
          description: service was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsService'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_services_id
      tags:
        - services
      summary: Deletes a service
      description: |
        Deletes a service.

        Will only succeed if this service isn't assigned to any ip addresses
      parameters:
        - in: path
          name: id
          description: ID of the service to delete.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: service was deleted successfully
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/os:
    post:
      operationId: post_api_v1_os
      tags:
        - operating systems
      summary: Creates a new os
      description: |
        Creates a new operating system
      requestBody:
        description: operating system to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPersonalComputerOperatingSystem'
            example:
              id: 42
              name: macOs monterey
              serverOperatingSystem: false
              active: true
              articleNumber: ''
      responses:
        '201':
          description: os was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputerOperatingSystem'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_os
      tags:
        - operating systems
      summary: Get a list of all os
      description: |
        Gets a list of all operating systems
      responses:
        '200':
          description: list of all operating systems
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPersonalComputerOperatingSystem'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/os/{id}:
    put:
      operationId: put_api_v1_os_id
      tags:
        - operating systems
      summary: Updates a os
      description: |
        Updates an existing operating system
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the operating system
          schema:
            type: integer
          example: 3
      requestBody:
        description: operating system to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPersonalComputerOperatingSystem'
            example:
              id: 42
              name: macOs monterey
              serverOperatingSystem: false
              active: true
              articleNumber: ''
      responses:
        '202':
          description: os was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputerOperatingSystem'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_os_id
      tags:
        - operating systems
      summary: Get a specific os
      description: |
        Gets a specific operating system
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the operating system
          schema:
            type: integer
          example: 3
      responses:
        '200':
          description: operating systems
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputerOperatingSystem'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_os_id
      tags:
        - operating systems
      summary: Deletes a specific os
      description: |
        Deletes a specific operating system
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the operating system
          schema:
            type: integer
          example: 3
      responses:
        '204':
          description: deleted operating system
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/manufacturers:
    post:
      operationId: post_api_v1_manufacturers
      tags:
        - manufacturer
      summary: Creates a new manufacturer
      description: |
        Creates a new manufacturer
      requestBody:
        description: manufacturer to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsManufacturer'
            example:
              id: 42
              name: Acer
      responses:
        '201':
          description: manufacturer was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsManufacturer'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_manufacturers
      tags:
        - manufacturer
      summary: Get a list of all manufacturers
      description: |
        Gets a list of all manufacturers
      responses:
        '200':
          description: list of all manufacturer
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsManufacturer'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/manufacturers/{id}:
    put:
      operationId: put_api_v1_manufacturers_id
      tags:
        - manufacturer
      summary: Updates a manufacturer
      description: |
        Updates an existing manufacturer
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the manufacturer
          schema:
            type: integer
          example: 1
      requestBody:
        description: manufacturer to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsManufacturer'
            example:
              id: 42
              name: Acer
      responses:
        '202':
          description: manufacturer was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsManufacturer'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_manufacturers_id
      tags:
        - manufacturer
      summary: Get a manufacturer
      description: |
        Gets a specific manufacturer
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the manufacturer
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: manufacturer
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsManufacturer'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_manufacturers_id
      tags:
        - manufacturer
      summary: Deletes a manufacturer
      description: |
        Deletes a manufacturer
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the manufacturer
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: deleted manufacturer
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/cpus:
    post:
      operationId: post_api_v1_cpus
      tags:
        - cpus
      summary: Creates a new cpu
      description: |
        Creates a new cpu
      requestBody:
        description: cpu to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPersonalComputerCpu'
            example:
              id: 42
              name: Example name
      responses:
        '201':
          description: cpu was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputerCpu'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_cpus
      tags:
        - cpus
      summary: Get a list of all cpus
      description: |
        Gets a list of all cpus
      responses:
        '200':
          description: list of all cpus
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPersonalComputerCpu'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/cpus/{id}:
    put:
      operationId: put_api_v1_cpus_id
      tags:
        - cpus
      summary: Updates a cpu
      description: |
        Updates an existing cpu
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the cpu
          schema:
            type: integer
          example: 4
      requestBody:
        description: cpu to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPersonalComputerCpu'
            example:
              id: 42
              name: Example name
      responses:
        '202':
          description: cpu was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputerCpu'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_cpus_id
      tags:
        - cpus
      summary: Get a cpu
      description: |
        Gets a specific cpu
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the cpu
          schema:
            type: integer
          example: 4
      responses:
        '200':
          description: cpus
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputerCpu'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_cpus_id
      tags:
        - cpus
      summary: Deletes a cpu
      description: |
        Deletes a cpu
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the cpu
          schema:
            type: integer
          example: 4
      responses:
        '204':
          description: deleted cpu
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/hddTypes:
    post:
      operationId: post_api_v1_hddTypes
      tags:
        - hddTypes
      summary: Creates a new hdd type
      description: |
        Creates a new hdd type
      requestBody:
        description: hdd type to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPersonalComputerHddType'
            example:
              id: 42
              name: S-ATA
      responses:
        '201':
          description: hdd type was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputerHddType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_hddTypes
      tags:
        - hddTypes
      summary: Get a list of all hdd types
      description: |
        Gets a list of all hdd types
      responses:
        '200':
          description: list of all hdd types
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPersonalComputerHddType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/hddTypes/{id}:
    put:
      operationId: put_api_v1_hddTypes_id
      tags:
        - hddTypes
      summary: Updates a hdd type
      description: |
        Updates an existing hdd type
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the hdd type
          schema:
            type: integer
          example: 1
      requestBody:
        description: hdd type to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsPersonalComputerHddType'
            example:
              id: 42
              name: S-ATA
      responses:
        '202':
          description: hdd type was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputerHddType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_hddTypes_id
      tags:
        - hddTypes
      summary: Get a hdd type
      description: |
        Gets a specific hdd type
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the hdd type
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: hdd type
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsPersonalComputerHddType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_hddTypes_id
      tags:
        - hddTypes
      summary: Deletes a hdd type
      description: |
        Deletes a hdd type
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the hdd type
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: deleted hdd type
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companyCategories:
    get:
      operationId: get_api_v1_companyCategories
      tags:
        - company category
      summary: list of categories
      description: |
        Gets a list of all categories
      responses:
        '200':
          description: category list
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsCompanyCategory-With-Types'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_companyCategories
      tags:
        - company category
      summary: Creates a new company category
      description: |
        Creates a company category in TANSS.
      requestBody:
        description: company category object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsCompanyCategory'
            example:
              id: 1
              name: Regionen
      responses:
        '201':
          description: category was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsCompanyCategory-With-Types'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companyCategories/{id}:
    get:
      operationId: get_api_v1_companyCategories_id
      tags:
        - company category
      summary: gets a category
      description: |
        gets a single company category
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company category
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: company category infos
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsCompanyCategory-With-Types'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_companyCategories_id
      tags:
        - company category
      summary: updates a category
      description: |
        Updates a company category
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company category
          example: 1
          schema:
            type: integer
      requestBody:
        description: company category object to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsCompanyCategory'
            example:
              id: 1
              name: Regionen
      responses:
        '202':
          description: updated category
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsCompanyCategory-With-Types'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_companyCategories_id
      tags:
        - company category
      summary: Deletes a company category
      description: |
        Deletes a company category
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company category
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: category was successfully deleted
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companyCategories/types:
    get:
      operationId: get_api_v1_companyCategories_types
      tags:
        - company category
      summary: list of company types
      description: |
        Gets a list of all company types
      responses:
        '200':
          description: company type list
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsCompanyType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_companyCategories_types
      tags:
        - company category
      summary: Creates a new company type
      description: |
        Creates a company type in TANSS.
      requestBody:
        description: company ztype object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsCompanyType'
            example:
              id: 42
              name: Example name
              categoryId: 1
              icon: string
              hidden: false
      responses:
        '201':
          description: type was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsCompanyType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companyCategories/types/{id}:
    get:
      operationId: get_api_v1_companyCategories_types_id
      tags:
        - company category
      summary: gets a company type
      description: |
        gets a single company type
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company type
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: company type infos
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsCompanyType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_companyCategories_types_id
      tags:
        - company category
      summary: updates a company type
      description: |
        Updates a company type
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company type
          example: 1
          schema:
            type: integer
      requestBody:
        description: company type object to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsCompanyType'
            example:
              id: 42
              name: Example name
              categoryId: 1
              icon: string
              hidden: false
      responses:
        '202':
          description: updated type
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsCompanyType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_companyCategories_types_id
      tags:
        - company category
      summary: Deletes a company type
      description: |
        Deletes a company type
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company type
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: type was successfully deleted
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/identify:
    post:
      operationId: post_api_v1_identify
      tags:
        - identify
      summary: identifies items
      description: |
        This call lets you "identify" misc. items, i.e. get a manufacturer id by name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TnsIdentifyRequest'
            example:
              - items:
                  - linkType: PC
                    identifier: string
                    searchSections: []
      responses:
        '200':
          description: list of identified objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsIdentifyResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ips/{assignmentType}/{assignmentId}:
    get:
      operationId: get_api_v1_ips_assignmentType_assignmentId
      tags:
        - ips
      summary: Gets ip addresses
      description: Gets all ip addresses of a device
      parameters:
        - in: path
          name: assignmentType
          required: true
          description: assignment type (PC / PERIPHERY)
          schema:
            $ref: '#/components/schemas/TnsIpMacAssignmentType'
          example: PC
        - in: path
          name: assignmentId
          required: true
          description: id of the pc / periphery
          schema:
            type: integer
          example: 55
      responses:
        '200':
          description: list of ip addresses
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsIpMac'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_ips_assignmentType_assignmentId
      tags:
        - ips
      summary: Creates an ip address
      description: |
        Creates an ip addresse for a pc / periphery
      parameters:
        - in: path
          name: assignmentType
          required: true
          description: assignment type (PC / PERIPHERY)
          schema:
            $ref: '#/components/schemas/TnsIpMacAssignmentType'
          example: PC
        - in: path
          name: assignmentId
          required: true
          description: id of the pc / periphery
          schema:
            type: integer
          example: 55
      requestBody:
        description: ip address object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsIpMac-Minimum'
            example:
              ip: string
              mac: string
              remark: string
              dhcp: false
      responses:
        '201':
          description: ip address was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsIpMac'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ips/{id}:
    put:
      operationId: put_api_v1_ips_id
      tags:
        - ips
      summary: Update ip address
      description: Updates a specific ip address
      parameters:
        - in: path
          name: id
          required: true
          description: id of ip address
          schema:
            type: integer
          example: 8
      requestBody:
        description: ip address object to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsIpMac-Minimum'
            example:
              ip: string
              mac: string
              remark: string
              dhcp: false
      responses:
        '200':
          description: updated ip address
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsIpMac'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_ips_id
      tags:
        - ips
      summary: Deletes an ip address
      description: |
        Deletes an ip address for a pc / periphery
      parameters:
        - in: path
          name: id
          required: true
          description: id of ip address
          schema:
            type: integer
          example: 8
      responses:
        '204':
          description: ip address was successfully deleted
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailAccounts:
    post:
      operationId: post_api_v1_emailAccounts
      tags:
        - emailAccounts
      summary: Creates an email account
      description: |
        Creates an email account
      requestBody:
        description: account object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsEmailAccount'
            example:
              id: 1
              companyId: 100000
              description: Catch-All Postfach von Firma A
              loginName: TestUser1
              loginPassword: 64gdfs_izda8!
              incomingServer: pop3.test.de
              outgoingServer: smtp.test.de
              sendAttachments: true
              deleteArchived: true
              sendTrackingInfos: false
              catchAllAccount: true
              addresses: address1@kunde.de;address2@kunde.de
              active: true
              typeId: 1
              typeName: Example name
              remark: example
              linkTypeId: 0
              linkId: 0
              domainId: 0
      responses:
        '201':
          description: pc/server was successfully inserted
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsEmailAccount'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailAccounts/compamy/{companyId}:
    get:
      operationId: get_api_v1_emailAccounts_compamy_companyId
      tags:
        - emailAccounts
      summary: List accounts of company
      description: |
        This route will get all E-Mail accounts of a given company
      parameters:
        - in: path
          name: companyId
          required: true
          description: Id of the company
          schema:
            type: integer
          example: 42
      responses:
        '201':
          description: list of accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsEmailAccount'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailAccounts/{id}:
    get:
      operationId: get_api_v1_emailAccounts_id
      tags:
        - emailAccounts
      summary: Gets an account
      description: |
        This route will get one account and return it
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the E-mail account
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: E-mail account infos
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsEmailAccount'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_emailAccounts_id
      tags:
        - emailAccounts
      summary: Edit an accounts
      description: |
        This route will update one account
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the E-mail account
          schema:
            type: integer
          example: 42
      requestBody:
        description: account object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsEmailAccount'
            example:
              id: 1
              companyId: 100000
              description: Catch-All Postfach von Firma A
              loginName: TestUser1
              loginPassword: 64gdfs_izda8!
              incomingServer: pop3.test.de
              outgoingServer: smtp.test.de
              sendAttachments: true
              deleteArchived: true
              sendTrackingInfos: false
              catchAllAccount: true
              addresses: address1@kunde.de;address2@kunde.de
              active: true
              typeId: 1
              typeName: Example name
              remark: example
              linkTypeId: 0
              linkId: 0
              domainId: 0
      responses:
        '201':
          description: E-mail account updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsEmailAccount'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_emailAccounts_id
      tags:
        - emailAccounts
      summary: Deletes an account
      description: |
        This route will delete a specific account
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the E-mail account
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: E-mail account was deleted
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailAccounts/types:
    get:
      operationId: get_api_v1_emailAccounts_types
      tags:
        - emailAccounts
      summary: List account types
      description: |
        Gets a list of available E-mail account types
      responses:
        '200':
          description: List of E-mail account types
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsEmailAccountType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests/list:
    put:
      operationId: put_api_v1_vacationRequests_list
      tags:
        - vacationRequests
      summary: Gets a list of vacation requests
      requestBody:
        description: query parameters for retrieving vacation requests
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsVacationRequestConfiguration'
            example:
              year: 2023
              month: 11
              employeeIds:
                - 1
              departmentIds:
                - 1
              planningTypes:
                - SUPPORT
              planningAdditionalIds:
                - 1
              customTypeIds:
                - 1
              statesOnly:
                - NEW
      responses:
        '200':
          description: a list of vacation requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsVacationRequest'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests/planningAdditionalTypes:
    get:
      operationId: get_api_v1_vacationRequests_planningAdditionalTypes
      tags:
        - vacationRequests - balance & config
      summary: Gets a list of absence/custom types
      responses:
        '200':
          description: a list of absence/custom
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsPlanningAdditionalType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests:
    post:
      operationId: post_api_v1_vacationRequests
      tags:
        - vacationRequests
      summary: creates a vacation request
      requestBody:
        description: vacation request to be stored
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsVacationRequest'
            example:
              id: 42
              planningType: SUPPORT
              status: NEW
              startDate: 1748256000
              endDate: 1748256000
              requesterId: 1
              requestReason: example
              requestDate: 1748256000
              supervisorId: 1
              supervisorReason: example
              supervisorDate: 1748256000
              planningAdditionalId: 1
              processId: 1
              processStepId: 1
              days:
                - vacationRequestId: 1
                  date: 1
                  forenoon: false
                  afternoon: false
                  startHour: 1
                  startMinute: 1
                  endHour: 1
                  endMinute: 1
                  pause: 1
      responses:
        '200':
          description: the created vacation request
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsVacationRequest'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests/{id}:
    put:
      operationId: put_api_v1_vacationRequests_id
      tags:
        - vacationRequests
      summary: updates a vacation request
      requestBody:
        description: vacation request to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsVacationRequest'
            example:
              id: 42
              planningType: SUPPORT
              status: NEW
              startDate: 1748256000
              endDate: 1748256000
              requesterId: 1
              requestReason: example
              requestDate: 1748256000
              supervisorId: 1
              supervisorReason: example
              supervisorDate: 1748256000
              planningAdditionalId: 1
              processId: 1
              processStepId: 1
              days:
                - vacationRequestId: 1
                  date: 1
                  forenoon: false
                  afternoon: false
                  startHour: 1
                  startMinute: 1
                  endHour: 1
                  endMinute: 1
                  pause: 1
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the vacation request
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: the updated vacation request
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsVacationRequest'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_vacationRequests_id
      tags:
        - vacationRequests
      summary: deletes a vacation request
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the vacation request
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: deleted vacation request
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests/vacationDays/year/{year}:
    get:
      operationId: get_api_v1_vacationRequests_vacationDays_year_year
      tags:
        - vacationRequests - balance & config
      summary: gets the available vacation days per year
      parameters:
        - in: path
          name: year
          required: true
          description: The year for which available vacation days are returned
          example: 2025
          schema:
            type: integer
      responses:
        '200':
          description: list of vacation days for all employees with access
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsEmployeeVacationDays'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests/vacationDays:
    post:
      operationId: post_api_v1_vacationRequests_vacationDays
      tags:
        - vacationRequests - balance & config
      summary: sets the available vacation days per year
      requestBody:
        description: infos on employee and vacation days per year
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsEmployeeVacationDays'
            example:
              employeeId: 1
              year: 1
              numberOfDays: 1
              transferred: 1
              employee:
                id: 42
                name: Example name
                firstName: Example name
                lastName: Example name
                salutationId: 1
                departmentId: 1
                room: example
                telephoneNumber: example
                emailAddress: user@example.com
                carId: 1
                mobilePhone: example
                initials: example
                workingHourModelId: 1
                accountingTypeId: 1
                privatePhoneNumber: example
                active: false
                erpNumber: example
                personalFaxNumber: example
                role: example
                titleId: 1
                language: example
                telephoneNumberTwo: example
                mobileNumberTwo: example
                restrictedUserLicense: false
                birthday: '1977-12-02'
      responses:
        '200':
          description: updated infos for the employee
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsEmployeeVacationDays'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tanssEvents:
    put:
      operationId: put_api_v1_tanssEvents
      tags:
        - activityFeed
      summary: List of user items
      description: |
        This route will gibe a list of activity feed items for the user
      requestBody:
        description: list filter object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTanssEventConfiguration'
            example:
              minimumCreationDate: 1748256000
              seenFilter: BOTH
              confirmedFilter: BOTH
              triggerTypes: []
              linkTypes: []
              linkIds: []
              preventViewEvent: false
              includeContent: false
      responses:
        '200':
          description: list of activity feed items
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTanssEvent'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tanssEvents/unseen:
    get:
      operationId: get_api_v1_tanssEvents_unseen
      tags:
        - activityFeed
      summary: Number of unseen events
      description: |
        Gets the total number of unseen events
      responses:
        '200':
          description: number of unseen events
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: integer
                    description: number of unseen events
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tanssEvents/mark/all/seen:
    post:
      operationId: post_api_v1_tanssEvents_mark_all_seen
      tags:
        - activityFeed
      summary: Marks all as seen
      description: |
        This route will mark all unseen events as "seen"
      responses:
        '200':
          description: number of unseen events
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: integer
                    description: number of unseen events that were markes as seen
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/ticketStates:
    get:
      operationId: get_api_v1_admin_ticketStates
      tags:
        - ticket states
      summary: Gets a list of all ticket states
      responses:
        '200':
          description: list of ticket states
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsTicketState'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_admin_ticketStates
      tags:
        - ticket states
      summary: Creates a ticket state
      requestBody:
        description: ticket state object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTicketState'
            example:
              name: Example name
              image: string
              waitState: false
              rank: 1
              active: false
      responses:
        '201':
          description: ticket state was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTicketState'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/ticketStates/{id}:
    put:
      operationId: put_api_v1_admin_ticketStates_id
      tags:
        - ticket states
      summary: Updates a ticket state
      requestBody:
        description: ticket state object to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsTicketState'
            example:
              name: Example name
              image: string
              waitState: false
              rank: 1
              active: false
      parameters:
        - in: path
          name: id
          example: 42
          required: true
          schema:
            type: integer
          description: id of the ticket state that shall be updated
      responses:
        '202':
          description: ticket state was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsTicketState'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_admin_ticketStates_id
      tags:
        - ticket states
      summary: Deletes a ticket state
      parameters:
        - in: path
          name: id
          example: 42
          required: true
          schema:
            type: integer
          description: id of the ticket state that shall be deleted
      responses:
        '204':
          description: no content
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/documents:
    put:
      operationId: put_api_v1_documents
      tags:
        - documents
      summary: Get a list of company documents
      requestBody:
        description: query parameters for retrieving documents
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsDocumentConfiguration'
            example:
              companyId: 1
              linkTypeId: 1
              linkId: 1
              branchFilter: COMPANY_ONLY
              textFilter: Example content
              types: []
      responses:
        '200':
          description: list of documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsDocument'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_documents
      tags:
        - documents
      summary: Creates a document
      requestBody:
        description: document with content
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsDocument-With-Content'
            example:
              id: 42
              date: 1748256000
              modificationDate: 1748256000
              name: Example name
              type: DOCUMENT
              companyId: 1
              content: Example content
              createdEmployeeId: 1
              internal: false
              linkTypeId: 1
              linkId: 1
              encrypted: false
      responses:
        '201':
          description: created documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsDocument-With-Content'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/documents/{id}:
    get:
      operationId: get_api_v1_documents_id
      tags:
        - documents
      summary: Get a single document (including content)
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the document
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: document
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsDocument-With-Content'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_documents_id
      tags:
        - documents
      summary: Updates a document
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the document
          example: 42
          schema:
            type: integer
      responses:
        '202':
          description: document updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsDocument-With-Content'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_documents_id
      tags:
        - documents
      summary: Deletes a document
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the document
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: no content
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/documents/{id}/file:
    post:
      operationId: post_api_v1_documents_id_file
      tags:
        - documents
      summary: Uploads a file
      description: |
        If the document is of type "FILE", then you can set a file for this document

        This is set via this route
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the document
          example: 42
          schema:
            type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: REQUIRED! binary data of the uploaded file(s)
      responses:
        '201':
          description: document with file response
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsDocument-With-File'
              example: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/domains:
    post:
      operationId: post_api_v1_domains
      tags:
        - domains
      summary: Creates a domain
      requestBody:
        description: domain object to be saved
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsDomain-Full'
            example:
              id: 42
              companyId: 1
              owner: 1
              ownerLinkTypeId: 1
              adminc: 1
              admincLinkTypeId: 1
              techc: 1
              techcLinkTypeId: 1
              forwardDomainId: 1
              responsibleTechId: 1
              contractDurationStart: 1748256000
              contractDurationEnd: 1748259600
              title: Example title
              fqdn: string
              description: Example content
              customerId: string
              providerName: string
              loginName: max.mustermann
              loginPassword: max.mustermann
      responses:
        '201':
          description: domain was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsDomain-Full'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/domains/{id}:
    get:
      operationId: get_api_v1_domains_id
      tags:
        - domains
      summary: Gets a single domain
      parameters:
        - in: path
          name: id
          required: true
          example: 1
          schema:
            type: integer
          description: id of the domain that shall be fetched
      responses:
        '200':
          description: domain
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsDomain-Full'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_domains_id
      tags:
        - domains
      summary: Updates a domain
      requestBody:
        description: domain object to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsDomain-Full'
            example:
              id: 42
              companyId: 1
              owner: 1
              ownerLinkTypeId: 1
              adminc: 1
              admincLinkTypeId: 1
              techc: 1
              techcLinkTypeId: 1
              forwardDomainId: 1
              responsibleTechId: 1
              contractDurationStart: 1748256000
              contractDurationEnd: 1748259600
              title: Example title
              fqdn: string
              description: Example content
              customerId: string
              providerName: string
              loginName: max.mustermann
              loginPassword: max.mustermann
      parameters:
        - in: path
          name: id
          required: true
          example: 1
          schema:
            type: integer
          description: id of the domain that shall be updated
      responses:
        '202':
          description: domain was successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsDomain-Full'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_domains_id
      tags:
        - domains
      summary: Deletes a domain
      parameters:
        - in: path
          name: id
          required: true
          example: 1
          schema:
            type: integer
          description: id of the domain that shall be deleted
      responses:
        '204':
          description: no content
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/domains/company/{id}:
    get:
      operationId: get_api_v1_domains_company_id
      tags:
        - domains
      summary: List of domains of a company
      parameters:
        - in: path
          name: id
          required: true
          example: 100023
          schema:
            type: integer
          description: id of the company
      responses:
        '200':
          description: domains of company
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      - $ref: '#/components/schemas/TnsDomain'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses:
    put:
      operationId: put_api_v1_softwarelicenses
      tags:
        - software licenses
      summary: Get a list of software licenses
      requestBody:
        description: query parameters for retrieving supports
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSoftwarelicenseConfiguration'
            example:
              softwarelicenseTypeId: 1
              linkTypeId: 1
              linkId: 1
              includeSubTypes: false
              expiryFilter: ALL
              onlyOverlicenced: false
      responses:
        '200':
          description: a list of software licenses
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsSoftwarelicense'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_softwarelicenses
      tags:
        - software licenses
      summary: Creates a software license
      requestBody:
        description: software license object to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSoftwarelicense'
            example:
              id: 42
              companyId: 1
              remark: string
              serialNumber: string
              inventoryNumber: string
              softwarelicenseTypeId: 1
              expirationDate: 1748256000
              renew: false
              date: 1748256000
              maxNumberOfInstall: 1
              numberOfVolumes: 1
              active: false
              employeeId: 1
              internalRemark: string
              articleNumber: string
              contractPrice: 99.95
      responses:
        '201':
          description: creted software license
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSoftwarelicense'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/{id}:
    get:
      operationId: get_api_v1_softwarelicenses_id
      tags:
        - software licenses
      summary: Gets a single software license by id
      parameters:
        - name: id
          in: path
          description: id of the software license to get
          required: true
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: a single software
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSoftwarelicense'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_softwarelicenses_id
      tags:
        - software licenses
      summary: Updates a software license
      parameters:
        - name: id
          in: path
          description: id of the software license to get
          required: true
          example: 42
          schema:
            type: integer
      requestBody:
        description: software license object to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSoftwarelicense'
            example:
              id: 42
              companyId: 1
              remark: string
              serialNumber: string
              inventoryNumber: string
              softwarelicenseTypeId: 1
              expirationDate: 1748256000
              renew: false
              date: 1748256000
              maxNumberOfInstall: 1
              numberOfVolumes: 1
              active: false
              employeeId: 1
              internalRemark: string
              articleNumber: string
              contractPrice: 99.95
      responses:
        '202':
          description: updated software license
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSoftwarelicense'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_softwarelicenses_id
      tags:
        - software licenses
      summary: Deletes a software license
      parameters:
        - name: id
          in: path
          description: id of the software license to get
          required: true
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: no content
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/types:
    get:
      operationId: get_api_v1_softwarelicenses_types
      tags:
        - software license types
      summary: Gets all software license types
      responses:
        '200':
          description: a list of all software license types
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsSoftwarelicenseType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_softwarelicenses_types
      tags:
        - software license types
      summary: Creates a new software license type
      requestBody:
        description: software license type object to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSoftwarelicenseType'
            example:
              id: 42
              manufacturerNumber: string
              name: Example name
              comment: Example content
              previousId: 1
              active: false
              standardRunningTime: 1748256000
              standardRenew: false
              standardMaxNumberOfInstallations: 1
              articleNumber: string
      responses:
        '202':
          description: created software license type
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSoftwarelicenseType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/types/{id}:
    get:
      operationId: get_api_v1_softwarelicenses_types_id
      tags:
        - software license types
      summary: Gets a single software license type
      parameters:
        - name: id
          in: path
          description: id of the software license type to get
          required: true
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: a single software license type
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSoftwarelicenseType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_softwarelicenses_types_id
      tags:
        - software license types
      summary: Updates a software license type
      parameters:
        - name: id
          in: path
          description: id of the software license type to update
          required: true
          example: 42
          schema:
            type: integer
      requestBody:
        description: software license type object to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSoftwarelicenseType'
            example:
              id: 42
              manufacturerNumber: string
              name: Example name
              comment: Example content
              previousId: 1
              active: false
              standardRunningTime: 1748256000
              standardRenew: false
              standardMaxNumberOfInstallations: 1
              articleNumber: string
      responses:
        '202':
          description: updated software license type
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsSoftwarelicenseType'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: delete_api_v1_softwarelicenses_types_id
      tags:
        - software license types
      summary: Deletes a software license type
      parameters:
        - name: id
          in: path
          description: id of the software license type to delete
          required: true
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: no content
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/calls/v1/notification/close:
    post:
      operationId: post_api_calls_v1_notification_close
      security:
        - PhoneToken: []
        - ApiTokenAuth: []
      tags:
        - calls (user context)
      summary: Close call notification
      description: |
        Dismisses the calling employee's currently displayed phone-call notification (e.g. after the call has ended or the user clicked away). Sends a server-side close event to all subscribed clients of that user. Requires basic phone-call permissions.
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/deviceManagement/v1/peripheries/fields:
    get:
      operationId: get_api_deviceManagement_v1_peripheries_fields
      security:
        - DeviceManagementToken: []
      tags:
        - device management
      summary: List periphery-type additional fields
      description: |
        Returns all custom additional-field definitions across all periphery types. Used by the device-management admin UI to render the per-type custom field configuration.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of additional-field definitions across all periphery types.
              example:
                meta: {}
                content:
                  - id: 1
                    peripheryTypeId: 4
                    title: Seriennummer
                    type: INPUT_TEXT
                  - id: 2
                    peripheryTypeId: 4
                    title: Lizenzschlüssel
                    type: INPUT_TEXT
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_deviceManagement_v1_peripheries_fields
      security:
        - DeviceManagementToken: []
      tags:
        - device management
      summary: Create periphery-type additional field
      description: |
        Adds a new custom additional-field definition (e.g. "Seriennummer", "Garantieende") under a periphery type. The field then becomes available to fill in when editing peripheries of that type.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - peripheryTypeId
              properties:
                id:
                  type: integer
                  description: Unique identifier of the additional field
                peripheryTypeId:
                  type: integer
                  description: Identifier of the periphery device type this field belongs to
                title:
                  type: string
                  description: Label of the additional field
                type:
                  type: string
                  description: Input type of the additional field
                  enum:
                    - INPUT_TEXT
            example:
              id: 42
              peripheryTypeId: 1
              title: Example title
              type:
                value: string
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The newly created additional-field definition.
              example:
                meta: {}
                content:
                  id: 3
                  peripheryTypeId: 4
                  title: Inventarnummer
                  type: INPUT_TEXT
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/deviceManagement/v1/peripheries/fields/{id}:
    delete:
      operationId: delete_api_deviceManagement_v1_peripheries_fields_id
      security:
        - DeviceManagementToken: []
      tags:
        - device management
      summary: Delete periphery-type additional field
      description: |
        Removes a custom additional-field definition (e.g. "serial number", "license key") attached to a periphery type. Standard CRUD permission checks for the device-management base data tables apply.
      parameters:
        - in: path
          name: id
          description: ID of the periphery-type additional field to delete.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_deviceManagement_v1_peripheries_fields_id
      security:
        - DeviceManagementToken: []
      tags:
        - device management
      summary: Get periphery-type additional field
      description: |
        Returns a single custom additional-field definition by id (title, periphery-type assignment, and field input type such as INPUT_TEXT).
      parameters:
        - in: path
          name: id
          description: ID of the periphery-type additional field to fetch.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The periphery-type additional-field definition.
              example:
                meta: {}
                content:
                  id: 1
                  peripheryTypeId: 4
                  title: Seriennummer
                  type: INPUT_TEXT
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_deviceManagement_v1_peripheries_fields_id
      security:
        - DeviceManagementToken: []
      tags:
        - device management
      summary: Update periphery-type additional field
      description: |
        Updates a custom additional-field definition for a periphery type (title or input type). Existing field contents stored against peripheries are kept; only the definition row is touched.
      parameters:
        - in: path
          name: id
          description: ID of the periphery-type additional field to update.
          required: true
          schema:
            type: integer
          example: 1
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - peripheryTypeId
              properties:
                id:
                  type: integer
                  description: Unique identifier of the additional field
                peripheryTypeId:
                  type: integer
                  description: Identifier of the periphery device type this field belongs to
                title:
                  type: string
                  description: Label of the additional field
                type:
                  type: string
                  description: Input type of the additional field
                  enum:
                    - INPUT_TEXT
            example:
              id: 42
              peripheryTypeId: 1
              title: Example title
              type:
                value: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The periphery-type additional-field definition.
              example:
                meta: {}
                content:
                  id: 1
                  peripheryTypeId: 4
                  title: Seriennummer
                  type: INPUT_TEXT
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/accountingtypes:
    get:
      operationId: get_api_erp_v1_accountingtypes
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get accounting types
      description: |
        Returns the list of all accounting types (Leistungsarten) configured in TANSS, used by the ERP system to map accounting categories during sync. This endpoint is intended for ERP integrations (e.g. Centron) and must be called with the dedicated API token bound to the role `ERP` — it is not exposed to normal user logins.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 1
                    name: Standard
                    percent: 100
                  - id: 2
                    name: Wartung
                    percent: 100
                  - id: 3
                    name: Garantie
                    percent: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_erp_v1_accountingtypes
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Create accounting type
      description: |
        Creates a new accounting type (Leistungsart) in TANSS so the ERP system can register categories it needs for billing/sync. Intended for ERP integrations (e.g. Centron); callers must authenticate with the dedicated API token bound to the role `ERP`, not with a normal user login.
      requestBody:
        description: An object describing the accounting category to create.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the accounting type.
                name:
                  type: string
                  description: Display name of the accounting type.
                active:
                  type: boolean
                  description: Whether the accounting type is currently active.
                articleNumber:
                  type: string
                  description: Article number associated with the accounting type.
            example:
              name: Wartung
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 4
                  name: Wartung
                  percent: 100
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/accountingtypes/prices:
    get:
      operationId: get_api_erp_v1_accountingtypes_prices
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get accounting type price
      description: |
        Returns the list of default accounting type prices (system-wide defaults, no company-specific overrides), used by ERP systems to retrieve current rates for billing/sync. Intended for ERP integrations (e.g. Centron) — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_erp_v1_accountingtypes_prices
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Save accounting type price
      description: |
        Creates a new default price entry for an accounting type, optionally scoped to a specific link (company or other entity); returns the persisted record. Intended for ERP integrations (e.g. Centron) — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountingTypeId
                - linkTypeId
                - linkId
              properties:
                accountingTypeId:
                  type: integer
                  description: Identifier of the accounting type this price belongs to.
                linkTypeId:
                  type: integer
                  description: Type of the linked entity the price applies to (for example ticket, contract, SLA or company).
                linkId:
                  type: integer
                  description: Identifier of the linked entity the price applies to.
                price:
                  type: number
                  description: Price value for this accounting type and linked entity combination.
            example:
              accountingTypeId: 1
              linkTypeId: 2
              linkId: 0
              price: 95
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/companies:
    post:
      operationId: post_api_erp_v1_companies
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Create company
      description: |
        Creates a new company (customer) record in TANSS from the supplied master data, so an ERP system can push newly onboarded customers into TANSS. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Unique identifier of the company
                displayId:
                  type: string
                  description: Human-readable display identifier of the company
                name:
                  type: string
                  description: Name of the company
                matchcode:
                  type: string
                  description: Short matchcode used for searching the company
                street:
                  type: string
                  description: Street address of the company
                postcode:
                  type: string
                  description: Postal code of the company address
                city:
                  type: string
                  description: City of the company address
                country:
                  type: string
                  description: Country of the company address
                email:
                  type: string
                  description: Primary email address of the company
                website:
                  type: string
                  description: Website URL of the company
                typeId:
                  type: integer
                  description: Identifier of the company type
                inactive:
                  type: boolean
                  description: Whether the company is marked inactive
            example:
              id: 42
              displayId: EXAMPLE-001
              name: Example name
              matchcode: EXAMPLE-001
              street: Hauptstraße 1
              postcode: '10115'
              city: Berlin
              country: DE
              email: user@example.com
              website: https://example.com
              typeId: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/companies/{id}:
    delete:
      operationId: delete_api_erp_v1_companies_id
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Delete company
      description: |
        Deletes the company identified by `id` along with its dependent data, behaving like the regular companies endpoint. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: id
          description: ID of the company to delete.
          required: true
          schema:
            type: integer
          example: 100023
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_erp_v1_companies_id
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get company
      description: |
        Returns the company record identified by `id` (matchcode, address, contact data, etc.), so the ERP system can read TANSS-side customer master data. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: id
          description: ID of the company to retrieve.
          required: true
          schema:
            type: integer
          example: 100023
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_erp_v1_companies_id
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Update company
      description: |
        Updates the company identified by `id` with the supplied fields, used by ERP integrations to push customer master-data changes back into TANSS. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: id
          description: ID of the company to update.
          required: true
          schema:
            type: integer
          example: 100023
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Unique identifier of the company
                displayId:
                  type: string
                  description: Human-readable display identifier of the company
                name:
                  type: string
                  description: Name of the company
                matchcode:
                  type: string
                  description: Short matchcode used for searching the company
                street:
                  type: string
                  description: Street address of the company
                postcode:
                  type: string
                  description: Postal code of the company address
                city:
                  type: string
                  description: City of the company address
                country:
                  type: string
                  description: Country of the company address
                email:
                  type: string
                  description: Primary email address of the company
                website:
                  type: string
                  description: Website URL of the company
                typeId:
                  type: integer
                  description: Identifier of the company type
                inactive:
                  type: boolean
                  description: Whether the company is marked inactive
            example:
              id: 42
              displayId: EXAMPLE-001
              name: Example name
              matchcode: EXAMPLE-001
              street: Hauptstraße 1
              postcode: '10115'
              city: Berlin
              country: DE
              email: user@example.com
              website: https://example.com
              typeId: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/companyCategories/{categoryId}:
    delete:
      operationId: delete_api_erp_v1_companyCategories_categoryId
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Delete category
      description: |
        Deletes the company category identified by `categoryId`. Intended for ERP integrations that maintain customer classifications from the ERP side — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: categoryId
          description: ID of the company category.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_erp_v1_companyCategories_categoryId
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get category
      description: |
        Returns the single company category identified by `categoryId`. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: categoryId
          description: ID of the company category.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_erp_v1_companyCategories_categoryId
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Create category
      description: |
        Creates a new company category from the supplied payload. Intended for ERP integrations that need to maintain customer classifications in TANSS — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: categoryId
          description: ID of the company category to create.
          required: true
          schema:
            type: string
          example: '1'
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Unique identifier of the company type category
                name:
                  type: string
                  description: Name of the category
                types:
                  type: array
                  description: Company types belonging to this category
                  items:
                    type: object
            example:
              id: 42
              name: Example name
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_erp_v1_companyCategories_categoryId
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Update category
      description: |
        Updates the company category identified by `categoryId` with the supplied fields. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: categoryId
          description: ID of the company category.
          required: true
          schema:
            type: integer
          example: 1
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Unique identifier of the company type category
                name:
                  type: string
                  description: Name of the category
                types:
                  type: array
                  description: Company types belonging to this category
                  items:
                    type: object
            example:
              id: 42
              name: Example name
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/employees:
    post:
      operationId: post_api_erp_v1_employees
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Create employee
      description: |
        Creates a new employee record in TANSS from the supplied payload, so an ERP system can push new staff/customer contacts into TANSS. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the employee.
                name:
                  type: string
                  description: Display name of the employee.
                firstName:
                  type: string
                  description: First name of the employee.
                lastName:
                  type: string
                  description: Last name of the employee.
                login:
                  type: string
                  description: Login user name of the employee.
                emailAddress:
                  type: string
                  description: Business email address of the employee.
                telephoneNumber:
                  type: string
                  description: Primary telephone number of the employee.
                mobilePhone:
                  type: string
                  description: Mobile phone number of the employee.
                departmentId:
                  type: integer
                  description: Identifier of the department the employee belongs to.
                titleId:
                  type: integer
                  description: Identifier of the employee's title.
                active:
                  type: boolean
                  description: Whether the employee account is active.
                language:
                  type: string
                  description: Preferred interface language code of the employee.
            example:
              id: 42
              name: Example name
              firstName: Max
              lastName: Mustermann
              departmentId: 1
              login: max.mustermann
              telephoneNumber: +49 30 1234567
              emailAddress: user@example.com
              mobilePhone: +49 30 1234567
              active: false
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/employees/{id}:
    get:
      operationId: get_api_erp_v1_employees_id
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get employees
      description: |
        Returns the single employee record identified by `id`, used by ERP integrations to read TANSS-side employee master data (contact info, department, ERP number, etc.). Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: id
          description: ID of the employee to retrieve.
          required: true
          schema:
            type: integer
          example: 5
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_erp_v1_employees_id
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Update employees
      description: |
        Updates the employee record identified by `id` with the supplied fields (e.g. department, ERP number, contact data). Used by ERP integrations to push employee master-data changes back into TANSS. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: id
          description: ID of the employee to update.
          required: true
          schema:
            type: integer
          example: 5
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the employee.
                name:
                  type: string
                  description: Display name of the employee.
                firstName:
                  type: string
                  description: First name of the employee.
                lastName:
                  type: string
                  description: Last name of the employee.
                login:
                  type: string
                  description: Login user name of the employee.
                emailAddress:
                  type: string
                  description: Business email address of the employee.
                telephoneNumber:
                  type: string
                  description: Primary telephone number of the employee.
                mobilePhone:
                  type: string
                  description: Mobile phone number of the employee.
                departmentId:
                  type: integer
                  description: Identifier of the department the employee belongs to.
                titleId:
                  type: integer
                  description: Identifier of the employee's title.
                active:
                  type: boolean
                  description: Whether the employee account is active.
                language:
                  type: string
                  description: Preferred interface language code of the employee.
            example:
              id: 42
              name: Example name
              firstName: Max
              lastName: Mustermann
              departmentId: 1
              login: max.mustermann
              telephoneNumber: +49 30 1234567
              emailAddress: user@example.com
              mobilePhone: +49 30 1234567
              active: false
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/types:
    get:
      operationId: get_api_erp_v1_types
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get company types
      description: |
        Returns the flat list of all company types (Firmen-Typen) configured in TANSS. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_erp_v1_types
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Create type
      description: |
        Creates a new company type (Firmen-Typ) and assigns it to a category. Intended for ERP integrations that need to seed customer classifications in TANSS — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Unique identifier of the company type
                name:
                  type: string
                  description: Name of the company type
                categoryId:
                  type: integer
                  description: Identifier of the category this type belongs to
                categoryName:
                  type: string
                  description: Name of the category this type belongs to
                icon:
                  type: string
                  description: Icon reference associated with the company type
                hidden:
                  type: boolean
                  description: Whether the company type is hidden
            example:
              id: 42
              name: Example name
              categoryId: 1
              icon: string
              hidden: false
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/erp/v1/types/{typeId}:
    delete:
      operationId: delete_api_erp_v1_types_typeId
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Delete type
      description: |
        Deletes the company type identified by `typeId`. Intended for ERP integrations that maintain customer classifications from the ERP side — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: typeId
          description: ID of the company type.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_erp_v1_types_typeId
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get type
      description: |
        Returns the single company type identified by `typeId`. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: typeId
          description: ID of the company type.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_erp_v1_types_typeId
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Update type
      description: |
        Updates the company type identified by `typeId` (e.g. its name, icon, or assigned category). Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: path
          name: typeId
          description: ID of the company type.
          required: true
          schema:
            type: integer
          example: 1
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Unique identifier of the company type
                name:
                  type: string
                  description: Name of the company type
                categoryId:
                  type: integer
                  description: Identifier of the category this type belongs to
                categoryName:
                  type: string
                  description: Name of the category this type belongs to
                icon:
                  type: string
                  description: Icon reference associated with the company type
                hidden:
                  type: boolean
                  description: Whether the company type is hidden
            example:
              id: 42
              name: Example name
              categoryId: 1
              icon: string
              hidden: false
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/servereye/v1/bucketitem/parse/{id}:
    get:
      operationId: get_api_servereye_v1_bucketitem_parse_id
      security:
        - MonitoringToken: []
      tags:
        - monitoring
      summary: Parse Server-Eye bucket item
      description: Parses a previously-fetched Server-Eye bucket item (identified by its stored-item id) into the matching TANSS entities and marks it as processed. Returns `OBJECT_NOT_FOUND` if the stored item does not exist and `ITEM_WAS_ALREADY_PARSED` if it was already handled. Used by the Server-Eye external monitoring integration; usually called via an external API token bearing the `MONITORING` role.
      parameters:
        - in: path
          name: id
          description: ID of the stored Server-Eye bucket item to parse.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The parsed Server-Eye bucket item.
              example:
                meta: {}
                content:
                  container:
                    cId: abc123
                  type: Sensor
                  state:
                    sId: '1'
                    error: true
                    stateId: 3
                  customer:
                    cId: cust-100023
                    number: K-100023
                  agent:
                    aId: agent-9
                    type: CPU
                  tanssCompanyId: 100023
                  linkTypeId: 1
                  linkId: 100
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/servereye/v1/fetch:
    get:
      operationId: get_api_servereye_v1_fetch
      security:
        - MonitoringToken: []
      tags:
        - monitoring
      summary: Fetch Server-Eye bucket items
      description: Triggers a fetch of new bucket items from the Server-Eye monitoring API and returns the items that were just retrieved. Used by the Server-Eye external monitoring integration; usually called via an external API token bearing the `MONITORING` role.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of Server-Eye bucket items retrieved during the fetch.
              example:
                meta: {}
                content:
                  - container:
                      cId: abc123
                    type: Sensor
                    state:
                      sId: '1'
                      error: true
                      stateId: 3
                    customer:
                      cId: cust-100023
                      number: K-100023
                    tanssCompanyId: 100023
                    linkTypeId: 1
                    linkId: 100
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/systemhaus_one/v1/externalIds:
    post:
      operationId: post_api_systemhaus_one_v1_externalIds
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Create external id
      description: |
        Creates a new mapping between a TANSS entity (identified by `linkTypeId`/`linkId`) and its external identifier in the connected SAP Business One system. Intended for the SAP B1 ERP integration — must be called with the dedicated API token bound to the role `ERP`, not a normal user login; the `SAP_ONE` module must be licensed.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                linkTypeId:
                  type: integer
                  description: Type of the linked object the external assignment refers to
                linkId:
                  type: integer
                  description: ID of the linked object the external assignment refers to
                prog:
                  type: string
                  description: External program or system the assignment belongs to
                  enum:
                    - NONE
                extId:
                  type: string
                  description: Identifier of the object within the external system
            example:
              linkTypeId: 1
              linkId: 100023
              extId: SAP-1023
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_systemhaus_one_v1_externalIds
      security:
        - ErpToken: []
      tags:
        - erp
      summary: Get external ids
      description: |
        Returns the external identifiers (SAP B1 IDs) for the TANSS entities listed in the request body (link type plus a list of link IDs). Uses `PUT` so that the variable-length list of IDs can be supplied as a JSON body rather than a long query string. Intended for the SAP B1 ERP integration — must be called with the dedicated API token bound to the role `ERP`, not a normal user login; the `SAP_ONE` module must be licensed.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                linkTypeId:
                  type: integer
                  description: Type of the linked objects the external IDs apply to
                linkIds:
                  type: array
                  description: IDs of the linked objects to resolve external IDs for
                  items:
                    type: object
            example:
              linkTypeId: 1
              linkIds:
                - 100023
                - 100024
                - 100025
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/timestamps/v1:
    post:
      operationId: post_api_timestamps_v1
      security:
        - TimestampToken: []
      tags:
        - timestamp
      summary: Create timestamp
      description: |-
        Records a single time stamp (Stempeluhr punch) for the calling employee — e.g. clocking on, off, starting a pause
        or switching the work-time type. When `autoPause=true`, the service skips the minimum-pause check that normally
        blocks an OFF/WORK punch if the legally required break for the day has not been reached yet.
      parameters:
        - in: query
          name: autoPause
          required: false
          description: Skip the minimum-pause check when recording the punch
          example: true
          schema:
            type: boolean
            default: false
      requestBody:
        description: Timestamp punch to record (the request payload).
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              employeeId: 5
              date: 1748256000
              state: 'ON'
              type: WORK
      responses:
        '201':
          description: Timestamp was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The persisted timestamp.
              example:
                meta: {}
                content:
                  id: 1
                  employeeId: 5
                  date: 1748256000
                  state: 'ON'
                  type: WORK
                  duration: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/accountingTypes:
    get:
      operationId: get_api_v1_accountingTypes
      tags:
        - accounting types
      summary: Get all entities
      description: |
        Returns every accounting type configured in the system, including inactive ones. Standard admin list filters are applied before the payload is built. Callable by technicians and freelancers; modifying operations additionally require `MANAGE_ACCOUNTING_TYPES`.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Standard
                        active:
                          type: boolean
                          example: true
                        articleNumber:
                          type: string
                          example: ART-001
              example:
                meta: {}
                content:
                  - id: 1
                    name: Standard
                    active: true
                    articleNumber: ART-001
                  - id: 2
                    name: Anfahrt
                    active: true
                    articleNumber: ART-DRIVE
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_accountingTypes
      tags:
        - accounting types
      summary: Create entity
      description: |
        Creates a new accounting type entry that can later be referenced from services, contracts, and tickets. Requires `MANAGE_ACCOUNTING_TYPES`; the entry is validated and persisted via the default CRUD lifecycle.
      requestBody:
        description: JSON body. An object.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the accounting type.
                name:
                  type: string
                  description: Display name of the accounting type.
                active:
                  type: boolean
                  description: Whether the accounting type is currently active.
                articleNumber:
                  type: string
                  description: Article number associated with the accounting type.
            example:
              id: 0
              name: Standard
              active: true
              articleNumber: ART-001
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: Standard
                      active:
                        type: boolean
                        example: true
                      articleNumber:
                        type: string
                        example: ART-001
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
                  active: true
                  articleNumber: ART-001
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/accountingTypes/prices:
    post:
      operationId: post_api_v1_accountingTypes_prices
      tags:
        - accounting types
      summary: Create or update accounting type price
      description: |
        Upserts the price for an accounting type at a given assignment (company, contract, or ticket). The controller validates the linked accounting type, delegates the access check to the link-type strategy, and returns `201` when the row is created or `202` when an existing one is updated. The accounting type price cache is cleared after persisting.
      requestBody:
        description: An object describing the accounting type id, link type/id, and the new price.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsAccountingTypePrice'
            example:
              accountingTypeId: 3
              linkTypeId: 2
              linkId: 1000
              price: 95
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/TnsAccountingTypePrice'
              example:
                meta: {}
                content:
                  accountingTypeId: 3
                  linkTypeId: 2
                  linkId: 1000
                  price: 95
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/accountingTypes/prices/{accountingTypeId}/{linkTypeId}/{linkId}:
    delete:
      operationId: delete_api_v1_accountingTypes_prices_accountingTypeId_linkTypeId_linkId
      tags:
        - accounting types
      summary: Delete accounting type price
      description: |
        Removes the price entry for the given accounting type / link combination (company, contract, or ticket). Access is delegated to the matching link-type strategy, and the accounting type price cache is invalidated afterwards so subsequent price lookups see the change.
      parameters:
        - in: path
          name: accountingTypeId
          required: true
          description: Id of the accounting type whose price entry should be deleted.
          schema:
            type: integer
          example: 1
        - in: path
          name: linkTypeId
          required: true
          description: Link type of the assignment (company, contract, or ticket).
          schema:
            type: integer
          example: 1
        - in: path
          name: linkId
          required: true
          description: Id of the linked entity the price is attached to.
          schema:
            type: integer
          example: 4711
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/accountingTypes/{id}:
    delete:
      operationId: delete_api_v1_accountingTypes_id
      tags:
        - accounting types
      summary: Delete accounting type by id
      description: |
        Generic admin delete endpoint. Used by accounting types, currencies, payment methods, etc.; Requires the corresponding admin permission (e.g. `MANAGE_ACCOUNTING_TYPES` or `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`) and checks for blocking references before the row is removed.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the accounting type.
          schema:
            type: string
          example: '42'
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_accountingTypes_id
      tags:
        - accounting types
      summary: Get accounting type by id
      description: |
        Generic admin read endpoint. Returns the single configured entity (accounting type, currency, payment method, etc.) addressed by `id`. Standard admin access checks apply.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the accounting type.
          schema:
            type: string
          example: '42'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    example:
                      id: 1
                      name: Standard
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_accountingTypes_id
      tags:
        - accounting types
      summary: Edit accounting type by id
      description: |
        Generic admin update endpoint. Applies the JSON patch to the entity addressed by `id` and persists it. Requires the corresponding admin permission (e.g. `MANAGE_ACCOUNTING_TYPES`, `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`).
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the accounting type.
          schema:
            type: string
          example: '42'
      requestBody:
        description: JSON body with the updated entity fields.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              id: 1
              name: Standard
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    example:
                      id: 1
                      name: Standard
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/additionalCharges:
    get:
      operationId: get_api_v1_additionalCharges
      tags:
        - additional charges
      summary: Get all overtime additional charges
      description: |
        Returns all configured overtime additional-charge rules (`zuschlag` table). These rules define percentage surcharges that apply to supports (time entries) booked on specific weekdays/time ranges, scoped by company, contract and link type. Requires the `MANAGE_OVERTIME_DEFINITIONS` permission and technician/freelancer status.
      parameters:
        - in: query
          name: companyId
          required: false
          description: Filter the additional-charge rules to a single company.
          schema:
            type: integer
          example: 100023
        - in: query
          name: contractId
          required: false
          description: Filter the additional-charge rules to a single contract.
          schema:
            type: integer
          example: 17
      responses:
        '200':
          description: List of overtime additional charges.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - companyId: 100023
                    contractId: 17
                    linkTypeId: 1
                    linkId: 0
                    day: MONDAY
                    number: 1
                    startTime: '18:00'
                    endTime: '22:00'
                    percent: 25
                  - companyId: 100023
                    contractId: 17
                    linkTypeId: 1
                    linkId: 0
                    day: SATURDAY
                    number: 1
                    startTime: '00:00'
                    endTime: '23:59'
                    percent: 50
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_additionalCharges
      tags:
        - additional charges
      summary: Create overtime additional charge
      description: |
        Creates a new overtime additional-charge definition. The composite key consists of `companyId`, `contractId`, `linkTypeId`, `linkId`, `day` and `number`; `number` is auto-assigned when omitted. Overlapping time ranges within the same scope/day are rejected. Requires the `MANAGE_OVERTIME_DEFINITIONS` permission.
      requestBody:
        description: Body the request payload. `startTime`/`endTime` use `HH:mm` strings; `percent` is the surcharge percentage applied to the support price.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              companyId: 100023
              contractId: 17
              linkTypeId: 1
              linkId: 0
              day: FRIDAY
              number: 1
              startTime: '18:00'
              endTime: '22:00'
              percent: 25
      responses:
        '201':
          description: Overtime additional charge created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  companyId: 100023
                  contractId: 17
                  linkTypeId: 1
                  linkId: 0
                  day: FRIDAY
                  number: 1
                  startTime: '18:00'
                  endTime: '22:00'
                  percent: 25
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_additionalCharges
      tags:
        - additional charges
      summary: Update overtime additional charge
      description: |
        Updates an existing overtime additional-charge rule identified by its composite key (`companyId`, `contractId`, `linkTypeId`, `linkId`, `day`, `number`). The service re-validates the timeframe and rejects overlaps with other charges in the same scope. Logs old/new values for the change. Requires the `MANAGE_OVERTIME_DEFINITIONS` permission.
      requestBody:
        description: Body the request payload. All composite-key fields must be present so the entity can be located; mutable fields are `startTime`, `endTime`, `percent`.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              companyId: 100023
              contractId: 17
              linkTypeId: 1
              linkId: 0
              day: FRIDAY
              number: 1
              startTime: '17:00'
              endTime: '22:00'
              percent: 30
      responses:
        '200':
          description: Updated overtime additional charge.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  companyId: 100023
                  contractId: 17
                  linkTypeId: 1
                  linkId: 0
                  day: FRIDAY
                  number: 1
                  startTime: '17:00'
                  endTime: '22:00'
                  percent: 30
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/additionalCharges/delete:
    post:
      operationId: post_api_v1_additionalCharges_delete
      tags:
        - additional charges
      summary: Delete overtime additional charge
      description: Deletes the overtime additional-charge rule identified by its composite key (`companyId`, `contractId`, `linkTypeId`, `linkId`, `day`, `number`). Uses POST because the key must be sent in the body. After deletion the service fills the resulting time gap with a 0%-filler. Requires the `MANAGE_OVERTIME_DEFINITIONS` permission.
      requestBody:
        description: Composite id of the overtime additional charge to delete.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: integer
                  description: Identifier of the company the additional charge applies to
                contractId:
                  type: integer
                  description: Identifier of the maintenance contract the charge belongs to
                linkTypeId:
                  type: integer
                  description: Type of the linked entity the charge is attached to
                linkId:
                  type: integer
                  description: Identifier of the linked entity the charge is attached to
                day:
                  type: string
                  description: Weekday or special day the charge applies to
                  enum:
                    - SUNDAY
                    - MONDAY
                    - TUESDAY
                    - WEDNESDAY
                    - THURSDAY
                    - FRIDAY
                    - SATURDAY
                    - EVERYDAY
                    - HOLIDAY
                    - HOLIDAY_AM
                    - HOLIDAY_PM
                number:
                  type: integer
                  description: Sequential number of the charge within its group
            example:
              companyId: 100023
              contractId: 17
              linkTypeId: 1
              linkId: 0
              day: FRIDAY
              number: 1
      responses:
        '201':
          description: Deletion result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/permissionPackages:
    get:
      operationId: get_api_v1_admin_permissionPackages
      tags:
        - permission packages
      summary: List permission packages
      description: |
        Returns all permission packages, sorted by name. When `withPermissions=true`
        each package also carries its categories and contained permissions. Caller
        must be from the own company and hold `MANAGE_PERMISSION_PACKAGES`.
      parameters:
        - in: query
          name: withPermissions
          description: When true, each package also includes its categories and contained permissions.
          required: false
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        info:
                          type: string
                        type:
                          type: integer
              example:
                meta: {}
                content:
                  - id: 1
                    name: Standard Technician
                    info: Default permissions for technicians
                    type: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_admin_permissionPackages
      tags:
        - permission packages
      summary: Create a permission package
      description: |
        Creates a new permission package. Caller must be from the own company and
        hold `MANAGE_PERMISSION_PACKAGES`.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the permission package
                name:
                  type: string
                  description: Display name of the permission package
                info:
                  type: string
                  description: Descriptive information about the permission package
                type:
                  type: string
                  description: User category this permission package applies to
                  enum:
                    - TECHNICIAN
                    - FREELANCER
                    - RESTRICTED_USER
                    - CUSTOMER
                categories:
                  type: array
                  description: Permission category definitions contained in the package
                  items:
                    type: object
            example:
              name: Standard Technician
              info: Default permissions for technicians
              type: 1
      responses:
        '201':
          description: Created permission package.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard Technician
                  info: Default permissions for technicians
                  type: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_admin_permissionPackages
      tags:
        - permission packages
      summary: Toggle permissions of a permission package
      description: |
        Toggles each `permissionId` in the comma-separated list inside the given
        `packageId`: permissions currently in the package are removed, those not
        in it are added. Caller must be from the own company and hold
        `MANAGE_PERMISSION_PACKAGES`.
      parameters:
        - in: query
          name: packageId
          description: Id of the permission package whose permissions should be toggled.
          required: true
          schema:
            type: integer
          example: 1
        - in: query
          name: permissionIds
          description: Comma-separated list of permission ids to toggle within the package.
          required: true
          schema:
            type: string
          example: 12,33,45
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/permissionPackages/{packageId}:
    delete:
      operationId: delete_api_v1_admin_permissionPackages_packageId
      tags:
        - permission packages
      summary: Delete a permission package
      description: |-
        Deletes the permission package identified by `packageId`; all permissions
        contained in the package are unlinked via an `afterDelete` hook. Caller
        must be from the own company and hold `MANAGE_PERMISSION_PACKAGES`.
      parameters:
        - in: path
          name: packageId
          description: Id of the permission package to delete.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_admin_permissionPackages_packageId
      tags:
        - permission packages
      summary: Get a permission package by id
      description: |-
        Returns a single permission package (with its permissions) by id.
        Caller must be from the own company and hold `MANAGE_PERMISSION_PACKAGES`.
      parameters:
        - in: path
          name: packageId
          description: Id of the permission package to return.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      info:
                        type: string
                      type:
                        type: integer
                      permissions:
                        type: array
                        items:
                          type: integer
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard Technician
                  info: Default permissions for technicians
                  type: 1
                  permissions:
                    - 12
                    - 33
                    - 45
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_admin_permissionPackages_packageId
      tags:
        - permission packages
      summary: Update a permission package
      description: |-
        Updates a permission package (name, info, type). Caller must be from the
        own company and hold `MANAGE_PERMISSION_PACKAGES`.
      parameters:
        - in: path
          name: packageId
          description: Id of the permission package to update.
          required: true
          schema:
            type: integer
          example: 1
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the permission package
                name:
                  type: string
                  description: Display name of the permission package
                info:
                  type: string
                  description: Descriptive information about the permission package
                type:
                  type: string
                  description: User category this permission package applies to
                  enum:
                    - TECHNICIAN
                    - FREELANCER
                    - RESTRICTED_USER
                    - CUSTOMER
                categories:
                  type: array
                  description: Permission category definitions contained in the package
                  items:
                    type: object
            example:
              id: 1
              name: Standard Technician
              info: Default permissions for technicians
              type: 1
      responses:
        '200':
          description: Updated permission package.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard Technician
                  info: Default permissions for technicians
                  type: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/permissionPackages/{packageId}/category/{categoryId}:
    delete:
      operationId: delete_api_v1_admin_permissionPackages_packageId_category_categoryId
      tags:
        - permission packages
      summary: Remove all permissions of a category from a package
      description: |
        Removes every permission belonging to the given category from the given
        permission package. Caller must be from the own company and hold
        `MANAGE_PERMISSION_PACKAGES`.
      parameters:
        - in: path
          name: packageId
          description: Id of the permission package to modify.
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: categoryId
          description: Id of the permission category whose permissions should be removed.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_admin_permissionPackages_packageId_category_categoryId
      tags:
        - permission packages
      summary: Add all permissions of a category to a package
      description: |
        Adds every permission belonging to the given category to the given
        permission package. Caller must be from the own company and hold
        `MANAGE_PERMISSION_PACKAGES`.
      parameters:
        - in: path
          name: packageId
          description: Id of the permission package to modify.
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: categoryId
          description: Id of the permission category whose permissions should be added.
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/ticketStates/attention:
    get:
      operationId: get_api_v1_admin_ticketStates_attention
      tags:
        - ticket states
      summary: Get attention items
      description: |-
        Returns the configured attention items (icon + type combinations) used to flag
        tickets needing attention. Used by the admin UI for "Aufmerksamkeit"
        configuration.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Configured attention items.
              example:
                meta: {}
                content:
                  - type: URGENT
                    fileName: urgent.png
                  - type: OVERDUE
                    fileName: overdue.png
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/ticketStates/attention/{attentionType}:
    post:
      operationId: post_api_v1_admin_ticketStates_attention_attentionType
      tags:
        - ticket states
      summary: Upload attention item
      description: |-
        Uploads an attention icon image for a specific attention type (e.g. urgent,
        overdue). With `overwrite=true` an existing image is replaced, otherwise the
        call fails if an image is already present. Requires admin permission on the
        attention aspect.
      parameters:
        - in: path
          name: attentionType
          example: URGENT
          required: true
          schema:
            type: string
        - in: query
          name: overwrite
          description: When true, replace an existing attention image; otherwise the call fails if one is present.
          example: false
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The persisted attention record.
              example:
                meta: {}
                content:
                  type: URGENT
                  fileName: urgent.png
                  uploadedAt: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/ticketStates/images:
    delete:
      operationId: delete_api_v1_admin_ticketStates_images
      tags:
        - ticket states
      summary: Delete ticket image
      description: |-
        Deletes an uploaded ticket-state icon by file name. Requires admin permission
        on the ticket-state-image aspect.
      parameters:
        - in: query
          name: imageName
          description: File name of the ticket-state icon to delete.
          example: Beispiel
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_admin_ticketStates_images
      tags:
        - ticket states
      summary: Get ticket images
      description: |-
        Returns the list of uploaded ticket-state icon file names available for use on
        ticket states. Requires admin permission on the ticket-state-image aspect.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Available image file names.
              example:
                meta: {}
                content:
                  - open.png
                  - in-progress.png
                  - done.png
                  - waiting.png
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_admin_ticketStates_images
      tags:
        - ticket states
      summary: Upload ticket image
      description: |-
        Uploads one or more icon images (multipart `files` field) for use on ticket
        states. Returns the stored file names. Requires admin permission on the
        ticket-state-image aspect.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: File names assigned to the uploaded images.
              example:
                meta: {}
                content:
                  - custom-priority-high.png
                  - custom-priority-low.png
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/ticketTypes:
    get:
      operationId: get_api_v1_admin_ticketTypes
      tags:
        - ticket types
      summary: Get all entities
      description: |-
        Returns all ticket types — both active and inactive — for admin
        configuration. Use `GET /api/v1/tickets/types` for the active-only list shown
        in ticket-edit drop-downs.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: All ticket types (active and inactive).
              example:
                meta: {}
                content:
                  - id: 1
                    name: Incident
                    useReactionHours: true
                    active: true
                  - id: 2
                    name: Service Request
                    useReactionHours: false
                    active: true
                  - id: 3
                    name: Project
                    useReactionHours: false
                    active: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_admin_ticketTypes
      tags:
        - ticket types
      summary: Create entity
      description: Creates a new ticket type. Requires ticket-type-administration permission.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the ticket type.
                name:
                  type: string
                  description: Display name of the ticket type.
                useReactionHours:
                  type: boolean
                  description: Whether reaction-time hours apply to this ticket type.
                active:
                  type: boolean
                  description: Whether the ticket type is currently active.
            example:
              id: 42
              name: Example name
              useReactionHours: false
              active: false
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created ticket type.
              example:
                meta: {}
                content:
                  id: 4
                  name: Change
                  useReactionHours: false
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/admin/ticketTypes/{id}:
    delete:
      operationId: delete_api_v1_admin_ticketTypes_id
      tags:
        - ticket types
      summary: Delete entity
      description: |-
        Deletes a ticket type by id. Fails if tickets still reference this type
        (linked-entity delete check via the ticket type service). Requires
        ticket-type-administration permission.
      parameters:
        - in: path
          name: id
          description: Id of the ticket type.
          example: '42'
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_admin_ticketTypes_id
      tags:
        - ticket types
      summary: Get entity
      description: Returns a single ticket type by id.
      parameters:
        - in: path
          name: id
          description: Id of the ticket type.
          example: '42'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The ticket type.
              example:
                meta: {}
                content:
                  id: 1
                  name: Incident
                  useReactionHours: true
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_admin_ticketTypes_id
      tags:
        - ticket types
      summary: Edit entity
      description: |-
        Updates fields of an existing ticket type (name, `useReactionHours` flag,
        `active`). Requires ticket-type-administration permission.
      parameters:
        - in: path
          name: id
          description: Id of the ticket type.
          example: '42'
          required: true
          schema:
            type: string
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the ticket type.
                name:
                  type: string
                  description: Display name of the ticket type.
                useReactionHours:
                  type: boolean
                  description: Whether reaction-time hours apply to this ticket type.
                active:
                  type: boolean
                  description: Whether the ticket type is currently active.
            example:
              id: 42
              name: Example name
              useReactionHours: false
              active: false
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The ticket type.
              example:
                meta: {}
                content:
                  id: 1
                  name: Incident
                  useReactionHours: true
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/assignments/company/{companyId}:
    get:
      operationId: get_api_v1_assignments_company_companyId
      tags:
        - assignments
      summary: List assignments selectable for a company
      description: |-
        Returns the tree of assignments (devices, contracts, locations, custom assignment types) that can be picked when linking
        something to the given company — used by the assignment-picker dialog in tickets and supports. Pass `branches=true` to include
        assignments of the company's child branches in addition to its own.
      parameters:
        - in: path
          name: companyId
          required: true
          description: ID of the company whose pickable assignments should be returned.
          example: 100023
          schema:
            type: integer
        - in: query
          name: branches
          required: false
          description: If 'true', also include assignments of the company's child branches.
          example: 'false'
          schema:
            type: string
            default: 'false'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Pickable assignments for the company (and optionally its branches).
              example:
                meta: {}
                content:
                  - id: 1
                    sourceType: TICKET
                    sourceId: 4711
                    targetType: DEVICE
                    targetId: 100
                    type: AFFECTS
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/assignments/flags/{linkTypeId}/{linkId}:
    get:
      operationId: get_api_v1_assignments_flags_linkTypeId_linkId
      tags:
        - assignments
      summary: Get flag icons for an assignment
      description: |-
        Returns the list of "flag icons" (small status badges like "VIP customer", "maintenance contract active", "device in service")
        that should be shown next to an assignment in the ticket header. The assignment is addressed by its `linkTypeId` + `linkId`;
        access to the underlying company is required.
      parameters:
        - in: path
          name: linkTypeId
          required: true
          description: Link type ID identifying the kind of assignment.
          example: 1
          schema:
            type: integer
        - in: path
          name: linkId
          required: true
          description: ID of the linked assignment object.
          example: 4711
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of flag-icon descriptors.
              example:
                meta: {}
                content:
                  - id: 1
                    sourceType: TICKET
                    sourceId: 4711
                    targetType: DEVICE
                    targetId: 100
                    type: AFFECTS
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/availability/types:
    get:
      operationId: get_api_v1_availability_types
      tags:
        - availability
      summary: Get availability types
      description: |
        Returns the configured catalog of availability types used to mark an employee as unavailable on a given day (for example `Urlaub`, `Krank`, `Feiertag`, `Fortbildung`). The list is rendered as picker entries in the planning UI and is administered via the dedicated CRUD service. Read access uses the standard list controller action; managing the catalog requires `MANAGE_QUICK_STATUS` and access to all companies.
      responses:
        '200':
          description: List of availability types.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 1
                    name: Urlaub
                  - id: 2
                    name: Krank
                  - id: 3
                    name: Feiertag
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/bankaccounts:
    get:
      operationId: get_api_v1_bankaccounts
      tags:
        - company - master data
      summary: Get all bank accounts
      description: |
        Returns the full list of object records stored in the system, regardless of which company they belong to. Used by the bookkeeping / billing UI to populate selection lists. Standard permission checks apply: requires an authenticated technician or freelancer with access to the bank-account data.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: List of bank accounts.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 17
                        companyId:
                          type: integer
                          example: 100023
                        countingNumber:
                          type: integer
                          example: 1
                        bank:
                          type: string
                          example: Sparkasse Berlin
                        blz:
                          type: string
                          example: '10050000'
                        bic:
                          type: string
                          example: BELADEBEXXX
                        accountOwner:
                          type: string
                          example: Beispiel GmbH
                        accountNumber:
                          type: string
                          example: '1234567890'
                        iban:
                          type: string
                          example: DE89100500000123456789
                        mandateReference:
                          type: string
                          example: MAND-2024-017
                        mandateReferenceDate:
                          type: integer
                          example: 1748256000
                        sequenceTypeDebitId:
                          type: integer
                          example: 1
                        currencyId:
                          type: integer
                          example: 1
                        debits:
                          type: boolean
                          example: true
                        transfers:
                          type: boolean
                          example: true
                        cheques:
                          type: boolean
                          example: false
              example:
                meta: {}
                content:
                  - id: 17
                    companyId: 100023
                    countingNumber: 1
                    bank: Sparkasse Berlin
                    blz: '10050000'
                    bic: BELADEBEXXX
                    accountOwner: Beispiel GmbH
                    accountNumber: '1234567890'
                    iban: DE89100500000123456789
                    mandateReference: MAND-2024-017
                    mandateReferenceDate: 1748256000
                    sequenceTypeDebitId: 1
                    currencyId: 1
                    debits: true
                    transfers: true
                    cheques: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_bankaccounts
      tags:
        - company - master data
      summary: Create bank account
      description: |
        Creates a new object and persists it. The bank account is linked to a company via `companyId` and stores bank details (IBAN/BIC, account owner, mandate info) used for invoicing and SEPA debits. Standard administrative permission checks apply, so only technicians or freelancers with the bank-account management right may create entries.
      requestBody:
        description: An object to be persisted.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: integer
                countingNumber:
                  type: integer
                bank:
                  type: string
                blz:
                  type: string
                bic:
                  type: string
                accountOwner:
                  type: string
                accountNumber:
                  type: string
                iban:
                  type: string
                mandateReference:
                  type: string
                mandateReferenceDate:
                  type: integer
                sequenceTypeDebitId:
                  type: integer
                currencyId:
                  type: integer
                debits:
                  type: boolean
                transfers:
                  type: boolean
                cheques:
                  type: boolean
            example:
              companyId: 100023
              bank: Sparkasse Berlin
              bic: BELADEBEXXX
              accountOwner: Beispiel GmbH
              iban: DE89100500000123456789
              mandateReference: MAND-2024-017
              currencyId: 1
              debits: true
              transfers: true
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: The created bank account (including its newly assigned `id`).
              example:
                meta: {}
                content:
                  id: 42
                  companyId: 100023
                  countingNumber: 1
                  bank: Sparkasse Berlin
                  bic: BELADEBEXXX
                  accountOwner: Beispiel GmbH
                  iban: DE89100500000123456789
                  mandateReference: MAND-2024-017
                  mandateReferenceDate: 1748256000
                  sequenceTypeDebitId: 1
                  currencyId: 1
                  debits: true
                  transfers: true
                  cheques: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/bankaccounts/{id}:
    get:
      operationId: get_api_v1_bankaccounts_id
      tags:
        - company - master data
      summary: Get bank account
      description: |
        Returns a single object by its id. Standard permission checks apply: requires an authenticated technician or freelancer with access to the bank-account data.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the bank account.
          example: 17
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 17
                      companyId:
                        type: integer
                        example: 100023
                      countingNumber:
                        type: integer
                        example: 1
                      bank:
                        type: string
                        example: Sparkasse Berlin
                      blz:
                        type: string
                        example: '10050000'
                      bic:
                        type: string
                        example: BELADEBEXXX
                      accountOwner:
                        type: string
                        example: Beispiel GmbH
                      accountNumber:
                        type: string
                        example: '1234567890'
                      iban:
                        type: string
                        example: DE89100500000123456789
                      mandateReference:
                        type: string
                        example: MAND-2024-017
                      mandateReferenceDate:
                        type: integer
                        example: 1748256000
                      sequenceTypeDebitId:
                        type: integer
                        example: 1
                      currencyId:
                        type: integer
                        example: 1
                      debits:
                        type: boolean
                        example: true
                      transfers:
                        type: boolean
                        example: true
                      cheques:
                        type: boolean
                        example: false
              example:
                meta: {}
                content:
                  id: 17
                  companyId: 100023
                  countingNumber: 1
                  bank: Sparkasse Berlin
                  blz: '10050000'
                  bic: BELADEBEXXX
                  accountOwner: Beispiel GmbH
                  accountNumber: '1234567890'
                  iban: DE89100500000123456789
                  mandateReference: MAND-2024-017
                  mandateReferenceDate: 1748256000
                  sequenceTypeDebitId: 1
                  currencyId: 1
                  debits: true
                  transfers: true
                  cheques: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_bankaccounts_id
      tags:
        - company - master data
      summary: Update bank account
      description: |
        Updates an existing bank account with the supplied values. Only the fields present in the payload are changed. Standard permission checks apply.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the bank account to update.
          example: 17
          schema:
            type: integer
      requestBody:
        description: The bank-account values to update.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: integer
                  example: 100023
                bank:
                  type: string
                  example: Sparkasse Berlin
                blz:
                  type: string
                  example: '10050000'
                bic:
                  type: string
                  example: BELADEBEXXX
                accountOwner:
                  type: string
                  example: Beispiel GmbH
                accountNumber:
                  type: string
                  example: '1234567890'
                iban:
                  type: string
                  example: DE89100500000123456789
                mandateReference:
                  type: string
                  example: MAND-2024-017
                mandateReferenceDate:
                  type: integer
                  example: 1748256000
                sequenceTypeDebitId:
                  type: integer
                  example: 1
                currencyId:
                  type: integer
                  example: 1
                debits:
                  type: boolean
                  example: true
                transfers:
                  type: boolean
                  example: true
                cheques:
                  type: boolean
                  example: false
            example:
              bank: Sparkasse Berlin
              iban: DE89100500000123456789
              accountOwner: Beispiel GmbH
              mandateReference: MAND-2024-017
      responses:
        '200':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 17
                  companyId: 100023
                  bank: Sparkasse Berlin
                  iban: DE89100500000123456789
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/cache/clear/{cacheType}:
    get:
      operationId: get_api_v1_cache_clear_cacheType
      tags:
        - util routes
      summary: Clear cache
      description: |
        Clears one of the in-memory caches by name. Supported `cacheType` values include
        `deviceType`, `componentType`, `softwarelicenseType`, `employeeRights`, `companyHqs`, `localTicketAdmin`,
        `contract`, `employeeName`, `amountingTypePrice`, and `supportTypes`. Some types (e.g. `employeeRights`,
        `companyHqs`, `contract`, `employeeName`) require the optional `id` query parameter to address a single
        entry — `companyHqs` additionally invalidates the local-ticket-admin cache as a side effect.

        Returns `404` for unknown cache names.
      parameters:
        - in: path
          name: cacheType
          required: true
          description: Name of the in-memory cache to clear (e.g. `deviceType`, `employeeRights`, `companyHqs`).
          schema:
            type: string
          example: deviceType
        - in: query
          name: id
          required: false
          description: Optional id of a single cache entry to invalidate (required for id-scoped caches).
          schema:
            type: string
            default: ''
          example: '42'
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty content; only `meta.text = FOUND` is set.
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/callbacks/{id}/state:
    post:
      operationId: post_api_v1_callbacks_id_state
      tags:
        - callback
      summary: Change callback state
      description: |
        Records a state change for an existing callback (Rückruf) — e.g. moving it from `UNSEEN` to `DONE` or `RESCHEDULED` — and appends a corresponding entry to the callback's state log. The request body must carry the new `state` (an optional `infoText` is stored as the log comment). The caller must have access to the underlying callback; the created log entry is returned so the client can render it without a re-fetch.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the callback whose state is being changed.
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackId:
                  type: integer
                  description: Identifier of the callback this log entry belongs to
                date:
                  type: integer
                  format: int64
                  description: Timestamp when the state change occurred
                state:
                  type: string
                  description: State recorded for the callback
                  enum:
                    - UNSEEN
                    - NEW
                    - NOBODY_ANSWERED
                    - BUSY
                    - NOT_PRESENT
                    - NEW_CALLBACK_REENTERED
                    - COMPLETED
                    - EXPECTED_CALLBACK
                    - EXPECTED_CALLBACK_COMPLETED
                infoText:
                  type: string
                  description: Free-text note describing the state change
                employeeId:
                  type: integer
                  description: Identifier of the employee who triggered the state change
      responses:
        '200':
          description: The created state log entry.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 87
                  callbackId: 1
                  employeeId: 5
                  state: DONE
                  date: 1748256000
                  info: Kunde erreicht, Angebot bestätigt
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/cars:
    post:
      operationId: post_api_v1_cars
      tags:
        - cars
      summary: Create car
      description: |
        Persists a new car entry for the company car pool. The request payload is filtered against the caller's permissions: only technicians/freelancers from the own company with `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` may submit fields; everyone else effectively gets the body cleared before persistence.
      requestBody:
        description: An object.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Unique identifier of the car
                numberPlate:
                  type: string
                  description: License plate of the car
                manufacturer:
                  type: string
                  description: Manufacturer of the car
                type:
                  type: string
                  description: Model or type designation of the car
                active:
                  type: boolean
                  description: Whether the car is currently active
                initialRegistrationYear:
                  type: integer
                  description: Year of initial registration
                activeFromDate:
                  type: integer
                  format: int64
                  description: Timestamp from which the car is active
                activeTillDate:
                  type: integer
                  format: int64
                  description: Timestamp until which the car is active
                tuev:
                  type: integer
                  format: int64
                  description: Date of the next mandatory technical inspection
                fuel:
                  type: string
                  description: Fuel type used by the car
                  enum:
                    - DIESEL
                    - BENZINE
                    - SUPER_PLUS
                    - GAS
                insuranceId:
                  type: integer
                  description: Identifier of the insurance provider for the car
                note:
                  type: string
                  description: Free-text note about the car
            example:
              id: 0
              numberPlate: HH-AB 1234
              manufacturer: Volkswagen
              type: Passat
              initialRegistrationYear: 2022
              active: true
              fuel: DIESEL
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      numberPlate:
                        type: string
                        example: HH-AB 1234
                      manufacturer:
                        type: string
                        example: Volkswagen
                      type:
                        type: string
                        example: Passat
                      active:
                        type: boolean
                        example: true
              example:
                meta: {}
                content:
                  id: 1
                  numberPlate: HH-AB 1234
                  manufacturer: Volkswagen
                  type: Passat
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/cars/{id}:
    delete:
      operationId: delete_api_v1_cars_id
      tags:
        - cars
      summary: Delete car by id
      description: |
        Generic admin delete endpoint. Used by accounting types, currencies, payment methods, etc.; Requires the corresponding admin permission (e.g. `MANAGE_ACCOUNTING_TYPES` or `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`) and checks for blocking references before the row is removed.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the car.
          schema:
            type: string
          example: '42'
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_cars_id
      tags:
        - cars
      summary: Get car by id
      description: |
        Generic admin read endpoint. Returns the single configured entity (accounting type, currency, payment method, etc.) addressed by `id`. Standard admin access checks apply.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the car.
          schema:
            type: string
          example: '42'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    example:
                      id: 1
                      name: Standard
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_cars_id
      tags:
        - cars
      summary: Edit car by id
      description: |
        Generic admin update endpoint. Applies the JSON patch to the entity addressed by `id` and persists it. Requires the corresponding admin permission (e.g. `MANAGE_ACCOUNTING_TYPES`, `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`).
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the car.
          schema:
            type: string
          example: '42'
      requestBody:
        description: JSON body with the updated entity fields.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              id: 1
              name: Standard
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    example:
                      id: 1
                      name: Standard
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklistEvents:
    post:
      operationId: post_api_v1_checklistEvents
      tags:
        - checklists - events
      summary: Create event
      description: |
        Creates a new checklist event — a trigger that fires when a particular item is checked, a multi-select option is picked, or some other condition is met during checklist processing. Standard CRUD permission check applies.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Unique identifier of the checklist event
                checklistItemId:
                  type: integer
                  description: Identifier of the checklist item this event belongs to
                multiSelectOptionId:
                  type: integer
                  description: Identifier of the multi-select option this event is attached to, if any
                type:
                  type: string
                  description: The kind of automated action this event performs
                  enum:
                    - JUMP_TO_FIELD
                    - SEND_EMAIL
                    - CHANGE_TICKET_EMPLOYEE_DEPARTMENT
                    - CHANGE_TICKET_DUE
                    - ADD_TICKET_COMMENT
                    - ADD_CHECKLIST
                    - CREATE_TICKET
                    - CHANGE_TICKET_STATUS
                    - END_PROCESS
                    - APPROVAL_PROCESS
                    - CHANGE_TICKET_PRICE
                    - LOCK_OR_UNLOCK_TICKET
                    - ADD_ROLE
                    - CHANGE_RESUBMISSION
                    - SET_SEPARATE_BILLING
                    - SET_UPPER_LIMIT
                    - SET_INSTALLATION_FEE
                    - CHANGE_TICKET_TYPE
                    - CREATE_PASSWORD
                    - CHANGE_VISIBILITY
                    - CHANGE_ASSIGNMENT
                    - CHANGE_TICKET_DEADLINE
                    - ADD_TAG
                    - CHANGE_ESTIMATED_TIME
                    - SET_TICKET_TEXTS
                    - ESCALATION_CAN_BE_TRIGGERED_AGAIN
                    - CHANGE_PRIORITY
                    - RESET_RULE
                    - LOCAL_TICKET_ADMIN_FLAG
                    - REMOVE_CHECKLIST
                    - SET_COMPANY_TYPES
                    - SUGGEST_TICKET_FOR_FEEDBACK
                    - REMOVE_ROLE
                    - CONTRACT_WORKFLOW
                    - CHANGE_REPAIR_TICKET
                    - CHANGE_EXT_TICKET_NR
                    - CHANGE_TICKET_ORDER_NR
                    - CHANGE_COST_CENTER
                    - CHANGE_CLEARANCE_MODE
                    - SEND_SERVICE_REPORT
                    - APPOINTMENT_WIZARD
                    - ASSIGN_TO_PROJECT
                    - WEBHOOK
                    - SET_REMITTER
                    - SET_NOTIFICATION
                    - CLEAR_SUPPORTS
                    - SET_TICKET_TEXTS_BY_AI
                    - CREATE_TICKET_SUMMARY
                    - CREATE_SUPPORT
                    - START_TICKET_TIMER
                value:
                  type: string
                  description: Configuration value or payload for the event action
                pos:
                  type: integer
                  description: Ordering position of the event within its item
            example:
              id: 42
              checklistItemId: 1
              multiSelectOptionId: 1
              type:
                value: 1
              value: string
              pos: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created checklist event.
              example:
                meta: {}
                content:
                  id: 17
                  checklistItemId: 12
                  multiSelectOptionId: 0
                  type:
                    value: 1
                  value: Auto-Mail an Manager
                  pos: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklistEvents/frontend/events/{eventType}:
    get:
      operationId: get_api_v1_checklistEvents_frontend_events_eventType
      tags:
        - checklists - events
      summary: Get events frontend values
      description: |
        Returns the configurable fields (dropdown options, default values, validation hints) that the frontend needs in order to render the configuration form for a checklist event of the given type. Optionally scoped to a specific checklist via the query parameter so that the strategy can pre-fill checklist-specific choices.
      parameters:
        - in: path
          name: eventType
          description: Type of checklist event to load the configuration form for.
          required: true
          example: TICKET_CREATED
          schema:
            type: string
        - in: query
          name: checklistId
          description: (optional) checklist id to scope event configuration to a specific checklist.
          required: false
          example: 1
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Configurable fields for the requested event type.
              example:
                meta: {}
                content:
                  type: MAIL
                  fields:
                    - key: recipient
                      label: Empfänger
                      inputType: EMAIL
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklistEvents/{id}:
    delete:
      operationId: delete_api_v1_checklistEvents_id
      tags:
        - checklists - events
      summary: Delete checklist event
      description: Deletes the checklist event with the given id.
      parameters:
        - in: path
          name: id
          description: Id of the checklist event.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_checklistEvents_id
      tags:
        - checklists - events
      summary: Get checklist event
      description: Returns the checklist event with the given id.
      parameters:
        - in: path
          name: id
          description: Id of the checklist event.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The requested checklist event.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_checklistEvents_id
      tags:
        - checklists - events
      summary: Update checklist event
      description: Updates the checklist event with the given id.
      parameters:
        - in: path
          name: id
          description: Id of the checklist event.
          required: true
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Unique identifier of the checklist event
                checklistItemId:
                  type: integer
                  description: Identifier of the checklist item this event belongs to
                multiSelectOptionId:
                  type: integer
                  description: Identifier of the multi-select option this event is attached to, if any
                type:
                  type: string
                  description: The kind of automated action this event performs
                  enum:
                    - JUMP_TO_FIELD
                    - SEND_EMAIL
                    - CHANGE_TICKET_EMPLOYEE_DEPARTMENT
                    - CHANGE_TICKET_DUE
                    - ADD_TICKET_COMMENT
                    - ADD_CHECKLIST
                    - CREATE_TICKET
                    - CHANGE_TICKET_STATUS
                    - END_PROCESS
                    - APPROVAL_PROCESS
                    - CHANGE_TICKET_PRICE
                    - LOCK_OR_UNLOCK_TICKET
                    - ADD_ROLE
                    - CHANGE_RESUBMISSION
                    - SET_SEPARATE_BILLING
                    - SET_UPPER_LIMIT
                    - SET_INSTALLATION_FEE
                    - CHANGE_TICKET_TYPE
                    - CREATE_PASSWORD
                    - CHANGE_VISIBILITY
                    - CHANGE_ASSIGNMENT
                    - CHANGE_TICKET_DEADLINE
                    - ADD_TAG
                    - CHANGE_ESTIMATED_TIME
                    - SET_TICKET_TEXTS
                    - ESCALATION_CAN_BE_TRIGGERED_AGAIN
                    - CHANGE_PRIORITY
                    - RESET_RULE
                    - LOCAL_TICKET_ADMIN_FLAG
                    - REMOVE_CHECKLIST
                    - SET_COMPANY_TYPES
                    - SUGGEST_TICKET_FOR_FEEDBACK
                    - REMOVE_ROLE
                    - CONTRACT_WORKFLOW
                    - CHANGE_REPAIR_TICKET
                    - CHANGE_EXT_TICKET_NR
                    - CHANGE_TICKET_ORDER_NR
                    - CHANGE_COST_CENTER
                    - CHANGE_CLEARANCE_MODE
                    - SEND_SERVICE_REPORT
                    - APPOINTMENT_WIZARD
                    - ASSIGN_TO_PROJECT
                    - WEBHOOK
                    - SET_REMITTER
                    - SET_NOTIFICATION
                    - CLEAR_SUPPORTS
                    - SET_TICKET_TEXTS_BY_AI
                    - CREATE_TICKET_SUMMARY
                    - CREATE_SUPPORT
                    - START_TICKET_TIMER
                value:
                  type: string
                  description: Configuration value or payload for the event action
                pos:
                  type: integer
                  description: Ordering position of the event within its item
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated checklist event.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklistItems:
    post:
      operationId: post_api_v1_checklistItems
      tags:
        - checklists - items
      summary: Create item
      description: |
        Creates a new checklist item (single row inside a checklist — checkbox, text input, multi-select, etc.). The caller's access to and permission to modify the parent checklist are verified before the item is persisted.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Unique identifier of the checklist item
                checklistId:
                  type: integer
                  description: Identifier of the checklist this item belongs to
                type:
                  type: string
                  description: The kind of checklist item (field, multi-select, included checklist, etc.)
                  enum:
                    - TEXT_FIELD
                    - REQUIRED_FIELD
                    - OPTIONAL_FIELD
                    - INCLUDED_CHECKLIST
                    - REQUIRED_TEXT_FIELD
                    - OPTIONAL_TEXT_FIELD
                    - REQUIRED_MULTISELECT
                    - OPTIONAL_MULTISELECT
                    - EVENT_CONTAINER
                    - APPROVAL_PROCESS
                    - SERVICE_CATALOG_SELECTION
                    - CREATE_SUPPORT_FIELD
                    - INCLUDED_CONTAINER
                heading:
                  type: string
                  description: Title or heading shown for the item
                description:
                  type: string
                  description: Descriptive text for the item
                entryPoint:
                  type: boolean
                  description: Whether this item is the starting point of the checklist
                nextItemId:
                  type: integer
                  description: Identifier of the item that follows this one in the sequence
                serviceText:
                  type: string
                  description: Service text associated with the item for billing purposes
                hidden:
                  type: boolean
                  description: Whether the item is currently hidden
            example:
              checklistId: 1
              description: Vollbackup vor Migration durchführen
              type:
                value: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created checklist item.
              example:
                meta: {}
                content:
                  id: 12
                  checklistId: 1
                  title: Backup erstellen
                  type:
                    value: 1
                  rank: 1
                  mandatory: true
                  checked: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklistItems/multiSelectOptions:
    post:
      operationId: post_api_v1_checklistItems_multiSelectOptions
      tags:
        - checklists - items
      summary: Create multi select option
      description: |
        Adds a new choice (label) to an existing multi-select checklist item. The caller must have access to the parent item and update permissions on it before the option is persisted.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - multiSelectId
              properties:
                multiSelectId:
                  type: integer
                  description: Unique identifier of the multi-select option
                checklistItemId:
                  type: integer
                  description: Identifier of the checklist item this option belongs to
                rank:
                  type: integer
                  description: Ordering rank of the option within its item
                name:
                  type: string
                  description: Display name of the option
                description:
                  type: string
                  description: Descriptive text for the option
            example:
              multiSelectId: 1
              checklistItemId: 12
              rank: 1
              name: Erfolgreich
              description: Backup ohne Fehler abgeschlossen
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created multi-select option.
              example:
                meta: {}
                content:
                  id: 5
                  multiSelectId: 1
                  checklistItemId: 12
                  rank: 1
                  name: Erfolgreich
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklistItems/multiSelectOptions/{id}:
    delete:
      operationId: delete_api_v1_checklistItems_multiSelectOptions_id
      tags:
        - checklists - items
      summary: Delete multi select option
      description: |
        Removes a single choice from a multi-select checklist item. Standard admin permission check applies.
      parameters:
        - in: path
          name: id
          description: ID of the multi-select option.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_checklistItems_multiSelectOptions_id
      tags:
        - checklists - items
      summary: Update multi select option
      description: |
        Updates the label, rank or description of an existing multi-select option attached to a checklist item.
      parameters:
        - in: path
          name: id
          description: ID of the multi-select option.
          required: true
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - multiSelectId
              properties:
                multiSelectId:
                  type: integer
                  description: Unique identifier of the multi-select option
                checklistItemId:
                  type: integer
                  description: Identifier of the checklist item this option belongs to
                rank:
                  type: integer
                  description: Ordering rank of the option within its item
                name:
                  type: string
                  description: Display name of the option
                description:
                  type: string
                  description: Descriptive text for the option
            example:
              multiSelectId: 1
              checklistItemId: 12
              rank: 1
              name: Erfolgreich
              description: Backup ohne Fehler abgeschlossen
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated multi-select option.
              example:
                meta: {}
                content:
                  id: 5
                  multiSelectId: 1
                  checklistItemId: 12
                  rank: 1
                  name: Erfolgreich
                  description: Backup ohne Fehler abgeschlossen
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklistItems/{id}:
    delete:
      operationId: delete_api_v1_checklistItems_id
      tags:
        - checklists - items
      summary: Delete checklist item
      description: Deletes the checklist item with the given id.
      parameters:
        - in: path
          name: id
          description: Id of the checklist item.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_checklistItems_id
      tags:
        - checklists - items
      summary: Get checklist item
      description: Returns the checklist item with the given id.
      parameters:
        - in: path
          name: id
          description: Id of the checklist item.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The requested checklist item.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_checklistItems_id
      tags:
        - checklists - items
      summary: Update checklist item
      description: Updates the checklist item with the given id.
      parameters:
        - in: path
          name: id
          description: Id of the checklist item.
          required: true
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Unique identifier of the checklist item
                checklistId:
                  type: integer
                  description: Identifier of the checklist this item belongs to
                type:
                  type: string
                  description: The kind of checklist item (field, multi-select, included checklist, etc.)
                  enum:
                    - TEXT_FIELD
                    - REQUIRED_FIELD
                    - OPTIONAL_FIELD
                    - INCLUDED_CHECKLIST
                    - REQUIRED_TEXT_FIELD
                    - OPTIONAL_TEXT_FIELD
                    - REQUIRED_MULTISELECT
                    - OPTIONAL_MULTISELECT
                    - EVENT_CONTAINER
                    - APPROVAL_PROCESS
                    - SERVICE_CATALOG_SELECTION
                    - CREATE_SUPPORT_FIELD
                    - INCLUDED_CONTAINER
                heading:
                  type: string
                  description: Title or heading shown for the item
                description:
                  type: string
                  description: Descriptive text for the item
                entryPoint:
                  type: boolean
                  description: Whether this item is the starting point of the checklist
                nextItemId:
                  type: integer
                  description: Identifier of the item that follows this one in the sequence
                serviceText:
                  type: string
                  description: Service text associated with the item for billing purposes
                hidden:
                  type: boolean
                  description: Whether the item is currently hidden
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated checklist item.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklistItems/{id}/multiSelectOptions:
    get:
      operationId: get_api_v1_checklistItems_id_multiSelectOptions
      tags:
        - checklists - items
      summary: Get multi select options by item id
      description: |
        Returns all selectable options configured for a multi-select checklist item (radio-button / dropdown choices). Access to the parent checklist item is verified first.
      parameters:
        - in: path
          name: id
          description: ID of the checklist item.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of multi-select options for the item.
              example:
                meta: {}
                content:
                  - id: 5
                    multiSelectId: 1
                    checklistItemId: 12
                    rank: 1
                    name: Erfolgreich
                  - id: 6
                    multiSelectId: 1
                    checklistItemId: 12
                    rank: 2
                    name: Fehlgeschlagen
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists/action:
    put:
      operationId: put_api_v1_checklists_action
      tags:
        - checklists
      summary: Update checklist action
      description: |
        Updates the persisted state of a single checklist action (e.g. a button/event hook attached to a checklist item) for the given assignment. Restricted to technicians and freelancers, who must additionally have access both to the checklist assignment and to the action itself.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                checklistId:
                  type: integer
                  description: Identifier of the checklist the action belongs to
                checklistMainId:
                  type: integer
                  description: Identifier of the top-level checklist
                linkTypeId:
                  type: integer
                  description: Type of the linked entity the checklist is attached to
                linkId:
                  type: integer
                  description: Identifier of the linked entity the checklist is attached to
                checklistItemId:
                  type: integer
                  description: Identifier of the checklist item the action refers to
                value:
                  type: integer
                  description: Recorded value for the action; a positive value marks the item as checked
                date:
                  type: integer
                  description: Timestamp when the action was performed
                userId:
                  type: integer
                  description: Identifier of the employee who performed the action
                supportId:
                  type: integer
                  description: Identifier of the related support ticket
                hidden:
                  type: boolean
                  description: Whether the action is hidden
            example:
              checklistId: 1
              linkTypeId: 11
              linkId: 4711
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Updated checklist action.
              example:
                meta: {}
                content:
                  id: 5
                  checklistId: 1
                  linkTypeId: 11
                  linkId: 4711
                  itemId: 12
                  actionType: MAIL
                  executed: true
                  executedAt: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists/copy/{checklistId}:
    post:
      operationId: post_api_v1_checklists_copy_checklistId
      tags:
        - checklists
      summary: Copy checklist
      description: |
        Duplicates an existing checklist (template) — items, multi-select options, events and actions are all cloned into a brand-new checklist independent of the source. Predecessor/successor (versioning) chain is NOT continued; use the createNewVersion route for that. Permission to copy is checked against the source checklist.
      parameters:
        - in: path
          name: checklistId
          description: ID of the checklist to copy.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The newly created copy of the checklist.
              example:
                meta: {}
                content:
                  id: 42
                  name: Server-Migration (Kopie)
                  categoryId: 1
                  predecessorId: 0
                  successorId: 0
                  active: true
                  items:
                    - id: 101
                      title: Backup erstellen
                      checked: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists/createNewVersion/{checklistId}:
    post:
      operationId: post_api_v1_checklists_createNewVersion_checklistId
      tags:
        - checklists
      summary: Create new version of checklist
      description: |
        Creates a successor version of an existing checklist. The new checklist is linked to the source via predecessor/successor ids; the source is deactivated so that future ticket assignments pick up the latest version while in-flight processed instances keep referring to the old version. If `updateIncludedInChecklists` is true, parent checklists that embed the source as a sub-checklist are automatically rewired to the new version.
      parameters:
        - in: path
          name: checklistId
          description: ID of the source checklist to create a new version of.
          required: true
          example: 1
          schema:
            type: integer
        - in: query
          name: updateIncludedInChecklists
          description: If true, rewire parent checklists embedding the source to the new version.
          required: false
          example: true
          schema:
            type: boolean
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Result holding ids of the source and the newly created successor checklist.
              example:
                meta: {}
                content:
                  sourceChecklistId: 1
                  newChecklistId: 42
                  updatedParentChecklistIds:
                    - 7
                    - 9
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists/{id}:
    delete:
      operationId: delete_api_v1_checklists_id
      tags:
        - checklists
      summary: Delete checklist
      description: |
        Deletes a checklist template along with its items, multi-select options, events and actions. Requires the DELETE_PROCESSES permission; a checklist that has a successor (i.e. a newer version) cannot be deleted.
      parameters:
        - in: path
          name: id
          description: ID of the checklist.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_checklists_id
      tags:
        - checklists
      summary: Get checklist
      description: |
        Loads a checklist in edit-mode — all fields (including hidden/disabled ones) are returned so that an administrator can modify the template. For the read-only processing view used inside a ticket, use the `/process` endpoint instead.
      parameters:
        - in: path
          name: id
          description: ID of the checklist.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Checklist template in edit-mode.
              example:
                meta: {}
                content:
                  id: 1
                  name: Server-Migration
                  categoryId: 1
                  active: true
                  items:
                    - id: 12
                      title: Backup erstellen
                      checked: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_checklists_id
      tags:
        - checklists
      summary: Update checklist
      description: |
        Updates an existing checklist template. The JSON body is merged using the "checked rights" mechanism — only fields the caller is allowed to change will be applied, anything else is silently ignored.
      parameters:
        - in: path
          name: id
          description: ID of the checklist.
          required: true
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the checklist
                name:
                  type: string
                  description: Name of the checklist
                description:
                  type: string
                  description: Description of the checklist
                type:
                  type: string
                  description: Kind of checklist
                  enum:
                    - CHECKLIST
                    - TEMPLATE
                    - ADHOC
                creatorId:
                  type: integer
                  description: Identifier of the employee who created the checklist
                active:
                  type: boolean
                  description: Whether the checklist is currently active
                position:
                  type: string
                  description: Display position of the checklist
                  enum:
                    - DEFAULT
                    - TOP
                completed:
                  type: boolean
                  description: Whether the checklist has been completed
            example:
              id: 1
              name: Server-Migration
              description: Standard-Ablauf für Migrationen
              type:
                value: 1
              active: true
              position:
                value: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Updated checklist template.
              example:
                meta: {}
                content:
                  id: 1
                  name: Server-Migration
                  categoryId: 1
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/checklists/{id}/convert/adhoc/{linkTypeId}/{linkId}:
    post:
      operationId: post_api_v1_checklists_id_convert_adhoc_linkTypeId_linkId
      tags:
        - checklists
      summary: Convert to adhoc
      description: |
        Takes a template checklist and turns it into an ad-hoc instance that is bound to one specific link target (typically a ticket). The ad-hoc copy is editable independently of the template — useful when a technician needs to tweak the workflow for a single case. Requires the CONVERT_CHECKLIST_INTO_ADHOC permission and access to the target assignment.
      parameters:
        - in: path
          name: id
          description: ID of the template checklist to convert to an ad-hoc instance.
          required: true
          example: '1'
          schema:
            type: string
        - in: path
          name: linkTypeId
          description: linkTypeId of the target assignment (11 = ticket).
          required: true
          example: 1
          schema:
            type: integer
        - in: path
          name: linkId
          description: id of the link target (e.g. the ticket).
          required: true
          example: 4711
          schema:
            type: integer
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The newly created ad-hoc checklist bound to the assignment.
              example:
                meta: {}
                content:
                  id: 99
                  name: Server-Migration (Adhoc)
                  adhoc: true
                  linkTypeId: 11
                  linkId: 4711
                  items:
                    - id: 12
                      title: Backup erstellen
                      checked: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/costCenter/{id}:
    get:
      operationId: get_api_v1_companies_costCenter_id
      tags:
        - company - relations
      summary: Get company cost center info
      description: |
        Returns the cost-center configuration for a company (whether cost centers are used, the list of defined cost centers, and assignments to PCs / peripherals / employees). The caller must have access to the company. If the company is a branch without its own configuration, the lookup falls back to the headquarter's cost-center setup.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company whose cost-center configuration should be returned.
          example: 100023
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: object with the company's cost-center configuration.
              example:
                meta: {}
                content:
                  companyId: 100023
                  costCenterUsed: true
                  costCenterBranchUsed: false
                  costCenters:
                    - id: 5
                      name: IT Infrastruktur
                    - id: 6
                      name: Vertrieb
                  assignments:
                    - linkTypeId: 12
                      linkId: 901
                      costCenterId: 5
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/departments:
    get:
      operationId: get_api_v1_companies_departments
      tags:
        - company
      summary: Get company departments
      description: |
        Returns the list of employee departments (id + name) defined in the system. When `withEmployees=true` and the caller is a technician or freelancer, each department is enriched with the list of employee IDs assigned to it; customer users never receive the employee IDs even if they request them. Used to populate department selectors in the UI.
      parameters:
        - in: query
          name: withEmployees
          required: false
          description: When true, each department is enriched with the list of assigned employee IDs (technicians/freelancers only).
          example: true
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        employeeIds:
                          type: array
                          items:
                            type: integer
              example:
                meta: {}
                content:
                  - id: 1
                    name: Geschäftsführung
                    employeeIds:
                      - 4711
                      - 4712
                  - id: 2
                    name: IT
                    employeeIds:
                      - 4720
                      - 4721
                      - 4722
                  - id: 3
                    name: Buchhaltung
                    employeeIds:
                      - 4730
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/flags/{id}:
    get:
      operationId: get_api_v1_companies_flags_id
      tags:
        - company
      summary: Get company flag icons
      description: |
        Returns the list of "flag icons" (visual marker icons) currently set on the company — e.g. lockout indicators, VIP markers or other type-driven icons. Requires access to the company; returns 404 if the company does not exist. Used by the company header to render status badges.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company whose flag icons should be returned.
          example: 100023
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: List of object entries currently shown for the company.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        icon:
                          type: string
                        title:
                          type: string
              example:
                meta: {}
                content:
                  - id: 1
                    name: vip
                    icon: vip.png
                    title: VIP-Kunde
                  - id: 2
                    name: lockout
                    icon: lock.png
                    title: Firma gesperrt
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/properties:
    get:
      operationId: get_api_v1_companies_properties
      tags:
        - company
      summary: Get company meta properties
      description: |
        Returns the meta-properties (field permissions, editable fields, available extras) for a "blank" company — used by the frontend to know which fields the current user may see and edit before opening or creating a company. The property set is attached to the response `meta` block; `content` itself is `null`. Visible fields differ between technicians and customer users.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    nullable: true
                    description: Always `null`. The interesting data lives in `meta.properties`.
              example:
                meta:
                  properties:
                    editable: true
                    fields:
                      name:
                        editable: true
                      supportInfo:
                        editable: false
                        visible: false
                      headquarterId:
                        editable: true
                    extras:
                      ownCompanyId:
                        value: 1
                content: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/relations/status:
    get:
      operationId: get_api_v1_companies_relations_status
      tags:
        - company - relations
      summary: List all relationship status definitions
      description: |
        Returns the configured object catalog (id + name). Used by the relationship UI to populate the status dropdown when creating or filtering company relationships.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
              example:
                meta: {}
                content:
                  - id: 1
                    name: aktiv
                  - id: 2
                    name: geplant
                  - id: 3
                    name: beendet
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_companies_relations_status
      tags:
        - company - relations
      summary: Create relationship status
      description: |
        Creates a new object (the label set used when defining company relationships). Requires a technician or freelancer and the `MANAGE_COMPANY_RELATIONS` permission.
      requestBody:
        description: A new object to be persisted.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
            example:
              name: aktiv
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
              example:
                meta: {}
                content:
                  id: 4
                  name: aktiv
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/relations/status/{id}:
    delete:
      operationId: delete_api_v1_companies_relations_status_id
      tags:
        - company - relations
      summary: Delete relationship status
      description: |
        Removes a single object definition (a configurable label like "active", "expired", "planned") that can be attached to company relationships. Requires a technician or freelancer and the `MANAGE_COMPANY_RELATIONS` permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the relationship status.
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_companies_relations_status_id
      tags:
        - company - relations
      summary: Get relationship status
      description: |
        Returns a single object (id + name) by id. Used by the relationship editor to render the status dropdown.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the relationship status.
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
              example:
                meta: {}
                content:
                  id: 1
                  name: aktiv
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_companies_relations_status_id
      tags:
        - company - relations
      summary: Update relationship status
      description: |
        Renames object. Requires a technician or freelancer and the `MANAGE_COMPANY_RELATIONS` permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the relationship status to update.
          example: 1
          schema:
            type: integer
      requestBody:
        description: Updated payload.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string
            example:
              id: 1
              name: aktiv
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
              example:
                meta: {}
                content:
                  id: 1
                  name: aktiv
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/relations/{companyId}:
    delete:
      operationId: delete_api_v1_companies_relations_companyId
      tags:
        - company - relations
      summary: Delete a company relationship
      description: |
        Removes the supplier/customer relationship identified by object in the body. The path `companyId` is validated to exist and to be accessible to the caller before the delete runs. Requires a technician or freelancer and the `MANAGE_COMPANY_RELATIONS` permission.
      parameters:
        - in: path
          name: companyId
          required: true
          description: Id of the company whose relationship is being deleted.
          example: 100023
          schema:
            type: integer
      requestBody:
        description: Composite primary key of the relationship to delete.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customerLinkTypeId:
                  type: integer
                customerLinkId:
                  type: integer
                delivererLinkTypeId:
                  type: integer
                delivererLinkId:
                  type: integer
            example:
              customerLinkTypeId: 2
              customerLinkId: 100023
              delivererLinkTypeId: 2
              delivererLinkId: 100024
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_companies_relations_companyId
      tags:
        - company - relations
      summary: Get company relationships
      description: |
        Returns all relationships in which the company participates (as customer or deliverer) plus, if applicable, the relationships defined on its headquarter — headquarter rows are flagged with `relationFromHq=true`. Linked-entity resolution is filled in for assignments, the relationship status and involved companies. Requires access to the company; the company must exist.
      parameters:
        - in: path
          name: companyId
          required: true
          description: Id of the company whose relationships should be returned.
          example: 100023
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        customerLinkTypeId:
                          type: integer
                        customerLinkId:
                          type: integer
                        delivererLinkTypeId:
                          type: integer
                        delivererLinkId:
                          type: integer
                        statusId:
                          type: integer
                        info:
                          type: string
                        active:
                          type: boolean
                        companyId:
                          type: integer
                        relationFromHq:
                          type: boolean
                        hqId:
                          type: integer
              example:
                meta: {}
                content:
                  - customerLinkTypeId: 2
                    customerLinkId: 100023
                    delivererLinkTypeId: 2
                    delivererLinkId: 100024
                    statusId: 1
                    info: Wartungsvertrag Cloud
                    active: true
                    companyId: 100023
                    relationFromHq: false
                    hqId: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_companies_relations_companyId
      tags:
        - company - relations
      summary: Create a company relationship
      description: |
        Creates object between a customer and a deliverer (each side is identified by a `linkTypeId`/`linkId` pair — typically a company or an employee). One side must reference the path `companyId`. The target side's assignment is verified to exist and to be accessible; the `statusId` (if non-zero) must point to an existing relationship status. Requires a technician or freelancer and the `MANAGE_COMPANY_RELATIONS` permission.
      parameters:
        - in: path
          name: companyId
          required: true
          description: Id of the company one side of the new relationship references.
          example: 100023
          schema:
            type: integer
      requestBody:
        description: An object to create.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customerLinkTypeId:
                  type: integer
                customerLinkId:
                  type: integer
                delivererLinkTypeId:
                  type: integer
                delivererLinkId:
                  type: integer
                statusId:
                  type: integer
                info:
                  type: string
                active:
                  type: boolean
            example:
              customerLinkTypeId: 2
              customerLinkId: 100023
              delivererLinkTypeId: 2
              delivererLinkId: 100024
              statusId: 1
              info: Wartungsvertrag Cloud
              active: true
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: The persisted object.
              example:
                meta: {}
                content:
                  customerLinkTypeId: 2
                  customerLinkId: 100023
                  delivererLinkTypeId: 2
                  delivererLinkId: 100024
                  statusId: 1
                  info: Wartungsvertrag Cloud
                  active: true
                  companyId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/search:
    get:
      operationId: get_api_v1_companies_search
      tags:
        - company - relations
      summary: Search companies by free-text query
      description: |
        Runs a free-text search over the company index and returns a list of records (id, name, address snippet, match info). Standard search permissions and company-access filters apply — customer users only see their own companies, technicians see everything they have access to.
      parameters:
        - in: query
          name: query
          required: true
          example: Beispiel GmbH
          schema:
            type: string
          description: Free-text search string (request parameter named `query`).
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        customerNumber:
                          type: string
                        city:
                          type: string
              example:
                meta: {}
                content:
                  - id: 100023
                    name: Beispiel GmbH
                    customerNumber: K-1023
                    city: Berlin
                  - id: 100045
                    name: Beispiel-Service AG
                    customerNumber: K-1045
                    city: Berlin
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/technicianRecommendation/{companyId}:
    get:
      operationId: get_api_v1_companies_technicianRecommendation_companyId
      tags:
        - company - relations
      summary: Get technician recommendation for a company
      description: |
        Returns object — i.e. the ranked list of technicians most appropriate to handle work for the company (and optionally a specific assignment via `linkTypeId`/`linkId`, e.g. a PC or software license). The recommendation is derived from explicit object assignments, company types and headquarter fallbacks. Requires a technician or freelancer and access to the company — customer users do not get a recommendation.
      parameters:
        - in: path
          name: companyId
          required: true
          description: Id of the company to get a technician recommendation for.
          example: 100023
          schema:
            type: integer
        - in: query
          name: linkTypeId
          required: false
          description: Optional link type of a specific assignment (e.g. PC or software license) to narrow the recommendation.
          example: 1
          schema:
            type: integer
            default: 0
        - in: query
          name: linkId
          required: false
          description: Optional id of the assignment the recommendation should target.
          example: 100023
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: object with recommended/unwanted technician ids and their ranking.
                    properties:
                      recommendedEmployeeIds:
                        type: array
                        items:
                          type: integer
                      unwantedEmployeeIds:
                        type: array
                        items:
                          type: integer
                      companyId:
                        type: integer
              example:
                meta: {}
                content:
                  companyId: 100023
                  recommendedEmployeeIds:
                    - 4720
                    - 4721
                  unwantedEmployeeIds:
                    - 4799
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/{id}:
    get:
      operationId: get_api_v1_companies_id
      tags:
        - company
      summary: Get company
      description: |
        Returns a single company by its id, including its master data and assigned company types. The caller needs access to the company; customer users only ever see their own company.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company.
          example: 100023
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Company-Detail'
              example:
                meta: {}
                content:
                  id: 100023
                  displayId: 100234
                  name: HUCK IT GmbH
                  matchcode: HUCK IT GmbH (Zentrale)
                  street: Am Schatzborn 1
                  postcode: '64380'
                  city: Roßdorf
                  country: Deutschland
                  email: support@tanss.de
                  website: https://www.huckit.de
                  inactive: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_companies_id
      tags:
        - company
      summary: Update company
      description: |
        Updates an existing company with the supplied master data. Only the fields present in the payload are changed. The caller needs edit access to the company.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company to update.
          example: 100023
          schema:
            type: integer
      requestBody:
        description: The company master data to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Company-Post'
            example:
              name: HUCK IT GmbH
              street: Am Schatzborn 1
              postcode: '64380'
              city: Roßdorf
              telephone: 06154/6006-0
      responses:
        '200':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Company-Detail'
              example:
                meta: {}
                content:
                  id: 100023
                  displayId: 100234
                  name: HUCK IT GmbH
                  city: Roßdorf
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/{id}/bookableSupport:
    get:
      operationId: get_api_v1_companies_id_bookableSupport
      tags:
        - company
      summary: Get bookable support overview for company
      description: |
        Returns aggregated "bookable support" totals for a company — i.e. the unbooked/cleared support minutes and amounts not yet invoiced, plus the share that sits inside still-open tickets. Used by the company dashboard's billing summary. Requires access to the company, access to all companies and the `SUPPORT_REPORT_ACCESS` permission, so this is a technician-only view.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company whose bookable-support totals should be returned.
          example: 100023
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      totalMinutes:
                        type: integer
                      totalAmount:
                        type: number
                        format: double
                      inOpenTicketMinutes:
                        type: integer
                      inOpenTicketAmount:
                        type: number
                        format: double
                      showOpenTickets:
                        type: boolean
              example:
                meta: {}
                content:
                  totalMinutes: 480
                  totalAmount: 720
                  inOpenTicketMinutes: 60
                  inOpenTicketAmount: 90
                  showOpenTickets: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/{id}/types:
    get:
      operationId: get_api_v1_companies_id_types
      tags:
        - company - master data
      summary: Get types assigned to a company
      description: |
        Returns the list of records (with their category names resolved) currently assigned to the company — e.g. "Region Süd", "Premium-Kunde", etc. Used to display category badges on the company. The caller must have access to the company; in addition, customer users may only call this if they have access to all companies — otherwise the request is rejected.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company whose assigned types should be returned.
          example: 100023
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsCompanyType'
              example:
                meta: {}
                content:
                  - id: 41
                    name: Region Süd
                    categoryId: 2
                    categoryName: Regionale Gliederung
                    icon: region-sued.jpg
                    hidden: false
                  - id: 12
                    name: Premium-Kunde
                    categoryId: 1
                    categoryName: Kundenklasse
                    hidden: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/{id}/types/show:
    get:
      operationId: get_api_v1_companies_id_types_show
      tags:
        - company - master data
      summary: Get important company info type definitions
      description: |
        Returns the list of records ordered by their `rank` — i.e. the catalog of "important company info" fields an admin has set up (label, type, ordering). This is used by the admin UI to render the configuration of the important-info section. Requires the `EDIT_IMPORTANT_COMPANY_INFO` permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the company whose info type definitions should be returned.
          example: '100023'
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        type:
                          type: string
                        rank:
                          type: integer
              example:
                meta: {}
                content:
                  - id: 1
                    name: Admin-Passwort
                    type: DEFAULT
                    rank: 1
                  - id: 2
                    name: Notfall-Kontakt
                    type: DEFAULT
                    rank: 2
                  - id: 4
                    name: Domain-Server
                    type: ASSIGNMENT
                    rank: 3
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/{id}/{companyId}:
    get:
      operationId: get_api_v1_companies_id_companyId
      tags:
        - company
      summary: Get important company infos
      description: 'Returns all "important company infos" stored for the company: simple value entries (passwords, notes, URLs, knowledge-base references) and assignment-type infos (one entry per linked PC / server / device, grouped by definition rank). Each entry includes its definition id, name, type and resolved linked entity. Requires access to the company and the `VIEW_IMPORTANT_COMPANY_INFO` permission.'
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the important company info entry.
          example: '42'
          schema:
            type: string
        - in: path
          name: companyId
          required: true
          description: Id of the company the info entries belong to.
          example: 100023
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: definition id
                        name:
                          type: string
                        type:
                          type: string
                        rank:
                          type: integer
              example:
                meta: {}
                content:
                  - id: 1
                    name: Admin-Passwort
                    type: DEFAULT
                    rank: 1
                  - id: 4
                    name: Domain-Server
                    type: ASSIGNMENT
                    rank: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_companies_id_companyId
      tags:
        - company
      summary: Update important company infos
      description: Persists a value (or assignment list) for a single "important company info" definition on this company. The payload is bound to a object; how it is stored depends on the definition's type (string value, password, knowledge-base link, PC/server/device assignment, etc.), and a type-specific access check applies. Requires access to the company, the `VIEW_IMPORTANT_COMPANY_INFO` permission (for company access) and `EDIT_IMPORTANT_COMPANY_INFO` (for editing).
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the important company info entry.
          example: '42'
          schema:
            type: string
        - in: path
          name: companyId
          required: true
          description: Id of the company the info entry belongs to.
          example: 100023
          schema:
            type: integer
      requestBody:
        description: A payload. `id` selects the definition; remaining fields depend on the definition's type (`DEFAULT`, `ASSIGNMENT`, knowledge-base, etc.).
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Definition id this entry belongs to.
                name:
                  type: string
                type:
                  type: string
                  description: DEFAULT, ASSIGNMENT, ASSIGNMENT_SERVICE, ASSIGNMENT_SERVICE_PASSWORD, ...
                value:
                  type: string
                  description: For value-type entries.
                assignments:
                  type: array
                  description: For ASSIGNMENT-type entries.
                  items:
                    type: object
                    properties:
                      linkTypeId:
                        type: integer
                      linkId:
                        type: integer
            example:
              id: 1
              name: Admin-Passwort
              type: DEFAULT
              value: Sup3rS3cret!
      responses:
        '201':
          description: Resource created / updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: The stored object entry.
              example:
                meta: {}
                content:
                  id: 1
                  name: Admin-Passwort
                  type: DEFAULT
                  rank: 1
                  value: Sup3rS3cret!
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/companies/{id}/{companyId}/{definitionId}:
    delete:
      operationId: delete_api_v1_companies_id_companyId_definitionId
      tags:
        - company
      summary: Delete important company info
      description: |
        Removes the stored value and any assignment rows for a single "important company info" (defined by `definitionId`) on the given company. The caller must have access to the company, the `VIEW_IMPORTANT_COMPANY_INFO` permission for the access check and `EDIT_IMPORTANT_COMPANY_INFO` for the deletion itself — so customer users cannot reach this route.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the important company info entry.
          example: '42'
          schema:
            type: string
        - in: path
          name: companyId
          required: true
          description: Id of the company the info entry belongs to.
          example: 100023
          schema:
            type: integer
        - in: path
          name: definitionId
          required: true
          description: Id of the company info definition to delete.
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/components/pdf:
    put:
      operationId: put_api_v1_components_pdf
      tags:
        - device management
      summary: Get component list PDF
      description: |
        Generates a PDF rendering of the component list matching the supplied configuration filter. Same filter semantics as the regular list endpoint, but the result is a PDF (or file-pass key depending on the Accept header).
      requestBody:
        description: A configuration filter object describing which components to include; same filter semantics as the component list endpoint.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Configuration filter for the component list.
            example:
              text: Example content
              extras: {}
              linkedEntities: {}
              assignments:
                infos: {}
              properties:
                fields: {}
                extras: {}
                permissions: {}
                editable: false
                message: Example content
              pagination:
                itemsPerPage: 1
                totalItems: 1
                page: 1
              listProperties: {}
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: File-pass response pointing to the generated component-list PDF.
              example:
                meta: {}
                content:
                  fileKey: c92a0d11-3e4b-4f6c-9b21-58a3c1d20a7e
                  filename: component-list.pdf
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/configValues:
    get:
      operationId: get_api_v1_configValues
      tags:
        - preferences
      summary: Get config values
      description: |
        Returns every entry from the global configuration table ("OSK" values) used to tune system behaviour at runtime. The endpoint is open to authenticated users; the response is read-only.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        configName:
                          type: string
                          example: support.anfahrt.abrechnungstyp
                        configValue:
                          type: string
                          example: '2'
                        companyId:
                          type: integer
                          example: 0
              example:
                meta: {}
                content:
                  - configName: support.anfahrt.abrechnungstyp
                    configValue: '2'
                    companyId: 0
                  - configName: abrechnungstypen.vererbung.an.filialen
                    configValue: '1'
                    companyId: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/configValues/{cfgName}:
    get:
      operationId: get_api_v1_configValues_cfgName
      tags:
        - preferences
      summary: Get config value
      description: |
        Returns the single global configuration entry ("OSK" value) identified by `cfgName`. The lookup is scoped to `companyId = 0`; a missing key results in a 404 response.
      parameters:
        - in: path
          name: cfgName
          required: true
          description: Name of the global configuration entry ("OSK" value) to address.
          schema:
            type: string
          example: support.anfahrt.abrechnungstyp
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      configName:
                        type: string
                        example: support.anfahrt.abrechnungstyp
                      configValue:
                        type: string
                        example: '2'
                      companyId:
                        type: integer
                        example: 0
              example:
                meta: {}
                content:
                  configName: support.anfahrt.abrechnungstyp
                  configValue: '2'
                  companyId: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_configValues_cfgName
      tags:
        - preferences
      summary: Update config value
      description: |
        Updates the global configuration entry identified by `configName` inside the body (the path variable mirrors it). An admin-permission check is performed; non-existing keys are rejected.
      parameters:
        - in: path
          name: cfgName
          required: true
          description: Name of the global configuration entry ("OSK" value) to address.
          schema:
            type: string
          example: support.anfahrt.abrechnungstyp
      requestBody:
        description: JSON body with the updated config entry.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              configName: support.anfahrt.abrechnungstyp
              configValue: '3'
              companyId: 0
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      configName:
                        type: string
                        example: support.anfahrt.abrechnungstyp
                      configValue:
                        type: string
                        example: '3'
                      companyId:
                        type: integer
                        example: 0
              example:
                meta: {}
                content:
                  configName: support.anfahrt.abrechnungstyp
                  configValue: '3'
                  companyId: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/contracts/from/parameters:
    put:
      operationId: put_api_v1_contracts_from_parameters
      tags:
        - contracts
      summary: Find contracts by parameters
      description: |
        Returns all contracts matching the lookup criteria in the request body (typically company/department/ticket-type tuples or a contract type filter). Used by the frontend to find applicable maintenance contracts for a given context. Requires VIEW_MAINTENANCE_CONTRACTS plus contract-specific access checks on the requested parameters.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                date:
                  type: integer
                  format: int64
                  description: Reference timestamp for which the applicable contract is queried.
                companyId:
                  type: integer
                  description: Identifier of the company the contract lookup applies to.
                employeeId:
                  type: integer
                  description: Identifier of the employee associated with the query.
                linkTypeId:
                  type: integer
                  description: Type identifier of the linked entity.
                linkId:
                  type: integer
                  description: Identifier of the linked entity.
                ticketTypeId:
                  type: integer
                  description: Identifier of the ticket type.
                supportLocationId:
                  type: integer
                  description: Identifier of the support location (e.g. on-site or remote).
                supportTypeId:
                  type: integer
                  description: Identifier of the support type.
                installationFee:
                  type: boolean
                  description: Whether an installation fee applies.
                priorityId:
                  type: integer
                  description: Identifier of the priority.
                strategy:
                  type: string
                  description: Query strategy determining how matching contracts are resolved.
                  enum:
                    - DEFAULT
                    - SUPPORT
                    - TICKET
            example:
              companyId: 100023
              ticketTypeId: 4
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of contract-found results.
              example:
                meta: {}
                content:
                  - id: 1
                    companyId: 100023
                    name: Wartungsvertrag
                    validFrom: 1748256000
                    validTo: 1779792000
                    monthlyFee: 250
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/contracts/prepaid/{contractId}/calculate:
    put:
      operationId: put_api_v1_contracts_prepaid_contractId_calculate
      tags:
        - contracts
      summary: Calculate prepaid balance
      description: |
        Calculates the prepaid balance/forecast for the given contract using the options in the body (which months to include, whether to roll over unused time, etc.). The contract is *not* mutated by this call — the name "updateContract" is a controller-method artefact. Requires access to the contract and the prepaid-calculation permission.
      parameters:
        - in: path
          name: contractId
          description: ID of the contract to calculate the prepaid balance for.
          required: true
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                showCompleteHistory:
                  type: boolean
                  description: If true, already booked support entries are included; otherwise only unbooked ones are considered.
                calculateAllOverAgain:
                  type: boolean
                  description: Requires showCompleteHistory; if true, recalculates all booked entries from the beginning instead of using stored values.
                allowNegative:
                  type: boolean
                  description: Whether the calculated quota may go negative.
                excludeSupportId:
                  type: integer
                  description: Support entry id to exclude from the calculation.
                additionalSupportForCalculation:
                  type: array
                  description: Additional support entries to include in the calculation, e.g. to test whether they fit into the remaining quota.
                  items:
                    type: object
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Prepaid calculation result for the contract.
              example:
                meta: {}
                content:
                  contractId: 100
                  fromTimestamp: 1748256000
                  toTimestamp: 1779792000
                  budgetMinutes: 6000
                  consumedMinutes: 1820
                  remainingMinutes: 4180
                  rolloverMinutes: 240
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/currencies:
    get:
      operationId: get_api_v1_currencies
      tags:
        - currencies
      summary: Get all currencies
      description: |
        Returns every currency configured in the system together with its conversion factor. Read access uses the default CRUD basic permission check; mutations require a user from the own company with `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Euro
                        symbol:
                          type: string
                          example: EUR
                        factor:
                          type: number
                          example: 1
              example:
                meta: {}
                content:
                  - id: 1
                    name: Euro
                    symbol: EUR
                    factor: 1
                  - id: 2
                    name: US Dollar
                    symbol: USD
                    factor: 1.08
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_currencies
      tags:
        - currencies
      summary: Create currency
      description: |
        Creates a new currency entry that can be assigned to companies, offers, and invoices. Requires a user from the own company with `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`; the factor is stored as a multiplier relative to the system's leading currency.
      requestBody:
        description: JSON body. An object.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the currency.
                name:
                  type: string
                  description: Name of the currency.
                symbol:
                  type: string
                  description: Display symbol of the currency.
                factor:
                  type: number
                  description: Conversion factor relative to the base currency.
            example:
              id: 0
              name: US Dollar
              symbol: USD
              factor: 1.08
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 2
                      name:
                        type: string
                        example: US Dollar
                      symbol:
                        type: string
                        example: USD
                      factor:
                        type: number
                        example: 1.08
              example:
                meta: {}
                content:
                  id: 2
                  name: US Dollar
                  symbol: USD
                  factor: 1.08
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/currencies/{id}:
    delete:
      operationId: delete_api_v1_currencies_id
      tags:
        - currencies
      summary: Delete currency by id
      description: |
        Generic admin delete endpoint. Used by accounting types, currencies, payment methods, etc.; Requires the corresponding admin permission (e.g. `MANAGE_ACCOUNTING_TYPES` or `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`) and checks for blocking references before the row is removed.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the currency.
          schema:
            type: string
          example: '42'
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_currencies_id
      tags:
        - currencies
      summary: Get currency by id
      description: |
        Generic admin read endpoint. Returns the single configured entity (accounting type, currency, payment method, etc.) addressed by `id`. Standard admin access checks apply.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the currency.
          schema:
            type: string
          example: '42'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    example:
                      id: 1
                      name: Standard
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_currencies_id
      tags:
        - currencies
      summary: Edit currency by id
      description: |
        Generic admin update endpoint. Applies the JSON patch to the entity addressed by `id` and persists it. Requires the corresponding admin permission (e.g. `MANAGE_ACCOUNTING_TYPES`, `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`).
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the currency.
          schema:
            type: string
          example: '42'
      requestBody:
        description: JSON body with the updated entity fields.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              id: 1
              name: Standard
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    example:
                      id: 1
                      name: Standard
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/documents/file/{fileId}:
    delete:
      operationId: delete_api_v1_documents_file_fileId
      tags:
        - documents
      summary: Delete attached file from document
      description: |
        Removes a object attachment from its parent object and deletes the underlying file from disk. Access is checked against the parent document (company access plus internal/non-internal visibility), and deletion requires either ownership of the document combined with `DELETE_DOCUMENTS`, or the global `DELETE_ALL_DOCUMENTS` permission.
      parameters:
        - in: path
          name: fileId
          required: true
          description: Id of the document file attachment to delete.
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/documents/{id}/file/{fileId}:
    get:
      operationId: get_api_v1_documents_id_file_fileId
      tags:
        - documents
      summary: Get document file (file pass for download)
      description: |
        Returns a one-time "file pass" URL for downloading a specific file attached to a document. The pass is then resolved by a separate file-serving endpoint. The caller must have the `COMPANY_DOCUMENT_ACCESS` permission, access to the document's company, and must be allowed to see internal documents if the document is flagged internal. The `fileId` is verified against the requested `documentId` (mismatched IDs return 403).
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the document the file is attached to.
          example: 42
          schema:
            type: integer
        - in: path
          name: fileId
          required: true
          description: Id of the file attachment to download.
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: object carrying the temporary download URL/token.
                    properties:
                      url:
                        type: string
                      token:
                        type: string
                      expires:
                        type: integer
              example:
                meta: {}
                content:
                  url: https://tanss.example.de/files/by-pass/8f3c2a1b
                  token: 8f3c2a1b6e4d4b3aa1c1e9d2
                  expires: 1748259600
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/domains/nslookup:
    put:
      operationId: put_api_v1_domains_nslookup
      tags:
        - domains
      summary: DNS lookup for a hostname or IP
      description: 'Performs a DNS lookup for the supplied `host` (a hostname or IP address) and returns the resource records (A, AAAA, MX, NS, TXT) as a formatted text block. If an IP is given, it is first reverse-resolved to a hostname before querying. Used by the domain-management UI to inspect a domain. Standard permission checks apply: requires a technician or freelancer with domain-management rights.'
      requestBody:
        description: JSON body with the `host` to look up.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - host
              properties:
                host:
                  type: string
                  description: Hostname or IP address to resolve.
            example:
              host: beispiel.de
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: string
                    description: Pre-formatted text block listing the DNS records for the host.
              example:
                meta: {}
                content: |-
                  DNS Resource Records:

                  host: beispiel.de
                  class: IN
                  ttl: 60
                  type: A
                  ip: 93.184.216.34

                  host: beispiel.de
                  class: IN
                  ttl: 60
                  type: MX
                  pri: 10
                  target: mail.beispiel.de
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/domains/pdf:
    put:
      operationId: put_api_v1_domains_pdf
      tags:
        - emailAccounts
      summary: Get email account list as PDF
      description: |
        Builds and returns a PDF of the email-account list for the configuration in the request body (same filter object used by the list endpoint). Depending on the `Accept` header, the controller either streams the PDF directly, emails it, or returns a one-time file-pass URL. Requires the `VIEW_EMAIL_ACCOUNTS_OF_CUSTOMER` permission; the configuration is forced to run permission checks server-side, so only email accounts the caller may see end up in the PDF.
      requestBody:
        description: An object describing which email accounts to include (company filter, text filter, pagination, etc.).
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: integer
                branchFilter:
                  type: string
                textFilter:
                  type: string
                types:
                  type: array
                  items:
                    type: integer
            example:
              companyId: 100023
              branchFilter: COMPANY_AND_BRANCHES
              textFilter: ''
              types: []
      responses:
        '200':
          description: Successful response (PDF, file-pass JSON, or email confirmation depending on `Accept`).
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              example: JVBERi0xLjQKJeLjz9MK
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      url:
                        type: string
                      token:
                        type: string
              example:
                meta: {}
                content:
                  url: https://tanss.example.de/files/by-pass/email-account-list.pdf
                  token: 5e2b9a
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailAccounts/company/{companyId}:
    get:
      operationId: get_api_v1_emailAccounts_company_companyId
      tags:
        - emailAccounts
      summary: Get email accounts of company
      description: |
        Returns all records assigned to the given company, with linked entities (domain, contact employee, etc.) prefilled. Requires the `VIEW_EMAIL_ACCOUNTS_OF_CUSTOMER` permission and access to the company. Customer users do not call this route; only technicians or freelancers with the matching permission see email accounts.
      parameters:
        - in: path
          name: companyId
          required: true
          description: Id of the company whose email accounts should be returned.
          example: 100023
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: List of email accounts belonging to the company.
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 501
                    companyId: 100023
                    domainId: 17
                    linkTypeId: 2
                    linkId: 100023
                    address: info@beispiel.de
                    type: IMAP
                    username: info@beispiel.de
                    server: mail.beispiel.de
                    port: 993
                    ssl: true
                  - id: 502
                    companyId: 100023
                    domainId: 17
                    linkTypeId: 3
                    linkId: 4711
                    address: max.mustermann@beispiel.de
                    type: IMAP
                    username: max.mustermann
                    server: mail.beispiel.de
                    port: 993
                    ssl: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailAccounts/pdf:
    put:
      operationId: put_api_v1_emailAccounts_pdf
      tags:
        - emailAccounts
      summary: Get email account list as PDF
      description: |
        Builds and returns a PDF of the email-account list for the configuration in the request body (same filter object used by the list endpoint). Depending on the `Accept` header, the controller either streams the PDF directly, emails it, or returns a one-time file-pass URL. Requires the `VIEW_EMAIL_ACCOUNTS_OF_CUSTOMER` permission; the configuration is forced to run permission checks server-side, so only email accounts the caller may see end up in the PDF.
      requestBody:
        description: An object describing which email accounts to include (company filter, text filter, pagination, etc.).
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: integer
                branchFilter:
                  type: string
                textFilter:
                  type: string
                types:
                  type: array
                  items:
                    type: integer
            example:
              companyId: 100023
              branchFilter: COMPANY_AND_BRANCHES
              textFilter: ''
              types: []
      responses:
        '200':
          description: Successful response (PDF, file-pass JSON, or email confirmation depending on `Accept`).
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              example: JVBERi0xLjQKJeLjz9MK
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      url:
                        type: string
                      token:
                        type: string
              example:
                meta: {}
                content:
                  url: https://tanss.example.de/files/by-pass/email-account-list.pdf
                  token: 5e2b9a
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailSettings:
    get:
      operationId: get_api_v1_emailSettings
      tags:
        - email settings
      summary: Get list of mail settings
      description: Returns all configured mailboxes (POP3/IMAP/Microsoft Graph accounts) that the current technician may access, including linked-entity data needed by the mail-settings administration view. Used to populate the list of inboxes a technician can pick when sending mail from a ticket.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of object entries the user may access.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Support inbox
                    smtpHost: smtp.example-it.de
                    smtpUser: support@example-it.de
                    active: true
                  - id: 2
                    name: Sales inbox
                    smtpHost: smtp.example-it.de
                    smtpUser: sales@example-it.de
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_emailSettings
      tags:
        - email settings
      summary: Create mail settings
      description: Creates a new mailbox configuration (POP3/IMAP/SMTP credentials or Microsoft Graph link) used by techs to send and receive emails from tickets. The body is a object object.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the mailbox configuration.
                name:
                  type: string
                  description: Display name of the mailbox configuration.
                assignmentType:
                  type: string
                  description: Type of entity this mailbox is assigned to.
                  enum:
                    - NONE
                    - DEPARTMENT
                assignmentId:
                  type: integer
                  description: Identifier of the entity this mailbox is assigned to.
                pop3Type:
                  type: string
                  description: Incoming mail connection type.
                  enum:
                    - DEFAULT
                    - GRAPH
                    - GMAIL
                    - AZURE
                pop3Host:
                  type: string
                  description: Incoming mail server host name.
                pop3User:
                  type: string
                  description: Incoming mail server user name.
                smtpType:
                  type: string
                  description: Outgoing mail connection type.
                  enum:
                    - DEFAULT
                    - GRAPH
                    - GMAIL
                    - AZURE
                smtpAddress:
                  type: string
                  description: Sender email address used for outgoing mail.
                smtpHost:
                  type: string
                  description: Outgoing mail server host name.
                smtpAuth:
                  type: boolean
                  description: Whether the outgoing mail server requires authentication.
                active:
                  type: boolean
                  description: Whether the mailbox configuration is active.
            example:
              id: 42
              name: Example name
              assignmentType:
                value: 1
              assignmentId: 1
              pop3Type:
                value: 1
              pop3Host: string
              pop3User: string
              smtpType:
                value: 1
              smtpAddress: string
              smtpHost: string
              smtpAuth: false
              active: false
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created object entry.
              example:
                meta: {}
                content:
                  id: 3
                  name: Support inbox
                  smtpHost: smtp.example-it.de
                  smtpUser: support@example-it.de
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailSettings/properties:
    get:
      operationId: get_api_v1_emailSettings_properties
      tags:
        - email settings
      summary: Get mail settings properties
      description: |
        Returns the field metadata (labels, allowed values, picker options) the frontend uses to render the mail-settings form. Used once at form load so the UI knows which encryption types, assignment types, etc. are available.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: A map of object entries describing each form field.
              example:
                meta: {}
                content:
                  pop3EncryptionType:
                    values:
                      - value: NONE
                        label: Keine
                      - value: SSL
                        label: SSL
                      - value: STARTTLS
                        label: STARTTLS
                  smtpEncryptionType:
                    values:
                      - value: NONE
                        label: Keine
                      - value: SSL
                        label: SSL
                      - value: STARTTLS
                        label: STARTTLS
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailSettings/{id}:
    delete:
      operationId: delete_api_v1_emailSettings_id
      tags:
        - email settings
      summary: Delete mail settings
      description: Removes a mailbox configuration. After deletion that inbox is no longer available for sending/receiving mail from tickets.
      parameters:
        - in: path
          name: id
          description: Id of the mailbox / email settings entry.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_emailSettings_id
      tags:
        - email settings
      summary: Get mail settings
      description: Returns the full object for a single mailbox so the configuration view can edit POP3/IMAP/SMTP credentials or Microsoft Graph linkage.
      parameters:
        - in: path
          name: id
          description: Id of the mailbox / email settings entry.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The requested object entry.
              example:
                meta: {}
                content:
                  id: 1
                  name: Support inbox
                  smtpHost: smtp.example-it.de
                  smtpUser: support@example-it.de
                  smtpSenderName: Example IT Support
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_emailSettings_id
      tags:
        - email settings
      summary: Update mail settings
      description: Updates an existing mailbox configuration (credentials, encryption, sender name, reply template, assignment etc.). The body is a object object.
      parameters:
        - in: path
          name: id
          description: Id of the mailbox / email settings entry.
          required: true
          schema:
            type: integer
          example: 42
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the mailbox configuration.
                name:
                  type: string
                  description: Display name of the mailbox configuration.
                assignmentType:
                  type: string
                  description: Type of entity this mailbox is assigned to.
                  enum:
                    - NONE
                    - DEPARTMENT
                assignmentId:
                  type: integer
                  description: Identifier of the entity this mailbox is assigned to.
                pop3Type:
                  type: string
                  description: Incoming mail connection type.
                  enum:
                    - DEFAULT
                    - GRAPH
                    - GMAIL
                    - AZURE
                pop3Host:
                  type: string
                  description: Incoming mail server host name.
                pop3User:
                  type: string
                  description: Incoming mail server user name.
                smtpType:
                  type: string
                  description: Outgoing mail connection type.
                  enum:
                    - DEFAULT
                    - GRAPH
                    - GMAIL
                    - AZURE
                smtpAddress:
                  type: string
                  description: Sender email address used for outgoing mail.
                smtpHost:
                  type: string
                  description: Outgoing mail server host name.
                smtpAuth:
                  type: boolean
                  description: Whether the outgoing mail server requires authentication.
                active:
                  type: boolean
                  description: Whether the mailbox configuration is active.
            example:
              id: 42
              name: Example name
              assignmentType:
                value: 1
              assignmentId: 1
              pop3Type:
                value: 1
              pop3Host: string
              pop3User: string
              smtpType:
                value: 1
              smtpAddress: string
              smtpHost: string
              smtpAuth: false
              active: false
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated object entry.
              example:
                meta: {}
                content:
                  id: 1
                  name: Support inbox
                  smtpHost: smtp.example-it.de
                  smtpUser: support@example-it.de
                  smtpSenderName: Example IT Support
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailSettings/{id}/authUrl:
    get:
      operationId: get_api_v1_emailSettings_id_authUrl
      tags:
        - email settings
      summary: Get auth url
      description: |
        Builds the Microsoft Graph OAuth consent URL for the given mailbox so a tech can authorize TANSS to read mail via Graph. The frontend redirects the user to this URL to complete the OAuth flow.
      parameters:
        - in: path
          name: id
          description: Id of the mailbox / email settings entry.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object carrying the OAuth consent URL.
              example:
                meta: {}
                content:
                  authUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailSettings/{id}/mailFolders:
    get:
      operationId: get_api_v1_emailSettings_id_mailFolders
      tags:
        - email settings
      summary: Get mailfolders
      description: |
        Lists the mail folder tree for a Microsoft Graph-connected mailbox so the tech can choose which folder TANSS should pull mails from. Recursively walks subfolders via the Graph API.
      parameters:
        - in: path
          name: id
          description: Id of the mailbox / email settings entry.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object containing the folder tree.
              example:
                meta: {}
                content:
                  mailFolders:
                    - id: AAMkAD...
                      displayName: Inbox
                      childFolderCount: 2
                      children:
                        - id: AAMkAE...
                          displayName: Tickets
                          childFolderCount: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailSettings/{id}/messages:
    get:
      operationId: get_api_v1_emailSettings_id_messages
      tags:
        - email settings
      summary: Get messages
      description: |
        Loads the messages in the configured Graph mail folder for the given mailbox so the tech can preview which emails TANSS will import. Hits Microsoft Graph directly without persisting the results.
      parameters:
        - in: path
          name: id
          description: Id of the mailbox / email settings entry.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object with the folder's messages.
              example:
                meta: {}
                content:
                  messages:
                    - id: 1024
                      subject: 'Re: Festplatte defekt'
                      from: kunde@example.com
                      to:
                        - support@example-it.de
                      receivedDateTime: '2026-05-26T08:14:00Z'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/emailSettings/{id}/smtpAuthUrl:
    get:
      operationId: get_api_v1_emailSettings_id_smtpAuthUrl
      tags:
        - email settings
      summary: Get smtp auth url
      description: Builds the Microsoft Graph OAuth consent URL specifically for the SMTP-send scope on the given mailbox. The frontend redirects the user there so TANSS can subsequently send mail through Graph on behalf of that user.
      parameters:
        - in: path
          name: id
          description: Id of the mailbox / email settings entry.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object carrying the SMTP OAuth consent URL.
              example:
                meta: {}
                content:
                  authUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&scope=SMTP.Send
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/api/v1/employees/freelancers/{companyId}:
    get:
      operationId: get_api_v1_employees_api_v1_employees_freelancers_companyId
      tags:
        - employees - links & relations
      summary: Get freelancers
      description: |
        Returns the freelancers assigned to the given company. The list is built from the
        set of employees that the security manager flags as freelancers for `companyId`
        and is then materialised via the employee service.
      parameters:
        - in: path
          name: companyId
          description: Id of the company whose freelancers should be returned.
          required: true
          schema:
            type: integer
          example: 100023
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee-Short'
              example:
                meta: {}
                content:
                  - id: 5
                    name: Max Mustermann
                    listType: FREELANCER
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/avatars:
    get:
      operationId: get_api_v1_employees_avatars
      tags:
        - employees - personal data
      summary: Get avatars
      description: |
        Returns the avatar metadata records for the supplied comma-separated list of
        employee ids. Only technicians and freelancers may call this endpoint.
      parameters:
        - in: query
          name: employeeIds
          description: Comma-separated list of employee ids whose avatar metadata should be returned.
          required: false
          schema:
            type: string
            default: ''
          example: 5,6,7
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        employeeId:
                          type: integer
                        avatar:
                          type: string
                          description: base64-encoded image data
              example:
                meta: {}
                content:
                  - employeeId: 5
                    avatar: data:image/png;base64,iVBORw0KGgo...
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/birthdays:
    put:
      operationId: put_api_v1_employees_birthdays
      tags:
        - employees - personal data
      summary: Get birthdays
      description: |-
        Returns the list of employees whose birthday falls within the configured window
        (next/previous days). The caller must be a technician or freelancer and hold the
        `VIEW_BIRTHDAY_OF_ALL_EMPLOYEES` permission. The controller forces
        `usePermissionsOfEmployeeId = 0`, `usePrefValueForNextDays = true` and
        `fillFrontendValues = true` regardless of the body.
      requestBody:
        description: Birthday lookup configuration.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                inTheNextDays:
                  type: integer
                  description: number of days to look ahead
                showPreviousDays:
                  type: integer
                  description: number of past days to include
                companyIds:
                  type: array
                  items:
                    type: integer
            example:
              inTheNextDays: 30
              showPreviousDays: 5
              companyIds:
                - 1
      responses:
        '200':
          description: List of employees with upcoming/recent birthdays.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee'
              example:
                meta: {}
                content:
                  - id: 5
                    name: Max Mustermann
                    firstName: Max
                    lastName: Mustermann
                    birthday: '1977-12-02'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/departments:
    get:
      operationId: get_api_v1_employees_departments
      tags:
        - employees - departments
      summary: Get sales target departments
      description: |
        Returns the list of departments the caller may pick when querying or
        setting sales targets. The caller must be a technician or freelancer.
      responses:
        '200':
          description: Selectable departments for sales-target views.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
              example:
                meta: {}
                content:
                  - id: 3
                    name: Support
                  - id: 4
                    name: Sales
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/departments/{id}:
    delete:
      operationId: delete_api_v1_employees_departments_id
      tags:
        - employees - departments
      summary: Delete department
      description: |
        Deletes the department identified by `id`. Caller must be a technician or
        freelancer and hold the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          description: Id of the department to delete.
          required: true
          schema:
            type: string
          example: '3'
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_employees_departments_id
      tags:
        - employees - departments
      summary: Get department
      description: |
        Returns a single department by id. Caller must be a technician or
        freelancer and hold the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          description: Id of the department to return.
          required: true
          schema:
            type: string
          example: '3'
      responses:
        '200':
          description: Department record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
              example:
                meta: {}
                content:
                  id: 3
                  name: Support
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_employees_departments_id
      tags:
        - employees - departments
      summary: Update department
      description: |
        Updates the department identified by `id`. Caller must be a technician or
        freelancer and hold the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          description: Id of the department to update.
          required: true
          schema:
            type: string
          example: '3'
      requestBody:
        description: JSON body. An object.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string
            example:
              id: 3
              name: Support
      responses:
        '200':
          description: Updated department record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 3
                  name: Support
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/links:
    get:
      operationId: get_api_v1_employees_links
      tags:
        - employees - links & relations
      summary: List employee links
      description: |
        Returns all custom quick-links (bookmarks) for the currently logged-in
        user.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        employeeId:
                          type: integer
                        title:
                          type: string
                        link:
                          type: string
                        target:
                          type: string
              example:
                meta: {}
                content:
                  - id: 7
                    employeeId: 5
                    title: Internal Wiki
                    link: https://wiki.example.com
                    target: _blank
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_employees_links
      tags:
        - employees - links & relations
      summary: Create an employee link
      description: |
        Creates a new quick-link (bookmark) for the currently logged-in user.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - employeeId
                - title
                - link
              properties:
                id:
                  type: integer
                  description: Unique identifier of the employee link entry
                employeeId:
                  type: integer
                  description: Identifier of the employee this link belongs to
                title:
                  type: string
                  description: Display heading shown for the link
                link:
                  type: string
                  description: The URL the entry points to
                target:
                  type: string
                  description: Link target behavior, e.g. how the link opens
            example:
              employeeId: 5
              title: Internal Wiki
              link: https://wiki.example.com
              target: _blank
      responses:
        '201':
          description: Created employee link.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                      employeeId:
                        type: integer
                      title:
                        type: string
                      link:
                        type: string
                      target:
                        type: string
              example:
                meta: {}
                content:
                  id: 7
                  employeeId: 5
                  title: Internal Wiki
                  link: https://wiki.example.com
                  target: _blank
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/links/{id}:
    delete:
      operationId: delete_api_v1_employees_links_id
      tags:
        - employees - links & relations
      summary: Delete an employee link
      description: |
        Removes a single quick-link (bookmark to an URL) belonging to the logged-in
        user's link list.
      parameters:
        - in: path
          name: id
          description: Id of the employee link to delete.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_employees_links_id
      tags:
        - employees - links & relations
      summary: Update an employee link
      description: |
        Updates an existing quick-link entry (title, URL, target) owned by the
        logged-in user.
      parameters:
        - in: path
          name: id
          description: Id of the employee link to update.
          required: true
          schema:
            type: integer
          example: 42
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - employeeId
                - title
                - link
              properties:
                id:
                  type: integer
                  description: Unique identifier of the employee link entry
                employeeId:
                  type: integer
                  description: Identifier of the employee this link belongs to
                title:
                  type: string
                  description: Display heading shown for the link
                link:
                  type: string
                  description: The URL the entry points to
                target:
                  type: string
                  description: Link target behavior, e.g. how the link opens
            example:
              id: 7
              employeeId: 5
              title: Internal Wiki
              link: https://wiki.example.com
              target: _blank
      responses:
        '200':
          description: Updated employee link.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                      employeeId:
                        type: integer
                      title:
                        type: string
                      link:
                        type: string
                      target:
                        type: string
              example:
                meta: {}
                content:
                  id: 7
                  employeeId: 5
                  title: Internal Wiki
                  link: https://wiki.example.com
                  target: _blank
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/notWantedTechnicianAndVacationInfos/{employeeId}/{companyId}:
    get:
      operationId: get_api_v1_employees_notWantedTechnicianAndVacationInfos_employeeId_companyId
      tags:
        - employees - links & relations
      summary: Get blocked-technician and vacation info
      description: |
        Returns, for a given employee/company pair, both the flag whether the
        customer has marked this technician as "not wanted" and the technician's
        current vacation status. Caller must be a technician or freelancer with
        access to `companyId`.
      parameters:
        - in: path
          name: employeeId
          description: Id of the technician/employee to query.
          required: true
          schema:
            type: integer
          example: 5
        - in: path
          name: companyId
          description: Id of the company the technician is evaluated against.
          required: true
          schema:
            type: integer
          example: 100023
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      notWantedTechnician:
                        type: boolean
                      onVacation:
                        type: boolean
                      vacationUntil:
                        type: integer
                        description: unix timestamp when the vacation ends (0 if not on vacation)
              example:
                meta: {}
                content:
                  notWantedTechnician: false
                  onVacation: true
                  vacationUntil: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/ownState:
    get:
      operationId: get_api_v1_employees_ownState
      tags:
        - employees - personal data
      summary: Get own state
      description: |
        Returns a bundled state object for the logged-in user: their employee
        record, user type, default company, granted permissions, accessible company
        ids, licensed modules/features, server API version and the count of unseen
        events. Used by the frontend right after login to populate the session.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      loggedInUser:
                        $ref: '#/components/schemas/Employee'
                      userType:
                        $ref: '#/components/schemas/TnsEmployeeListType'
                      ownCompanyId:
                        type: integer
                      rights:
                        type: array
                        items:
                          type: integer
                      companyAccess:
                        type: array
                        items:
                          type: integer
                      apiVersion:
                        type: string
                      unseenEvents:
                        type: integer
              example:
                meta: {}
                content:
                  loggedInUser:
                    id: 5
                    name: Max Mustermann
                  userType: TECHNICIAN
                  ownCompanyId: 1
                  rights:
                    - 12
                    - 33
                    - 45
                  companyAccess:
                    - 1
                    - 2
                    - 7
                  apiVersion: 1.0.0
                  unseenEvents: 3
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/salutations:
    get:
      operationId: get_api_v1_employees_salutations
      tags:
        - employees - salutations
      summary: List salutations
      description: |
        Returns all salutations. Caller must be a technician or freelancer with
        the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        shortText:
                          type: string
                        longText:
                          type: string
                        gender:
                          type: integer
              example:
                meta: {}
                content:
                  - id: 1
                    shortText: Mr.
                    longText: Mister
                    gender: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_employees_salutations
      tags:
        - employees - salutations
      summary: Create salutation
      description: |
        Creates a new salutation. Caller must be a technician or freelancer with
        the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the salutation.
                shortText:
                  type: string
                  description: Short form of the salutation.
                longText:
                  type: string
                  description: Full form of the salutation.
                gender:
                  type: string
                  description: Gender associated with the salutation.
                  enum:
                    - NOT_SET
                    - MALE
                    - FEMALE
            example:
              shortText: Mr.
              longText: Mister
              gender: 1
      responses:
        '201':
          description: Created salutation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  shortText: Mr.
                  longText: Mister
                  gender: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/salutations/{id}:
    delete:
      operationId: delete_api_v1_employees_salutations_id
      tags:
        - employees - salutations
      summary: Delete salutation
      description: |
        Deletes the salutation (e.g. "Mr.", "Ms.") identified by `id`. Caller must
        be a technician or freelancer with the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`
        permission.
      parameters:
        - in: path
          name: id
          description: Id of the salutation to delete.
          required: true
          schema:
            type: string
          example: '1'
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_employees_salutations_id
      tags:
        - employees - salutations
      summary: Get salutation
      description: |
        Returns a single salutation record by id. Caller must be a technician
        or freelancer with the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          description: Id of the salutation to return.
          required: true
          schema:
            type: string
          example: '1'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                      shortText:
                        type: string
                      longText:
                        type: string
                      gender:
                        type: integer
              example:
                meta: {}
                content:
                  id: 1
                  shortText: Mr.
                  longText: Mister
                  gender: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_employees_salutations_id
      tags:
        - employees - salutations
      summary: Update salutation
      description: |
        Updates a salutation. Caller must be a technician or freelancer with the
        `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          description: Id of the salutation to update.
          required: true
          schema:
            type: string
          example: '1'
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the salutation.
                shortText:
                  type: string
                  description: Short form of the salutation.
                longText:
                  type: string
                  description: Full form of the salutation.
                gender:
                  type: string
                  description: Gender associated with the salutation.
                  enum:
                    - NOT_SET
                    - MALE
                    - FEMALE
            example:
              id: 1
              shortText: Mr.
              longText: Mister
              gender: 1
      responses:
        '200':
          description: Updated salutation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  shortText: Mr.
                  longText: Mister
                  gender: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/titles:
    get:
      operationId: get_api_v1_employees_titles
      tags:
        - employees - titles
      summary: List employee titles
      description: |
        Returns all employee titles. Caller must be a technician or freelancer
        with the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
              example:
                meta: {}
                content:
                  - id: 2
                    name: Dr.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_employees_titles
      tags:
        - employees - titles
      summary: Create an employee title
      description: |
        Creates a new employee title. Caller must be a technician or freelancer
        with the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              name: Dr.
      responses:
        '201':
          description: Created title.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 2
                  name: Dr.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/titles/{id}:
    delete:
      operationId: delete_api_v1_employees_titles_id
      tags:
        - employees - titles
      summary: Delete an employee title
      description: |
        Deletes the employee title (e.g. "Dr.", "Prof.") identified by `id`. Caller
        must be a technician or freelancer with the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`
        permission.
      parameters:
        - in: path
          name: id
          description: Id of the employee title to delete.
          required: true
          schema:
            type: string
          example: '2'
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_employees_titles_id
      tags:
        - employees - titles
      summary: Get an employee title
      description: |
        Returns a single employee title by id. Caller must be a technician or
        freelancer with the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          description: Id of the employee title to return.
          required: true
          schema:
            type: string
          example: '2'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
              example:
                meta: {}
                content:
                  id: 2
                  name: Dr.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_employees_titles_id
      tags:
        - employees - titles
      summary: Update an employee title
      description: |
        Updates an employee title. Caller must be a technician or freelancer with
        the `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          description: Id of the employee title to update.
          required: true
          schema:
            type: string
          example: '2'
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              id: 2
              name: Dr.
      responses:
        '200':
          description: Updated title.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 2
                  name: Dr.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/{id}:
    get:
      operationId: get_api_v1_employees_id
      tags:
        - employees
      summary: Get a single employee
      description: |-
        Returns the employee record for the given id. The CRUD service checks
        that the caller has access to the employee's company before returning.
      parameters:
        - in: path
          name: id
          description: Id of the employee to return.
          required: true
          schema:
            type: integer
          example: 5
      responses:
        '200':
          description: Employee record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Employee'
              example:
                meta: {}
                content:
                  id: 5
                  name: Max Mustermann
                  firstName: Max
                  lastName: Mustermann
                  emailAddress: max.mustermann@example.com
                  departmentId: 3
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_employees_id
      tags:
        - employees
      summary: Update an employee
      description: |-
        Updates the employee identified by `id` from the merged JSON body. Field-level
        rights are honoured by the service (`mergeJsonUsingCheckedRights`); company access
        and `EMPLOYEE_ADMINISTRATION` are required to make changes.
      parameters:
        - in: path
          name: id
          description: Id of the employee to update.
          required: true
          schema:
            type: integer
          example: 5
      requestBody:
        description: Partial or full `Employee` payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Employee'
            example:
              id: 5
              firstName: Max
              lastName: Mustermann
              emailAddress: max.mustermann@example.com
              departmentId: 3
              active: true
      responses:
        '200':
          description: Updated employee record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    $ref: '#/components/schemas/Employee'
              example:
                meta: {}
                content:
                  id: 5
                  name: Max Mustermann
                  firstName: Max
                  lastName: Mustermann
                  emailAddress: max.mustermann@example.com
                  departmentId: 3
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/{id}/avatar:
    delete:
      operationId: delete_api_v1_employees_id_avatar
      tags:
        - employees - personal data
      summary: Delete avatar
      description: |
        Removes the avatar image of the given employee. The CRUD service only
        allows deletion of the caller's own avatar (`employeeId == userId`); any
        other id is rejected.
      parameters:
        - in: path
          name: id
          description: Id of the employee whose avatar should be deleted.
          required: true
          schema:
            type: integer
          example: 5
      responses:
        '204':
          description: Avatar deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_employees_id_avatar
      tags:
        - employees - personal data
      summary: Get avatar
      description: |
        Returns the avatar image record (base64 payload) for the given employee.
        Restricted to technicians and freelancers.
      parameters:
        - in: path
          name: id
          description: Id of the employee whose avatar should be returned.
          required: true
          schema:
            type: integer
          example: 5
      responses:
        '200':
          description: Avatar record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      employeeId:
                        type: integer
                      avatar:
                        type: string
              example:
                meta: {}
                content:
                  employeeId: 5
                  avatar: data:image/png;base64,iVBORw0KGgo...
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_employees_id_avatar
      tags:
        - employees - personal data
      summary: Upload avatar
      description: |
        Uploads a new avatar image (multipart `avatar` field) for the given
        employee. The CRUD service requires `employeeId == userId`, so callers
        can only upload their own picture.
      parameters:
        - in: path
          name: id
          description: Id of the employee whose avatar should be uploaded.
          required: true
          schema:
            type: integer
          example: 5
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                avatar:
                  type: string
                  format: binary
      responses:
        '201':
          description: Avatar stored.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      employeeId:
                        type: integer
              example:
                meta: {}
                content:
                  employeeId: 5
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/{id}/properties:
    post:
      operationId: post_api_v1_employees_id_properties
      tags:
        - employees - personal data
      summary: Get employee properties
      description: |
        Loads the existing employee (or an empty one when `id = 0`), merges the
        posted JSON patch under the rules of the caller's rights and returns the
        full property/permission descriptor used by the edit dialog (editable
        fields, choices, validation messages). Requires the `EMPLOYEE_ADMINISTRATION`
        permission; access to the actual record is verified.
      parameters:
        - in: path
          name: id
          description: Id of the employee whose properties should be loaded (use 0 for a new employee).
          required: true
          schema:
            type: integer
          example: 5
        - in: query
          name: property
          description: Optional single property name to restrict the returned descriptor to.
          required: false
          schema:
            type: string
            default: ''
          example: emailAddress
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the employee.
                name:
                  type: string
                  description: Display name of the employee.
                firstName:
                  type: string
                  description: First name of the employee.
                lastName:
                  type: string
                  description: Last name of the employee.
                login:
                  type: string
                  description: Login user name of the employee.
                emailAddress:
                  type: string
                  description: Business email address of the employee.
                telephoneNumber:
                  type: string
                  description: Primary telephone number of the employee.
                mobilePhone:
                  type: string
                  description: Mobile phone number of the employee.
                departmentId:
                  type: integer
                  description: Identifier of the department the employee belongs to.
                titleId:
                  type: integer
                  description: Identifier of the employee's title.
                active:
                  type: boolean
                  description: Whether the employee account is active.
                language:
                  type: string
                  description: Preferred interface language code of the employee.
            example:
              id: 5
              name: Max Mustermann
              firstName: Max
              lastName: Mustermann
              departmentId: 3
              login: max.mustermann
              emailAddress: max.mustermann@example.com
              telephoneNumber: +49 30 1234567
              mobilePhone: +49 30 7654321
              active: true
      responses:
        '201':
          description: Property descriptor for the (merged) employee.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      fields:
                        type: object
                      permissions:
                        type: object
                      editable:
                        type: boolean
              example:
                meta: {}
                content:
                  fields:
                    emailAddress:
                      value: max.mustermann@example.com
                      editable: true
                    departmentId:
                      value: 3
                      editable: true
                  permissions:
                    edit: true
                  editable: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/employees/{id}/reachability:
    delete:
      operationId: delete_api_v1_employees_id_reachability
      tags:
        - employees - personal data
      summary: Delete reachability entry
      description: |
        Removes a single reachability (availability window) entry identified by its
        id. Access is enforced by the reachability service's own access checks.
      parameters:
        - in: path
          name: id
          description: Id of the reachability entry to delete.
          required: true
          schema:
            type: string
          example: '42'
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/entityFiles/{id}:
    delete:
      operationId: delete_api_v1_entityFiles_id
      tags:
        - entity files
      summary: Delete an entity file
      description: |
        Deletes the entity-file row and the underlying file on disk. Deletion requires full company access plus the matching `DELETE_*` permission depending on the file's `documentType` (standard, barcode, uploaded, knowledge-base). A failure to remove the on-disk file is logged but does not roll back the database delete.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the entity file.
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_entityFiles_id
      tags:
        - entity files
      summary: Get a download pass for an entity file
      description: |
        Returns a short-lived object for the entity file, which the frontend then uses to actually download the binary through the file-pass endpoint. Access to the file is checked first, so this also acts as the authorisation gate for the subsequent download.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the entity file.
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: object carrying the one-shot download token for the file.
              example:
                meta: {}
                content:
                  id: 1
                  linkType: TICKET
                  linkId: 4711
                  fileName: screenshot.png
                  size: 102400
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_entityFiles_id
      tags:
        - entity files
      summary: Update entity file metadata
      description: |
        Updates the metadata of an entity file (e.g. `title`, `internal` flag, `documentType`). Only the metadata fields are touched here — the actual file payload is not part of this route. Standard permission and access checks apply.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the entity file.
          example: 42
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the stored file
                filename:
                  type: string
                  description: Original display name of the file
                storedFilename:
                  type: string
                  description: Internal name under which the file is stored
                title:
                  type: string
                  description: Descriptive label of the file
                senderEmail:
                  type: string
                  description: Email address of the sender who provided the file
                senderId:
                  type: integer
                  description: Identifier of the sender who uploaded the file
                documentType:
                  type: string
                  description: Category of the document
                  enum:
                    - STANDARD
                    - BARCODE
                    - UPLOADED
                    - KNOWLEDGE_BASE
                internal:
                  type: boolean
                  description: Whether the file is marked as internal only
            example:
              id: 42
              filename: example.pdf
              storedFilename: example.pdf
              senderEmail: user@example.com
              senderId: 1
              title: Example title
              documentType:
                value: 1
              internal: false
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated object row.
              example:
                meta: {}
                content:
                  id: 1
                  linkType: TICKET
                  linkId: 4711
                  fileName: screenshot.png
                  size: 102400
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/entityFiles/{linkType}/{linkId}:
    get:
      operationId: get_api_v1_entityFiles_linkType_linkId
      tags:
        - entity files
      summary: List entity files attached to a linked entity
      description: |
        Returns object for the entity identified by `linkType` + `linkId` — i.e. all uploaded documents plus UI hints (`showIcon`, `mayUpload`, per-document `mayDelete` and resolved file size). If the caller has no access to the link type, an empty container with `showIcon=false` is returned instead of an error. Used by ticket/company/asset views to render the paperclip icon and the documents pop-out.
      parameters:
        - in: path
          name: linkType
          required: true
          description: Type of the linked entity (e.g. TICKET).
          example: TICKET
          schema:
            type: string
        - in: path
          name: linkId
          required: true
          description: ID of the linked entity.
          example: 4711
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: object with the documents and UI flags for the linked entity.
              example:
                meta: {}
                content:
                  id: 1
                  linkType: TICKET
                  linkId: 4711
                  fileName: screenshot.png
                  size: 102400
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_entityFiles_linkType_linkId
      tags:
        - entity files
      summary: Upload one or more files to a linked entity
      description: |
        Uploads a file (multipart `file`) or several files (multipart `files`) and attaches each to the entity identified by `linkType` + `linkId`. Single uploads return one object, multi-uploads return the list. Returns `BAD_REQUEST` when neither field is set. The service generates a unique stored filename on disk and applies upload permission checks per link type.
      parameters:
        - in: path
          name: linkType
          required: true
          description: Type of the linked entity (e.g. TICKET).
          example: TICKET
          schema:
            type: string
        - in: path
          name: linkId
          required: true
          description: ID of the linked entity.
          example: 4711
          schema:
            type: integer
        - in: query
          name: file
          required: false
          description: Optional single file payload reference for the upload.
          example: contract.pdf
          schema:
            type: string
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The uploaded object (single upload) or a list of them (multi upload).
              example:
                meta: {}
                content:
                  id: 1
                  linkType: TICKET
                  linkId: 4711
                  fileName: screenshot.png
                  size: 102400
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/erp/projects:
    get:
      operationId: get_api_v1_erp_projects
      tags:
        - erp
      summary: Get projects
      description: |
        Returns the list of projects from the configured ERP backend via the factory-resolved ERP service. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login. If no ERP service is configured, an empty list is returned.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/erp/stocks:
    get:
      operationId: get_api_v1_erp_stocks
      tags:
        - erp
      summary: Get stocks
      description: |
        Returns the list of stocks (warehouses/inventories) from the configured ERP backend via the factory-resolved ERP service. Intended for ERP integrations — must be called with the dedicated API token bound to the role `ERP`, not a normal user login. If no ERP service is configured, an empty list is returned.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations:
    get:
      operationId: get_api_v1_escalations
      tags:
        - escalations
      summary: Get escalation list
      description: |
        Returns the full, unfiltered list of escalation rules configured in the system. Escalation rules drive automated SLA reactions (e-mails, status changes, technician reassignment) when tickets or supports breach a configured threshold. Requires the MANAGE_TICKET_ESCALATION permission and technician/freelancer role.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of escalation rules.
              example:
                meta: {}
                content:
                  - id: 1
                    name: SLA Bronze 4h
                    active: true
                    categoryId: 1
                    thresholdMinutes: 240
                    triggerLogicOperator: AND
                    action: MAIL_TO_MANAGER
                  - id: 2
                    name: SLA Gold 1h
                    active: true
                    categoryId: 1
                    thresholdMinutes: 60
                    triggerLogicOperator: AND
                    action: REASSIGN_TO_ON_CALL
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_escalations
      tags:
        - escalations
      summary: Create escalation
      description: |
        Creates a new escalation rule. After persistence the engine will start considering this rule on every periodic escalation check (and on the manual `/check` route). Requires MANAGE_TICKET_ESCALATION.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the escalation rule
                name:
                  type: string
                  description: Name of the escalation rule
                description:
                  type: string
                  description: Descriptive text explaining the rule
                active:
                  type: boolean
                  description: Whether the rule is currently active
                triggerLogicOperator:
                  type: string
                  description: Logical operator combining the rule triggers
                  enum:
                    - AND
                    - OR
                    - NOT
                    - NOT_AND
                    - GREATER_THAN
                    - GREATER_OR_EQUAL
                    - LESS_THAN
                    - LESS_OR_EQUAL
                    - EQUALS
                categoryId:
                  type: integer
                  description: Identifier of the escalation category the rule belongs to
                conditions:
                  type: array
                  description: Conditions that must be met for the rule to apply
                  items:
                    type: object
                triggers:
                  type: array
                  description: Triggers that cause the rule to fire
                  items:
                    type: object
                events:
                  type: array
                  description: Actions executed when the rule triggers
                  items:
                    type: object
            example:
              name: SLA Bronze 4h
              description: Auto-mail an Manager wenn Bronze-Ticket > 4h offen
              active: true
              triggerLogicOperator: AND
              categoryId: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created escalation rule.
              example:
                meta: {}
                content:
                  id: 3
                  name: SLA Bronze 4h
                  active: true
                  categoryId: 1
                  thresholdMinutes: 240
                  triggerLogicOperator: AND
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_escalations
      tags:
        - escalations
      summary: Get rule list
      description: |
        Returns escalation rules using a paginated/filtered configuration in the body (search text, sort order, category filter, …). Use this variant when the frontend needs to render a list view with filters; for an unconditional dump use GET.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                searchText:
                  type: string
                  description: Free-text search term used to filter escalation rules
                active:
                  type: string
                  description: Filter for active, inactive, or all rules
                  enum:
                    - ACTIVE_ONLY
                    - INACTIVE_ONLY
                    - ACTIVE_AND_INACTIVE
                id:
                  type: integer
                  description: Restrict results to a specific escalation rule identifier
                categoryId:
                  type: integer
                  description: Restrict results to a specific escalation category
                loadAttachedEntities:
                  type: boolean
                  description: Whether related entities should be loaded with the results
                sortOrder:
                  type: string
                  description: Sort direction of the result list
                  enum:
                    - ASC
                    - DESC
                sortField:
                  type: string
                  description: Field the result list is sorted by
                  enum:
                    - ID
                    - NAME
            example:
              searchText: SLA
              categoryId: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of escalation rules matching the configuration.
              example:
                meta: {}
                content:
                  - id: 1
                    name: SLA Bronze 4h
                    active: true
                    categoryId: 1
                    thresholdMinutes: 240
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/categories:
    get:
      operationId: get_api_v1_escalations_categories
      tags:
        - escalation categories
      summary: Get escalation category list
      description: |
        Returns all escalation categories — the labelled groups under which escalation rules can be filed for easier maintenance.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of escalation categories.
              example:
                meta: {}
                content:
                  - id: 1
                    name: SLA
                  - id: 2
                    name: Sicherheit
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_escalations_categories
      tags:
        - escalation categories
      summary: Create escalation category
      description: |
        Creates a new escalation category that escalation rules can later be assigned to. Requires MANAGE_TICKET_ESCALATION.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the escalation category
                name:
                  type: string
                  description: Name of the escalation category
            example:
              name: SLA
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created escalation category.
              example:
                meta: {}
                content:
                  id: 3
                  name: SLA
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/categories/{categoryId}:
    delete:
      operationId: delete_api_v1_escalations_categories_categoryId
      tags:
        - escalation categories
      summary: Delete escalation category
      description: |
        Deletes an escalation category. Rules currently referencing the category will keep their `categoryId` pointer; the data should be cleaned up by the caller. Requires MANAGE_TICKET_ESCALATION.
      parameters:
        - in: path
          name: categoryId
          required: true
          description: Id of the escalation category to delete.
          schema:
            type: integer
          example: 1
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_escalations_categories_categoryId
      tags:
        - escalation categories
      summary: Get escalation category
      description: |
        Returns a single escalation category by id. Categories are simple labelled buckets used to group escalation rules in the UI.
      parameters:
        - in: path
          name: categoryId
          required: true
          description: Id of the escalation category to fetch.
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Escalation category.
              example:
                meta: {}
                content:
                  id: 1
                  name: SLA
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_escalations_categories_categoryId
      tags:
        - escalation categories
      summary: Edit escalation category
      description: |
        Updates an escalation category (rename only; categories carry no behaviour beyond grouping). Requires MANAGE_TICKET_ESCALATION.
      parameters:
        - in: path
          name: categoryId
          required: true
          description: Id of the escalation category to update.
          schema:
            type: integer
          example: 1
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the escalation category
                name:
                  type: string
                  description: Name of the escalation category
            example:
              id: 1
              name: SLA
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Updated escalation category.
              example:
                meta: {}
                content:
                  id: 1
                  name: SLA
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/check:
    put:
      operationId: put_api_v1_escalations_check
      tags:
        - escalations
      summary: Check and execute escalations
      description: |
        Triggers the escalation engine on demand instead of waiting for the periodic scheduled run. The behaviour is governed by `checkMode` (SHOW = dry-run, EXECUTE = also fire the configured actions). Intended for testing and forced re-evaluation; logging is always enabled when invoked through this route. Requires MANAGE_TICKET_ESCALATION.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                checkMode:
                  type: string
                  description: Mode determining how the escalation check acts
                  enum:
                    - SHOW
                    - SIMULATE
                    - ESCALATE
                ruleId:
                  type: integer
                  description: Restrict processing to a single escalation rule
                ticketId:
                  type: integer
                  description: Restrict processing to a single ticket
                loggingIfPossible:
                  type: boolean
                  description: Whether check results should be logged when possible
                logActivatedCheck:
                  type: boolean
                  description: Whether the activation of the check itself should be logged
                checkStartedFrom:
                  type: string
                  description: Origin from which the check was started
                resetRulesIfPossble:
                  type: boolean
                  description: Whether rules with a reset event should be reset
            example:
              checkMode: SHOW
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Per-rule evaluation result list.
              example:
                meta: {}
                content:
                  - ruleId: 1
                    ruleName: SLA Bronze 4h
                    matchedTicketIds:
                      - 4711
                      - 4712
                    executed: false
                  - ruleId: 2
                    ruleName: SLA Gold 1h
                    matchedTicketIds: []
                    executed: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/frontend/conditions/{conditionType}:
    get:
      operationId: get_api_v1_escalations_frontend_conditions_conditionType
      tags:
        - escalations
      summary: Get condition frontend values
      description: |
        Returns the property-field definition (input type, possible values, validation) the frontend needs to render a configuration form for an escalation rule condition of the given type. Returns `null` content if no strategy is registered for the type.
      parameters:
        - in: path
          name: conditionType
          required: true
          description: Escalation rule condition type whose frontend form definition is requested.
          schema:
            type: string
          example: TIME
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Property-field descriptor for the requested condition type.
              example:
                meta: {}
                content:
                  type: SELECT
                  key: ticketStatus
                  label: Ticket-Status
                  options:
                    - value: 1
                      label: Offen
                    - value: 2
                      label: In Bearbeitung
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/frontend/events/{eventType}:
    get:
      operationId: get_api_v1_escalations_frontend_events_eventType
      tags:
        - escalations
      summary: Get events frontend values
      description: |
        Returns the configuration metadata the frontend needs to render the form for an escalation-rule event of the given type (e.g. "send mail", "change status"). Throws a bad-request error when no matching event strategy is registered.
      parameters:
        - in: path
          name: eventType
          required: true
          description: Escalation rule event type whose frontend form definition is requested.
          schema:
            type: string
          example: TICKET_CREATED
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Frontend value descriptor for the requested event type.
              example:
                meta: {}
                content:
                  type: MAIL
                  fields:
                    - key: recipient
                      label: Empfänger
                      inputType: EMAIL
                    - key: subject
                      label: Betreff
                      inputType: TEXT
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/getRulesForTicket/{ticketId}:
    get:
      operationId: get_api_v1_escalations_getRulesForTicket_ticketId
      tags:
        - escalations
      summary: Get rules for ticket
      description: |
        Returns the ids of every escalation rule whose conditions currently match the given ticket. Useful for debugging "why did this ticket escalate?" without running the full execution path.
      parameters:
        - in: path
          name: ticketId
          required: true
          description: Id of the ticket to evaluate against all escalation rules.
          schema:
            type: integer
          example: 4711
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of escalation-rule ids that currently match the ticket.
              example:
                meta: {}
                content:
                  - 1
                  - 4
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/getTicketsForRule/{ruleId}:
    get:
      operationId: get_api_v1_escalations_getTicketsForRule_ruleId
      tags:
        - escalations
      summary: Get tickets for rule
      description: |
        Returns the ids of every ticket currently matching the given escalation rule. Debug helper used to verify rule definitions before activating them.
      parameters:
        - in: path
          name: ruleId
          required: true
          description: Id of the escalation rule whose matching tickets are requested.
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of ticket ids matching the rule.
              example:
                meta: {}
                content:
                  - 4711
                  - 4712
                  - 4717
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/isTicket/{ticketId}/inRule/{ruleId}:
    get:
      operationId: get_api_v1_escalations_isTicket_ticketId_inRule_ruleId
      tags:
        - escalations
      summary: Is ticket in rule
      description: |
        Returns true if the given ticket currently satisfies every condition of the given escalation rule. Debug-only — gives a focused yes/no instead of running through the full check route.
      parameters:
        - in: path
          name: ticketId
          required: true
          description: Id of the ticket to test.
          schema:
            type: integer
          example: 4711
        - in: path
          name: ruleId
          required: true
          description: Id of the escalation rule to test the ticket against.
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: 'Boolean: true if the ticket matches the rule.'
              example:
                meta: {}
                content: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/statistics:
    put:
      operationId: put_api_v1_escalations_statistics
      tags:
        - escalations
      summary: Get statistics
      description: |
        Aggregates escalation activity (counts per rule, breaches per company, time-bucketed totals, etc.) over the range described in the body. The exact aggregation is driven by query parameters. Requires escalation-statistics permissions.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleIds:
                  type: array
                  description: IDs of the escalation rules to include in the statistics
                  items:
                    type: object
                categoryIds:
                  type: array
                  description: IDs of the ticket categories to filter the statistics by
                  items:
                    type: object
                companyIds:
                  type: array
                  description: IDs of the companies to filter the statistics by
                  items:
                    type: object
                ticketCreationTimeframe:
                  type: object
                  description: Time range restricting results to tickets created within it
                escTriggeredTimeframe:
                  type: object
                  description: Time range restricting results to escalations triggered within it
            example:
              ruleIds:
                - 1
                - 2
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Aggregated escalation statistics.
              example:
                meta: {}
                content:
                  fromTimestamp: 1745600000
                  toTimestamp: 1748256000
                  totalTriggered: 27
                  perRule:
                    - ruleId: 1
                      ruleName: SLA Bronze 4h
                      triggered: 19
                    - ruleId: 2
                      ruleName: SLA Gold 1h
                      triggered: 8
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/updateRelevantInfos:
    put:
      operationId: put_api_v1_escalations_updateRelevantInfos
      tags:
        - escalations
      summary: Update relevant infos
      description: |
        Rebuilds the cached "relevant info" snapshots used by the escalation engine to evaluate rules quickly (e.g. last status change timestamps, deadlines). Scope can be limited via the body to specific tickets/rules; otherwise everything is refreshed. Requires MANAGE_TICKET_ESCALATION.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleId:
                  type: integer
                  description: Restrict the update to a single escalation rule
                ticketId:
                  type: integer
                  description: Restrict the update to a single ticket
                loggingIfPossible:
                  type: boolean
                  description: Whether the update should be logged when possible
                updateStartedFrom:
                  type: string
                  description: Origin from which the update was started
                hash:
                  type: string
                  description: Hash value used to identify or deduplicate the update run
                startDate:
                  type: integer
                  format: int64
                  description: Start timestamp of the update run
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Per-rule update result list.
              example:
                meta: {}
                content:
                  - ruleId: 1
                    updatedTickets: 12
                    durationMs: 84
                  - ruleId: 2
                    updatedTickets: 4
                    durationMs: 22
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/{id}:
    delete:
      operationId: delete_api_v1_escalations_id
      tags:
        - escalations
      summary: Delete escalation
      description: |
        Removes an escalation rule together with its associated conditions and events. Requires MANAGE_TICKET_ESCALATION.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the escalation rule to delete.
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_escalations_id
      tags:
        - escalations
      summary: Get escalation
      description: |
        Returns a single escalation rule along with its attached conditions and events. Requires MANAGE_TICKET_ESCALATION.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the escalation rule to fetch.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Escalation rule with conditions and events.
              example:
                meta: {}
                content:
                  id: 1
                  name: SLA Bronze 4h
                  active: true
                  categoryId: 1
                  thresholdMinutes: 240
                  triggerLogicOperator: AND
                  conditions:
                    - id: 4
                      type: TICKET_STATUS
                      value: OPEN
                  events:
                    - id: 7
                      type: MAIL
                      recipient: manager@example.com
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_escalations_id
      tags:
        - escalations
      summary: Edit escalation
      description: |
        Updates an existing escalation rule (name, threshold, trigger logic operator, category, etc.). Activation/deactivation toggles are also done through this route. Requires MANAGE_TICKET_ESCALATION.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the escalation rule to update.
          schema:
            type: integer
          example: 42
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the escalation rule
                name:
                  type: string
                  description: Name of the escalation rule
                description:
                  type: string
                  description: Descriptive text explaining the rule
                active:
                  type: boolean
                  description: Whether the rule is currently active
                triggerLogicOperator:
                  type: string
                  description: Logical operator combining the rule triggers
                  enum:
                    - AND
                    - OR
                    - NOT
                    - NOT_AND
                    - GREATER_THAN
                    - GREATER_OR_EQUAL
                    - LESS_THAN
                    - LESS_OR_EQUAL
                    - EQUALS
                categoryId:
                  type: integer
                  description: Identifier of the escalation category the rule belongs to
                conditions:
                  type: array
                  description: Conditions that must be met for the rule to apply
                  items:
                    type: object
                triggers:
                  type: array
                  description: Triggers that cause the rule to fire
                  items:
                    type: object
                events:
                  type: array
                  description: Actions executed when the rule triggers
                  items:
                    type: object
            example:
              id: 1
              name: SLA Bronze 4h
              description: Auto-mail an Manager wenn Bronze-Ticket > 4h offen
              active: true
              triggerLogicOperator: AND
              categoryId: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Updated escalation rule.
              example:
                meta: {}
                content:
                  id: 1
                  name: SLA Bronze 4h
                  active: true
                  categoryId: 1
                  thresholdMinutes: 240
                  triggerLogicOperator: AND
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/escalations/{id}/copy:
    post:
      operationId: post_api_v1_escalations_id_copy
      tags:
        - escalations
      summary: Copy escalation
      description: |
        Duplicates an existing escalation rule including its conditions and events. The copy is created inactive (or under the rule-service's defaults) so it can be tweaked before being switched on. Requires MANAGE_TICKET_ESCALATION.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the escalation rule to duplicate.
          schema:
            type: integer
          example: 42
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The copied escalation rule.
              example:
                meta: {}
                content:
                  id: 12
                  name: SLA Bronze 4h (Kopie)
                  active: false
                  categoryId: 1
                  thresholdMinutes: 240
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/favorites/search/{linkTypeId}:
    get:
      operationId: get_api_v1_favorites_search_linkTypeId
      tags:
        - employees
      summary: Get favorites in search-result format
      description: |
        Returns the current user's favorites for the given `linkTypeId` formatted
        as search-result items (so that they can be merged into the global search
        suggestions UI).
      parameters:
        - in: path
          name: linkTypeId
          description: Link type to filter favorites by (e.g. company, ticket, employee).
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        linkTypeId:
                          type: integer
                        linkId:
                          type: integer
                        label:
                          type: string
              example:
                meta: {}
                content:
                  - linkTypeId: 1
                    linkId: 42
                    label: 'TICKET-42: Printer issue'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/favorites/{linkTypeId}:
    get:
      operationId: get_api_v1_favorites_linkTypeId
      tags:
        - employees
      summary: List favorites
      description: |
        Returns the currently logged-in user's favorites filtered by link type
        (e.g. tickets, companies, employees).
      parameters:
        - in: path
          name: linkTypeId
          description: Link type to filter favorites by (e.g. company, ticket, employee).
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        linkTypeId:
                          type: integer
                        linkId:
                          type: integer
                        name:
                          type: string
              example:
                meta: {}
                content:
                  - linkTypeId: 1
                    linkId: 42
                    name: 'TICKET-42: Printer issue'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/favorites/{linkTypeId}/{linkId}:
    delete:
      operationId: delete_api_v1_favorites_linkTypeId_linkId
      tags:
        - employees
      summary: Remove a favorite
      description: |
        Removes the favorite of the given link type (`linkTypeId`, e.g. company,
        ticket, employee) pointing at `linkId` from the currently logged-in user's
        favorites list.
      parameters:
        - in: path
          name: linkTypeId
          description: Link type of the favorite (e.g. company, ticket, employee).
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: linkId
          description: Id of the linked entity to remove from favorites.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_favorites_linkTypeId_linkId
      tags:
        - employees
      summary: Add a favorite
      description: |
        Adds an entity (identified by `linkTypeId` + `linkId`, e.g. a ticket or
        company) to the currently logged-in user's favorites list.
      parameters:
        - in: path
          name: linkTypeId
          description: Link type of the favorite (e.g. company, ticket, employee).
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: linkId
          description: Id of the linked entity to add to favorites.
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      linkTypeId:
                        type: integer
                      linkId:
                        type: integer
              example:
                meta: {}
                content:
                  linkTypeId: 1
                  linkId: 42
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/filesAndLinks:
    post:
      operationId: post_api_v1_filesAndLinks
      tags:
        - files & links
      summary: Create files-and-links folder
      description: |
        Creates a new files-and-links node (used as a folder/container in the knowledge base tree). Requires the knowledge base v2 feature plus the FILES_LINKS_ACTIVATED config flag, and the MANAGE_FILE_IMPORTANT_LINKS permission. `createdAt`/`createdBy` and `modifiedAt`/`modifiedBy` are set server-side.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Unique identifier of the file or link entry
                icon:
                  type: string
                  description: Icon representing the entry
                title:
                  type: string
                  description: Display title of the file or link entry
                parentId:
                  type: integer
                  description: ID of the parent entry this item is nested under
                createdAt:
                  type: integer
                  format: int64
                  description: Timestamp when the entry was created
                createdBy:
                  type: integer
                  description: ID of the user who created the entry
                modifiedAt:
                  type: integer
                  format: int64
                  description: Timestamp when the entry was last modified
                modifiedBy:
                  type: integer
                  description: ID of the user who last modified the entry
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created files-and-links node.
              example:
                meta: {}
                content:
                  id: 12
                  title: Wichtige Vertragsdokumente
                  icon: folder
                  parentId: 0
                  createdAt: 1748256000
                  createdBy: 17
                  modifiedAt: 1748256000
                  modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_filesAndLinks
      tags:
        - files & links
      summary: List files-and-links nodes
      description: |
        Returns files-and-links nodes for a given `parentId`. With `withChildren=true` the response is recursively expanded into a full tree; for each node the attached media filenames and URL titles are collected into `fileNames`.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentId:
                  type: integer
                  description: ID of the parent entry whose files and links should be listed
                withChildren:
                  type: boolean
                  description: Whether to include nested child entries in the result
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of files-and-links nodes, optionally with child trees.
              example:
                meta: {}
                content:
                  - id: 12
                    title: Wichtige Vertragsdokumente
                    icon: folder
                    parentId: 0
                    createdAt: 1748256000
                    createdBy: 17
                    modifiedAt: 1748256000
                    modifiedBy: 17
                    fileNames:
                      - Angebot.pdf
                      - https://kunde.example/portal
                    children: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/filesAndLinks/favorites:
    get:
      operationId: get_api_v1_filesAndLinks_favorites
      tags:
        - files & links
      summary: Get favorite files-and-links nodes
      description: |
        Returns the files-and-links nodes that the current user has marked as favorites. Favorites are stored as a per-user JSON preference string and resolved into full node objects here.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of files-and-links nodes the user has favorited.
              example:
                meta: {}
                content:
                  - id: 12
                    title: Wichtige Vertragsdokumente
                    icon: folder
                    parentId: 0
                    createdAt: 1748256000
                    createdBy: 17
                    modifiedAt: 1748256000
                    modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/filesAndLinks/latestUploads:
    get:
      operationId: get_api_v1_filesAndLinks_latestUploads
      tags:
        - files & links
      summary: Get latest uploads
      description: |
        Returns the 10 most recently modified files-and-links entries across both media attachments and URL links, sorted descending by `modifiedAt`. Used by the dashboard / quick-access panel.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Up to 10 most recently modified media or URL entries.
              example:
                meta: {}
                content:
                  - id: 1
                    type: MEDIA
                    title: Angebot Migration M365
                    modifiedAt: 1748256000
                    modifiedBy: 17
                  - id: 7
                    type: URL
                    title: Kundenportal
                    modifiedAt: 1748169600
                    modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/filesAndLinks/{id}:
    delete:
      operationId: delete_api_v1_filesAndLinks_id
      tags:
        - files & links
      summary: Delete files-and-links entry
      description: |
        Deletes the files-and-links entry with the given id. For folder nodes (mounted under `/filesAndLinks/{id}`) this cascades into all child nodes, attached media files, attached URLs and removes the id from every user's favorites preference. Media and URL endpoints simply delete the row. Requires the MANAGE_FILE_IMPORTANT_LINKS permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the files-and-links entry.
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_filesAndLinks_id
      tags:
        - files & links
      summary: Get files-and-links entry
      description: |
        Returns a single files-and-links entry by id. Used identically by the folder-node, media-attachment and URL endpoints; the returned payload shape depends on which path mounts this operation.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the files-and-links entry.
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The files-and-links entry (shape depends on the mounting path).
              example:
                meta: {}
                content:
                  id: 12
                  title: Wichtige Vertragsdokumente
                  icon: folder
                  parentId: 0
                  createdAt: 1748256000
                  createdBy: 17
                  modifiedAt: 1748256000
                  modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_filesAndLinks_id
      tags:
        - files & links
      summary: Update files-and-links entry
      description: |
        Updates a files-and-links entry (folder node, media attachment metadata, or URL link depending on the mounting path). `createdAt`/`createdBy` are preserved from the original record; `modifiedAt`/`modifiedBy` are refreshed. Requires the MANAGE_FILE_IMPORTANT_LINKS permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the files-and-links entry.
          example: 42
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - title
                - url
              properties:
                id:
                  type: integer
                  description: Unique identifier of the file/link entry.
                title:
                  type: string
                  description: Display title of the link.
                url:
                  type: string
                  description: The stored URL.
                assignedId:
                  type: integer
                  description: Identifier of the object this link is assigned to.
                createdAt:
                  type: integer
                  format: int64
                  description: Creation timestamp (epoch seconds).
                createdBy:
                  type: integer
                  description: Identifier of the employee who created the entry.
                modifiedAt:
                  type: integer
                  format: int64
                  description: Last modification timestamp (epoch seconds).
                modifiedBy:
                  type: integer
                  description: Identifier of the employee who last modified the entry.
            example:
              id: 42
              title: Example title
              url: https://example.com
              assignedId: 1
              createdAt: 1
              createdBy: 1
              modifiedAt: 1
              modifiedBy: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The files-and-links entry (shape depends on the mounting path).
              example:
                meta: {}
                content:
                  id: 12
                  title: Wichtige Vertragsdokumente
                  icon: folder
                  parentId: 0
                  createdAt: 1748256000
                  createdBy: 17
                  modifiedAt: 1748256000
                  modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/filesAndLinksMedia:
    post:
      operationId: post_api_v1_filesAndLinksMedia
      tags:
        - files & links
      summary: Upload a file attachment
      description: |
        Uploads a binary file as a multipart attachment under an existing files-and-links node (`assignedId`). Requires the knowledge base v2 feature, FILES_LINKS_ACTIVATED config, and the MANAGE_FILE_IMPORTANT_LINKS permission. The server stores the original filename, mime type and a generated UUID/filename for retrieval.
      parameters:
        - in: query
          name: title
          required: true
          description: Display title for the uploaded attachment.
          example: Beispiel
          schema:
            type: string
        - in: query
          name: assignedId
          required: true
          description: ID of the files-and-links node the attachment belongs to.
          example: 1
          schema:
            type: integer
        - in: query
          name: file
          required: true
          description: Binary file payload reference for the upload.
          example: Angebot.pdf
          schema:
            type: string
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created media attachment metadata.
              example:
                meta: {}
                content:
                  id: 1
                  title: Angebot Migration M365
                  assignedId: 12
                  filename: a5f3-angebot.pdf
                  originalFilename: Angebot.pdf
                  mimeType: application/pdf
                  extension: pdf
                  uuid: a5f3b2c1-9d11-4e02-8e3a-1f3c8b9a0e21
                  size: 524288
                  createdAt: 1748256000
                  createdBy: 17
                  modifiedAt: 1748256000
                  modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_filesAndLinksMedia
      tags:
        - files & links
      summary: List file attachments
      description: |
        Returns all media attachments for the supplied list configuration (typically filtered by `assignedId`). Each entry carries its stored filename, mime type and upload metadata.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                assignedId:
                  type: integer
                  description: ID of the object whose assigned media entries should be listed
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of media attachments.
              example:
                meta: {}
                content:
                  - id: 1
                    title: Angebot Migration M365
                    assignedId: 12
                    originalFilename: Angebot.pdf
                    mimeType: application/pdf
                    size: 524288
                    createdAt: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/filesAndLinksMedia/{id}:
    delete:
      operationId: delete_api_v1_filesAndLinksMedia_id
      tags:
        - files & links
      summary: Delete files-and-links entry
      description: |
        Deletes the files-and-links entry with the given id. For folder nodes (mounted under `/filesAndLinks/{id}`) this cascades into all child nodes, attached media files, attached URLs and removes the id from every user's favorites preference. Media and URL endpoints simply delete the row. Requires the MANAGE_FILE_IMPORTANT_LINKS permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the files-and-links entry.
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_filesAndLinksMedia_id
      tags:
        - files & links
      summary: Get files-and-links entry
      description: |
        Returns a single files-and-links entry by id. Used identically by the folder-node, media-attachment and URL endpoints; the returned payload shape depends on which path mounts this operation.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the files-and-links entry.
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The files-and-links entry (shape depends on the mounting path).
              example:
                meta: {}
                content:
                  id: 12
                  title: Wichtige Vertragsdokumente
                  icon: folder
                  parentId: 0
                  createdAt: 1748256000
                  createdBy: 17
                  modifiedAt: 1748256000
                  modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_filesAndLinksMedia_id
      tags:
        - files & links
      summary: Update files-and-links entry
      description: |
        Updates a files-and-links entry (folder node, media attachment metadata, or URL link depending on the mounting path). `createdAt`/`createdBy` are preserved from the original record; `modifiedAt`/`modifiedBy` are refreshed. Requires the MANAGE_FILE_IMPORTANT_LINKS permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the files-and-links entry.
          example: 42
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - title
                - url
              properties:
                id:
                  type: integer
                  description: Unique identifier of the file/link entry.
                title:
                  type: string
                  description: Display title of the link.
                url:
                  type: string
                  description: The stored URL.
                assignedId:
                  type: integer
                  description: Identifier of the object this link is assigned to.
                createdAt:
                  type: integer
                  format: int64
                  description: Creation timestamp (epoch seconds).
                createdBy:
                  type: integer
                  description: Identifier of the employee who created the entry.
                modifiedAt:
                  type: integer
                  format: int64
                  description: Last modification timestamp (epoch seconds).
                modifiedBy:
                  type: integer
                  description: Identifier of the employee who last modified the entry.
            example:
              id: 42
              title: Example title
              url: https://example.com
              assignedId: 1
              createdAt: 1
              createdBy: 1
              modifiedAt: 1
              modifiedBy: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The files-and-links entry (shape depends on the mounting path).
              example:
                meta: {}
                content:
                  id: 12
                  title: Wichtige Vertragsdokumente
                  icon: folder
                  parentId: 0
                  createdAt: 1748256000
                  createdBy: 17
                  modifiedAt: 1748256000
                  modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/filesAndLinksMedia/{id}/file:
    get:
      operationId: get_api_v1_filesAndLinksMedia_id_file
      tags:
        - files & links
      summary: Get download link for a file attachment
      description: |
        Returns a short-lived file-pass link for downloading the binary content of the media attachment with the given id. Used by the frontend to render preview / download buttons without exposing the underlying file path.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the media attachment to download.
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: File-pass link to download the attached binary.
              example:
                meta: {}
                content:
                  fileKey: a5f3b2c1-9d11-4e02-8e3a-1f3c8b9a0e21
                  url: /api/v1/util/files/a5f3b2c1-9d11-4e02-8e3a-1f3c8b9a0e21
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/filesAndLinksUrl:
    post:
      operationId: post_api_v1_filesAndLinksUrl
      tags:
        - files & links
      summary: Create URL link
      description: |
        Stores an external URL link under an existing files-and-links node (`assignedId`). Used for portal links, documentation references, etc. Requires the knowledge base v2 feature, FILES_LINKS_ACTIVATED config and the MANAGE_FILE_IMPORTANT_LINKS permission.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - url
              properties:
                id:
                  type: integer
                  description: Unique identifier of the file/link entry.
                title:
                  type: string
                  description: Display title of the link.
                url:
                  type: string
                  description: The stored URL.
                assignedId:
                  type: integer
                  description: Identifier of the object this link is assigned to.
                createdAt:
                  type: integer
                  format: int64
                  description: Creation timestamp (epoch seconds).
                createdBy:
                  type: integer
                  description: Identifier of the employee who created the entry.
                modifiedAt:
                  type: integer
                  format: int64
                  description: Last modification timestamp (epoch seconds).
                modifiedBy:
                  type: integer
                  description: Identifier of the employee who last modified the entry.
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created URL link.
              example:
                meta: {}
                content:
                  id: 7
                  title: Kundenportal
                  url: https://kunde.example/portal
                  assignedId: 12
                  createdAt: 1748256000
                  createdBy: 17
                  modifiedAt: 1748256000
                  modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_filesAndLinksUrl
      tags:
        - files & links
      summary: List URL links
      description: |
        Returns all external URL links matching the list configuration (typically filtered by `assignedId`).
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - assignedId
              properties:
                assignedId:
                  type: integer
                  description: Identifier of the object whose assigned links should be listed.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of URL links.
              example:
                meta: {}
                content:
                  - id: 7
                    title: Kundenportal
                    url: https://kunde.example/portal
                    assignedId: 12
                    createdAt: 1748256000
                    createdBy: 17
                    modifiedAt: 1748256000
                    modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/filesAndLinksUrl/{id}:
    delete:
      operationId: delete_api_v1_filesAndLinksUrl_id
      tags:
        - files & links
      summary: Delete files-and-links entry
      description: |
        Deletes the files-and-links entry with the given id. For folder nodes (mounted under `/filesAndLinks/{id}`) this cascades into all child nodes, attached media files, attached URLs and removes the id from every user's favorites preference. Media and URL endpoints simply delete the row. Requires the MANAGE_FILE_IMPORTANT_LINKS permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the files-and-links entry.
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_filesAndLinksUrl_id
      tags:
        - files & links
      summary: Get files-and-links entry
      description: |
        Returns a single files-and-links entry by id. Used identically by the folder-node, media-attachment and URL endpoints; the returned payload shape depends on which path mounts this operation.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the files-and-links entry.
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The files-and-links entry (shape depends on the mounting path).
              example:
                meta: {}
                content:
                  id: 12
                  title: Wichtige Vertragsdokumente
                  icon: folder
                  parentId: 0
                  createdAt: 1748256000
                  createdBy: 17
                  modifiedAt: 1748256000
                  modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_filesAndLinksUrl_id
      tags:
        - files & links
      summary: Update files-and-links entry
      description: |
        Updates a files-and-links entry (folder node, media attachment metadata, or URL link depending on the mounting path). `createdAt`/`createdBy` are preserved from the original record; `modifiedAt`/`modifiedBy` are refreshed. Requires the MANAGE_FILE_IMPORTANT_LINKS permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the files-and-links entry.
          example: 42
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - title
                - url
              properties:
                id:
                  type: integer
                  description: Unique identifier of the file/link entry.
                title:
                  type: string
                  description: Display title of the link.
                url:
                  type: string
                  description: The stored URL.
                assignedId:
                  type: integer
                  description: Identifier of the object this link is assigned to.
                createdAt:
                  type: integer
                  format: int64
                  description: Creation timestamp (epoch seconds).
                createdBy:
                  type: integer
                  description: Identifier of the employee who created the entry.
                modifiedAt:
                  type: integer
                  format: int64
                  description: Last modification timestamp (epoch seconds).
                modifiedBy:
                  type: integer
                  description: Identifier of the employee who last modified the entry.
            example:
              id: 42
              title: Example title
              url: https://example.com
              assignedId: 1
              createdAt: 1
              createdBy: 1
              modifiedAt: 1
              modifiedBy: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The files-and-links entry (shape depends on the mounting path).
              example:
                meta: {}
                content:
                  id: 12
                  title: Wichtige Vertragsdokumente
                  icon: folder
                  parentId: 0
                  createdAt: 1748256000
                  createdBy: 17
                  modifiedAt: 1748256000
                  modifiedBy: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/genericAssignments/for/{sourceType}/{sourceId}:
    get:
      operationId: get_api_v1_genericAssignments_for_sourceType_sourceId
      tags:
        - assignments
      summary: Get visibility assignments for a source
      description: |-
        Convenience wrapper around the typed variant that hard-codes `assignmentType=VISIBILITY` — i.e. it returns who is allowed to
        see the given `sourceType`/`sourceId` (employees/departments listed as visibility targets). Set `withInverted=true` to also
        include inverted assignments. Requires technician/freelancer with access to the source entity.
      parameters:
        - in: path
          name: sourceType
          required: true
          description: Type of the source entity (e.g. TICKET).
          example: TICKET
          schema:
            type: string
        - in: path
          name: sourceId
          required: true
          description: ID of the source entity.
          example: 4711
          schema:
            type: integer
        - in: query
          name: withInverted
          required: false
          description: If true, also include inverted assignments.
          example: true
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Visibility assignments for the source.
              example:
                meta: {}
                content:
                  - id: 1
                    sourceType: TICKET
                    sourceId: 4711
                    targetType: DEVICE
                    targetId: 100
                    type: AFFECTS
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_genericAssignments_for_sourceType_sourceId
      tags:
        - assignments
      summary: Replace visibility assignments for a source
      description: |-
        Convenience wrapper that hard-codes `assignmentType=VISIBILITY`: replaces the full visibility list for the given
        `sourceType`/`sourceId` with the body's array (items not in the body are removed). Requires technician/freelancer plus
        source-entity access and per-target access for every assignment.
      parameters:
        - in: path
          name: sourceType
          required: true
          description: Type of the source entity (e.g. TICKET).
          example: TICKET
          schema:
            type: string
        - in: path
          name: sourceId
          required: true
          description: ID of the source entity.
          example: 4711
          schema:
            type: integer
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - text: Example content
                extras: {}
                linkedEntities: {}
                assignments:
                  infos: {}
                properties:
                  fields: {}
                  extras: {}
                  permissions: {}
                  editable: false
                  message: Example content
                pagination:
                  itemsPerPage: 1
                  totalItems: 1
                  page: 1
                listProperties: {}
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Persisted visibility assignments after the replace.
              example:
                meta: {}
                content:
                  - id: 1
                    sourceType: TICKET
                    sourceId: 4711
                    targetType: DEVICE
                    targetId: 100
                    type: AFFECTS
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/genericAssignments/for/{sourceType}/{sourceId}/{assignmentType}:
    get:
      operationId: get_api_v1_genericAssignments_for_sourceType_sourceId_assignmentType
      tags:
        - assignments
      summary: Get generic assignments for a source (by type)
      description: |-
        Returns all generic assignments where the given `sourceType`/`sourceId` is the source — filtered by the requested
        `assignmentType` (e.g. `VISIBILITY`, `AFFECTS`). With `withInverted=true` the result also contains assignments where the
        same entity is the target instead, useful for showing both sides of bidirectional links. Requires the caller to be a
        technician or freelancer and to have access to the source entity (delegated to the matching source strategy).
      parameters:
        - in: path
          name: sourceType
          required: true
          description: Type of the source entity (e.g. TICKET).
          example: TICKET
          schema:
            type: string
        - in: path
          name: sourceId
          required: true
          description: ID of the source entity.
          example: 4711
          schema:
            type: integer
        - in: path
          name: assignmentType
          required: true
          description: Generic assignment type to filter by (e.g. VISIBILITY, AFFECTS).
          example: VISIBILITY
          schema:
            type: string
        - in: query
          name: withInverted
          required: false
          description: If true, also include assignments where the entity is the target.
          example: true
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of generic assignments for the source, of the requested type.
              example:
                meta: {}
                content:
                  - id: 1
                    sourceType: TICKET
                    sourceId: 4711
                    targetType: DEVICE
                    targetId: 100
                    type: AFFECTS
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_genericAssignments_for_sourceType_sourceId_assignmentType
      tags:
        - assignments
      summary: Replace generic assignments for a source (by type)
      description: |-
        Replaces the full set of generic assignments of the given `assignmentType` for `sourceType`/`sourceId` with the body's array —
        this is a "set" operation, not an append: assignments not contained in the body are deleted. Requires technician/freelancer
        plus access to the source entity (and per-target access to every assigned entity). The returned list is the persisted,
        output-prepared set after the update.
      parameters:
        - in: path
          name: sourceType
          required: true
          description: Type of the source entity (e.g. TICKET).
          example: TICKET
          schema:
            type: string
        - in: path
          name: sourceId
          required: true
          description: ID of the source entity.
          example: 4711
          schema:
            type: integer
        - in: path
          name: assignmentType
          required: true
          description: Generic assignment type to set (e.g. VISIBILITY, AFFECTS).
          example: VISIBILITY
          schema:
            type: string
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - text: Example content
                extras: {}
                linkedEntities: {}
                assignments:
                  infos: {}
                properties:
                  fields: {}
                  extras: {}
                  permissions: {}
                  editable: false
                  message: Example content
                pagination:
                  itemsPerPage: 1
                  totalItems: 1
                  page: 1
                listProperties: {}
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Persisted set of generic assignments after the replace.
              example:
                meta: {}
                content:
                  - id: 1
                    sourceType: TICKET
                    sourceId: 4711
                    targetType: DEVICE
                    targetId: 100
                    type: AFFECTS
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/genericAssignments/properties/{sourceType}:
    get:
      operationId: get_api_v1_genericAssignments_properties_sourceType
      tags:
        - assignments
      summary: Get assignable target properties for a source type
      description: |-
        Returns a map keyed by object describing, for the given `sourceType`, which target link types can be assigned and what
        their field properties look like — used by the generic-assignment editor in the UI to render the correct pickers and field
        constraints. No body, no path-level entity check (the map only describes metadata).
      parameters:
        - in: path
          name: sourceType
          required: true
          description: Type of the source entity (e.g. TICKET).
          example: TICKET
          schema:
            type: string
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Map keyed by object with property fields for each assignable target type.
              example:
                meta: {}
                content:
                  id: 1
                  sourceType: TICKET
                  sourceId: 4711
                  targetType: DEVICE
                  targetId: 100
                  type: AFFECTS
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/geocodes:
    post:
      operationId: post_api_v1_geocodes
      tags:
        - company - master data
      summary: Create geocode rule
      description: |
        Stores a geocode (longitude/latitude, accuracy, status) for an assignment — either an employee (`linkTypeId = 3`) or a company (`linkTypeId = 2`). The caller must be a technician or freelancer. If no `linkTypeId`/`linkId` is supplied, the geocode is attached to the currently logged-in user. For company geocodes, the caller additionally needs company access plus one of `CHANGE_COMPANY_ADDRESS`, `MANAGE_COMPANIES` or `COMPANY_MANAGEMENT_FAST_CARE`; for employee geocodes the user may only set their own coordinates. The `date` field is server-controlled and ignored on input.
      requestBody:
        description: Geocode payload bound to a entity.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                linkTypeId:
                  type: integer
                  description: 2 = company, 3 = employee. If omitted/0, defaults to the calling user.
                linkId:
                  type: integer
                  description: ID of the company or employee.
                longitude:
                  type: number
                  format: double
                latitude:
                  type: number
                  format: double
                accuracy:
                  type: integer
                statusCode:
                  type: integer
                companyId:
                  type: integer
            example:
              linkTypeId: 2
              linkId: 100023
              longitude: 13.38886
              latitude: 52.517037
              accuracy: 1
              statusCode: 1
              companyId: 100023
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: The persisted entity.
              example:
                meta: {}
                content:
                  linkTypeId: 2
                  linkId: 100023
                  longitude: 13.38886
                  latitude: 52.517037
                  accuracy: 1
                  statusCode: 1
                  date: 1748256000
                  companyId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/git/commits:
    post:
      operationId: post_api_v1_git_commits
      tags:
        - git
      summary: Record a git commit
      description: |
        Records a git commit entry — used to link commits to tickets. The current server time (`date`) and the caller's user id (`employeeId`) are set automatically, so those fields in the request body are ignored. Requires the `gitCommits` feature of the `TICKET` module and a technician/freelancer role.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the commit record.
                hash:
                  type: string
                  description: Commit hash.
                project:
                  type: string
                  description: Name of the project the commit belongs to.
                branch:
                  type: string
                  description: Branch the commit was made on.
                message:
                  type: string
                  description: Commit message.
                author:
                  type: string
                  description: Author of the commit.
                employeeId:
                  type: integer
                  description: Identifier of the employee linked to the commit.
                date:
                  type: integer
                  format: int64
                  description: Commit timestamp (epoch seconds).
                ticketId:
                  type: integer
                  description: Identifier of the ticket the commit is linked to.
                pinned:
                  type: boolean
                  description: Whether the commit is pinned in the ticket history.
            example:
              id: 42
              hash: a1b2c3d4e5f6
              project: string
              branch: string
              message: Example content
              author: string
              employeeId: 1
              date: 1748256000
              ticketId: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The newly created object row.
              example:
                meta: {}
                content:
                  hash: a1b2c3d
                  message: 'fix: ticket counter'
                  author: max.mustermann
                  date: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/git/commits/ticket/{ticketId}:
    get:
      operationId: get_api_v1_git_commits_ticket_ticketId
      tags:
        - git
      summary: List git commits linked to a ticket
      description: |
        Returns every recorded git commit linked to the given ticket. Before loading, it is confirmed that the ticket exists and that the caller has access to it, so commits are never leaked to users who cannot see the ticket itself. Each commit is enriched with linked-entity infos (e.g. resolved employee names) before being returned.
      parameters:
        - in: path
          name: ticketId
          required: true
          description: Id of the ticket whose linked git commits should be returned.
          example: 4711
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of records linked to the ticket.
              example:
                meta: {}
                content:
                  - hash: a1b2c3d
                    message: 'fix: ticket counter'
                    author: max.mustermann
                    date: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/guarantee:
    put:
      operationId: put_api_v1_guarantee
      tags:
        - device management
      summary: Load portal guarantee list
      description: |
        Returns the guarantee/warranty list used by the customer portal. Filters by company, link type (PC / server / periphery / component), and configurable "expired since" / "expires in" day windows. Requires the DEVICEMANAGEMENT or LICENSE_MANAGEMENT module; portal config overrides come from user preferences and TANSS config values.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyIds:
                  type: array
                  description: Identifiers of the companies to filter guarantee data for.
                  items:
                    type: object
                linkTypes:
                  type: array
                  description: Device link types to include.
                  items:
                    type: object
                peripheryTypeId:
                  type: integer
                  description: Identifier of the periphery type to filter by.
                componentTypeId:
                  type: integer
                  description: Identifier of the component type to filter by.
                expiredSinceDays:
                  type: integer
                  description: Number of days a guarantee has been expired within which to include entries.
                expiresInDays:
                  type: integer
                  description: Number of upcoming days within which an expiring guarantee should be included.
                fetchGuarantee:
                  type: boolean
                  description: Whether guarantee information should be fetched.
                fetchWarranty:
                  type: boolean
                  description: Whether warranty information should be fetched.
                usePortalValues:
                  type: boolean
                  description: Whether portal-level values should be applied to the query.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of guarantee/warranty entries matching the filters.
              example:
                meta: {}
                content:
                  - id: 1
                    linkTypeId: 1
                    linkId: 4711
                    companyId: 100023
                    guaranteeExpire: 1779792000
                    warrantyExpire: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/holidays:
    get:
      operationId: get_api_v1_holidays
      tags:
        - holidays
      summary: Get holidays
      description: |
        Returns every stored holiday entry (recurring entries have `year: 0`, year-specific entries carry the actual year). Read access requires the caller to be a user from the own company; no extra permission is needed for view.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        day:
                          type: integer
                          example: 1
                        month:
                          type: integer
                          example: 5
                        year:
                          type: integer
                          example: 0
                        description:
                          type: string
                          example: Tag der Arbeit
                        factor:
                          type: number
                          example: 1
                        type:
                          type: string
                          example: ALL_DAY
              example:
                meta: {}
                content:
                  - day: 1
                    month: 5
                    year: 0
                    description: Tag der Arbeit
                    factor: 1
                    type: ALL_DAY
                  - day: 18
                    month: 4
                    year: 2025
                    description: Karfreitag
                    factor: 1
                    type: ALL_DAY
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_holidays
      tags:
        - holidays
      summary: Create holiday
      description: |
        Creates a new holiday entry. The controller rejects the request if a holiday for the same day/month/year combination already exists. Requires the caller to be a user from the own company with `MANAGE_HOLIDAYS`; the description is trimmed and capped at 40 characters before persisting.
      requestBody:
        description: An object.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - day
                - month
                - year
              properties:
                day:
                  type: integer
                  description: Day of month of the holiday.
                month:
                  type: integer
                  description: Month of the holiday.
                year:
                  type: integer
                  description: Year of the holiday, or 0 for a recurring fixed holiday.
                factor:
                  type: number
                  description: Weighting factor applied for the holiday.
                description:
                  type: string
                  description: Name or description of the holiday.
                type:
                  type: string
                  description: Portion of the day the holiday covers.
                  enum:
                    - ALL_DAY
                    - FORENOON
                    - AFTERNOON
                dayTimestamp:
                  type: integer
                  format: int64
                  description: Timestamp representing the holiday date (epoch seconds).
            example:
              day: 18
              month: 4
              year: 2025
              description: Karfreitag
              factor: 1
              type: ALL_DAY
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      day:
                        type: integer
                        example: 18
                      month:
                        type: integer
                        example: 4
                      year:
                        type: integer
                        example: 2025
                      description:
                        type: string
                        example: Karfreitag
                      factor:
                        type: number
                        example: 1
                      type:
                        type: string
                        example: ALL_DAY
              example:
                meta: {}
                content:
                  day: 18
                  month: 4
                  year: 2025
                  description: Karfreitag
                  factor: 1
                  type: ALL_DAY
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/holidays/updates:
    post:
      operationId: post_api_v1_holidays_updates
      tags:
        - holidays
      summary: Bulk-create holiday entries
      description: |
        Bulk-imports a list of holiday entries — typically the result of one of the `updates/{year}` lookups, after the user has confirmed which entries to take over. Each entry runs through the standard create pipeline (description trim/length check, day/month validation). Requires a user from the own company with `MANAGE_HOLIDAYS`.
      requestBody:
        description: Array of objects to persist.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - day: 1
                month: 1
                year: 2025
                description: Neujahr
                factor: 1
                type: ALL_DAY
              - day: 18
                month: 4
                year: 2025
                description: Karfreitag
                factor: 1
                type: ALL_DAY
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        day:
                          type: integer
                          example: 1
                        month:
                          type: integer
                          example: 1
                        year:
                          type: integer
                          example: 2025
                        description:
                          type: string
                          example: Neujahr
                        factor:
                          type: number
                          example: 1
                        type:
                          type: string
                          example: ALL_DAY
              example:
                meta: {}
                content:
                  - day: 1
                    month: 1
                    year: 2025
                    description: Neujahr
                    factor: 1
                    type: ALL_DAY
                  - day: 18
                    month: 4
                    year: 2025
                    description: Karfreitag
                    factor: 1
                    type: ALL_DAY
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/holidays/updates/{year}:
    get:
      operationId: get_api_v1_holidays_updates_year
      tags:
        - holidays
      summary: Compute public holidays for year (nationwide)
      description: |
        Returns the canonical list of German public holidays for a given year without any federal-state filter (state defaults to `NONE`). Used by the admin UI to pre-fill the holiday import. Each entry tells whether the date is fixed (always same day/month) or movable (Easter-derived). Requires a user from the own company with `MANAGE_HOLIDAYS`.
      parameters:
        - in: path
          name: year
          required: true
          description: Year for which the public holidays should be computed.
          schema:
            type: integer
          example: 2025
      responses:
        '200':
          description: Public holidays computed for the requested year.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        holiday:
                          type: string
                          example: GOOD_FRIDAY
                        name:
                          type: string
                          example: Karfreitag
                        date:
                          type: string
                          format: date
                          example: '2025-04-18'
                        fixed:
                          type: boolean
                          example: false
                        states:
                          type: array
                          items:
                            type: string
                          example: []
              example:
                meta: {}
                content:
                  - holiday: NEW_YEAR
                    name: Neujahr
                    date: '2025-01-01'
                    fixed: true
                    states: []
                  - holiday: GOOD_FRIDAY
                    name: Karfreitag
                    date: '2025-04-18'
                    fixed: false
                    states: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/holidays/updates/{year}/{state}:
    get:
      operationId: get_api_v1_holidays_updates_year_state
      tags:
        - holidays
      summary: Compute public holidays for year + federal state
      description: |
        Returns the canonical list of German public holidays for a given year, restricted to those that apply in a specific federal state (`state` is a value from object, e.g. `BY`, `BW`, `NW`). Each entry indicates whether the holiday has a fixed date or is movable (Easter-derived). Requires a user from the own company with `MANAGE_HOLIDAYS`.
      parameters:
        - in: path
          name: year
          required: true
          description: Year for which the public holidays should be computed.
          schema:
            type: integer
          example: 2025
        - in: path
          name: state
          required: true
          description: German federal state code to filter the holidays (e.g. BY, BW, NW).
          schema:
            type: string
          example: BY
      responses:
        '200':
          description: Public holidays for the requested year and state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        holiday:
                          type: string
                          example: GOOD_FRIDAY
                        name:
                          type: string
                          example: Karfreitag
                        date:
                          type: string
                          format: date
                          example: '2025-04-18'
                        fixed:
                          type: boolean
                          example: false
                        states:
                          type: array
                          items:
                            type: string
                          example: []
              example:
                meta: {}
                content:
                  - holiday: NEW_YEAR
                    name: Neujahr
                    date: '2025-01-01'
                    fixed: true
                    states: []
                  - holiday: GOOD_FRIDAY
                    name: Karfreitag
                    date: '2025-04-18'
                    fixed: false
                    states: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/holidays/{year}/{month}/{day}:
    delete:
      operationId: delete_api_v1_holidays_year_month_day
      tags:
        - holidays
      summary: Delete holiday
      description: |
        Removes the holiday entry identified by the composite key `(day, month, year)`. Pass `year = 0` to delete a recurring entry. Requires a user from the own company with `MANAGE_HOLIDAYS`.
      parameters:
        - in: path
          name: year
          required: true
          description: Year part of the holiday key (use 0 for a recurring entry).
          schema:
            type: integer
          example: 2025
        - in: path
          name: month
          required: true
          description: Month part of the holiday key (1-12).
          schema:
            type: integer
          example: 5
        - in: path
          name: day
          required: true
          description: Day part of the holiday key (1-31).
          schema:
            type: integer
          example: 26
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_holidays_year_month_day
      tags:
        - holidays
      summary: Get holiday by date
      description: |
        Loads a single holiday entry identified by the composite key `(day, month, year)`. Pass `year = 0` for recurring entries. Returns 404 if nothing is found. Requires the caller to be a user from the own company; no extra permission for read.
      parameters:
        - in: path
          name: year
          required: true
          description: Year part of the holiday key (use 0 for a recurring entry).
          schema:
            type: integer
          example: 2025
        - in: path
          name: month
          required: true
          description: Month part of the holiday key (1-12).
          schema:
            type: integer
          example: 5
        - in: path
          name: day
          required: true
          description: Day part of the holiday key (1-31).
          schema:
            type: integer
          example: 26
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      day:
                        type: integer
                        example: 18
                      month:
                        type: integer
                        example: 4
                      year:
                        type: integer
                        example: 2025
                      description:
                        type: string
                        example: Karfreitag
                      factor:
                        type: number
                        example: 1
                      type:
                        type: string
                        example: ALL_DAY
              example:
                meta: {}
                content:
                  day: 18
                  month: 4
                  year: 2025
                  description: Karfreitag
                  factor: 1
                  type: ALL_DAY
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_holidays_year_month_day
      tags:
        - holidays
      summary: Update holiday
      description: |
        Updates the holiday entry identified by the composite key `(day, month, year)`; the request body carries the new field values. Requires a user from the own company with `MANAGE_HOLIDAYS`; description trimming and validation rules from create also apply.
      parameters:
        - in: path
          name: year
          required: true
          description: Year part of the holiday key (use 0 for a recurring entry).
          schema:
            type: integer
          example: 2025
        - in: path
          name: month
          required: true
          description: Month part of the holiday key (1-12).
          schema:
            type: integer
          example: 5
        - in: path
          name: day
          required: true
          description: Day part of the holiday key (1-31).
          schema:
            type: integer
          example: 26
      requestBody:
        description: An object with the updated values.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - day
                - month
                - year
              properties:
                day:
                  type: integer
                  description: Day of month of the holiday.
                month:
                  type: integer
                  description: Month of the holiday.
                year:
                  type: integer
                  description: Year of the holiday, or 0 for a recurring fixed holiday.
                factor:
                  type: number
                  description: Weighting factor applied for the holiday.
                description:
                  type: string
                  description: Name or description of the holiday.
                type:
                  type: string
                  description: Portion of the day the holiday covers.
                  enum:
                    - ALL_DAY
                    - FORENOON
                    - AFTERNOON
                dayTimestamp:
                  type: integer
                  format: int64
                  description: Timestamp representing the holiday date (epoch seconds).
            example:
              day: 18
              month: 4
              year: 2025
              description: Karfreitag
              factor: 1.5
              type: ALL_DAY
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      day:
                        type: integer
                        example: 18
                      month:
                        type: integer
                        example: 4
                      year:
                        type: integer
                        example: 2025
                      description:
                        type: string
                        example: Karfreitag
                      factor:
                        type: number
                        example: 1.5
                      type:
                        type: string
                        example: ALL_DAY
              example:
                meta: {}
                content:
                  day: 18
                  month: 4
                  year: 2025
                  description: Karfreitag
                  factor: 1.5
                  type: ALL_DAY
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ical/config:
    get:
      operationId: get_api_v1_ical_config
      tags:
        - ical
      summary: List iCal feed configurations
      description: |
        Returns all stored iCal feed configurations. A configuration controls what an external calendar client receives when it subscribes to the `/api/v1/ical/fetch/{configurationId}` URL — typically the set of employees and planning types to include. Managing configurations is an admin task.
      responses:
        '200':
          description: List of stored iCal feed configurations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 1
                    name: Team Berlin
                    employeeIds:
                      - 5
                      - 6
                      - 7
                    planningTypes:
                      - APPOINTMENT_FIX
                      - APPOINTMENT_PROPOSAL
                  - id: 2
                    name: Privater Kalender Max
                    employeeIds:
                      - 5
                    planningTypes:
                      - APPOINTMENT_PRIVATE
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_ical_config
      tags:
        - ical
      summary: Create an iCal feed configuration
      description: |
        Creates a new iCal feed configuration. The configuration's `password` (used by external calendar clients via HTTP Basic Auth on the fetch endpoint) is bcrypt-hashed before persistence. Once stored, subscribing to `/api/v1/ical/fetch/{configurationId}` will return the calendar entries defined by the configuration's filters.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              profileId: 1
              configName:
                title: Example title
                description: Example content
                mandatory: false
              configValue: string
      responses:
        '201':
          description: Created iCal configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 3
                  name: Team Berlin
                  employeeIds:
                    - 5
                    - 6
                    - 7
                  planningTypes:
                    - APPOINTMENT_FIX
                    - APPOINTMENT_PROPOSAL
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ical/config/{id}:
    delete:
      operationId: delete_api_v1_ical_config_id
      tags:
        - ical
      summary: Delete an iCal feed configuration
      description: |
        Removes an iCal feed configuration by id. Existing calendar subscribers using that configuration id will subsequently receive an error response on `/api/v1/ical/fetch/{configurationId}`, so this effectively revokes the external feed.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the iCal feed configuration.
          example: '1'
          schema:
            type: string
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_ical_config_id
      tags:
        - ical
      summary: Get a single iCal feed configuration
      description: |
        Returns the stored iCal feed configuration identified by `id` (filters such as included employees and planning types). The bcrypt-hashed password used by calendar clients is not exposed in plain text.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the iCal feed configuration.
          example: '1'
          schema:
            type: string
      responses:
        '200':
          description: iCal configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  name: Team Berlin
                  employeeIds:
                    - 5
                    - 6
                    - 7
                  planningTypes:
                    - APPOINTMENT_FIX
                    - APPOINTMENT_PROPOSAL
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_ical_config_id
      tags:
        - ical
      summary: Update an iCal feed configuration
      description: |
        Updates an existing iCal feed configuration. If the body carries a new `password`, it is bcrypt-hashed before being persisted; the `id` in the body is ignored in favour of the path parameter.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the iCal feed configuration.
          example: '1'
          schema:
            type: string
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              profileId: 1
              configName:
                title: Example title
                description: Example content
                mandatory: false
              configValue: string
      responses:
        '200':
          description: Updated iCal configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  name: Team Berlin (updated)
                  employeeIds:
                    - 5
                    - 6
                  planningTypes:
                    - APPOINTMENT_FIX
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ical/fetch/{configurationId}:
    get:
      operationId: get_api_v1_ical_fetch_configurationId
      tags:
        - ical
      summary: Fetch iCal feed for a configuration
      description: |
        Returns a `text/calendar` (iCalendar) feed for the given configuration so external calendar clients (Outlook, Google Calendar, Apple Calendar, Thunderbird) can subscribe to a technician's planned supports and appointments. Unlike the rest of the API this route uses HTTP Basic Auth (calendar clients cannot carry JWTs), and the configuration controls which employees and planning types are exported. If the configuration was deleted or has no body, a sensible default scoped to the logged-in user is returned.
      parameters:
        - in: path
          name: configurationId
          required: true
          description: Id of the iCal feed configuration to export.
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: iCalendar feed body.
          content:
            text/calendar:
              schema:
                type: string
              example: |
                BEGIN:VCALENDAR
                VERSION:2.0
                PRODID:-//TANSS//iCal Export//EN
                CALSCALE:GREGORIAN
                METHOD:PUBLISH
                BEGIN:VEVENT
                UID:tanss-support-4711@tanss
                DTSTAMP:20250526T080000Z
                DTSTART:20250526T080000Z
                DTEND:20250526T093000Z
                SUMMARY:Server-Migration Kunde XY
                DESCRIPTION:Geplanter Support fuer Ticket #4711
                LOCATION:Berlin, Kunde XY
                END:VEVENT
                BEGIN:VEVENT
                UID:tanss-appointment-815@tanss
                DTSTAMP:20250526T080000Z
                DTSTART:20250527T130000Z
                DTEND:20250527T140000Z
                SUMMARY:Telefontermin ACME GmbH
                END:VEVENT
                END:VCALENDAR
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/jwts/{ext_program}:
    get:
      operationId: get_api_v1_jwts_ext_program
      tags:
        - util routes
      summary: Create JWT for external program
      description: |
        Mints a JWT that lets an external program (e.g. remote-support agent, mobile app, integration bot)
        authenticate against this API. The token's lifetime is `duration` (milliseconds, default 1 year), the
        `info` parameter is stored in the token log so the issued token can be tracked / revoked, and
        `isForTesting=true` skips that log entry. For `REMOTE_SUPPORT` programs, `info` must be a numeric type
        code &ge; 1000.

        Requires the `CREATE_JWT_TOKENS_FOR_EXTERNAL_PROGRAMMS` permission. The external program must also be
        licensed (`isExternalProgramConfigured`).
      parameters:
        - in: path
          name: ext_program
          required: true
          description: Identifier of the external program the JWT is minted for.
          schema:
            type: string
          example: REMOTE_SUPPORT
        - in: query
          name: duration
          required: false
          description: Token lifetime in milliseconds (defaults to one year).
          schema:
            type: integer
            format: int64
            default: 31536000000
          example: 31536000000
        - in: query
          name: info
          required: false
          description: Free-text or type-code info stored in the token log for tracking.
          schema:
            type: string
            default: ''
          example: mobile-app-v3
        - in: query
          name: isForTesting
          required: false
          description: When true, skips creating the token-log entry.
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Map with the minted JWT under the `apiToken` key.
              example:
                meta: {}
                content:
                  apiToken: eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJyZW1vdGVfc3VwcG9ydCJ9.signature
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/knowledgeBase/articles/{id}:
    get:
      operationId: get_api_v1_knowledgeBase_articles_id
      tags:
        - knowledge base
      summary: Get a knowledge-base article
      description: |
        Returns a single customer-facing knowledge-base article by id. A per-entity access check is enforced — customers only see articles their company is allowed to browse. Used by the customer-facing KB browser to render the selected article.
      parameters:
        - in: path
          name: id
          description: ID of the knowledge-base article.
          required: true
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The requested knowledge-base article.
              example:
                meta: {}
                content:
                  id: 1
                  title: Wie sichere ich Daten?
                  content: ...
                  categoryId: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/knowledgeBase/browser:
    get:
      operationId: get_api_v1_knowledgeBase_browser
      tags:
        - knowledge base
      summary: Get the knowledge-base browser tree
      description: |
        Returns the root object and the standard browser filter set used by the customer-facing KB navigation. The result is the full category/article tree the caller is allowed to see — the basic KB permission check decides whether the caller may use the KB at all, and the browser service applies the per-customer visibility filters before serialisation.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Root object of the browser tree.
              example:
                meta: {}
                content:
                  id: 1
                  title: Wie sichere ich Daten?
                  content: ...
                  categoryId: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/landingPage/contractWorkflow:
    get:
      operationId: get_api_v1_landingPage_contractWorkflow
      tags:
        - tickets
      summary: Get workflow content
      description: |
        Returns the contract workflow landing page payload for the recipient identified by the workflow contract token currently stored in the request storage. The payload bundles the token, the underlying object, additional workflow info, and the filtered landing-page configuration (texts, layout flags, whether authorizators are required). Used by the public contract landing page rendered for the customer.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object.
              example:
                meta: {}
                content:
                  token:
                    token: a1b2c3d4e5f60718
                    type: AUTHORIZATOR
                    workflowContractId: 7
                  workflowContract:
                    id: 7
                    configId: 12
                    companyId: 134
                    state: OPEN
                  workflowInfos:
                    contractNumber: VTR-2026-0042
                  configuration:
                    LANDINGPAGE_1_HEADER: Bitte bestätigen Sie Ihren Vertrag
                    LANDINGPAGE_1_BUTTON_SEND: Vertrag absenden
                    LANDINGPAGE_1_NO_AUTHORIZATORS_REQUIRED: '0'
                  landingPageSubmitResult: null
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_landingPage_contractWorkflow
      tags:
        - tickets
      summary: Submit workflow content
      description: |
        Submits the customer's response on the contract workflow landing page (company data, approver details, optional list of authorizator employees, accept type). The server validates the workflow token, persists the response, and returns the updated landing page content including a `landingPageSubmitResult` indicating the outcome (e.g. confirmation step or follow-up screen).
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyName:
                  type: string
                  description: Name of the company associated with the contract
                companyAddress:
                  type: string
                  description: Address of the company
                approverFirstName:
                  type: string
                  description: First name of the approving contact person
                approverLastName:
                  type: string
                  description: Last name of the approving contact person
                approverSalutationId:
                  type: integer
                  description: Identifier of the approver's salutation
                approverEmail:
                  type: string
                  description: Email address of the approving contact person
                approverFunction:
                  type: string
                  description: Job function or role of the approver
                employees:
                  type: array
                  description: Authorized employees related to the contract
                  items:
                    type: object
                acceptType:
                  type: string
                  description: Whether the contract was accepted or declined
                  enum:
                    - ACCEPT
                    - DECLINE
            example:
              companyName: Muster GmbH
              companyAddress: Hauptstr. 1, 26123 Oldenburg
              approverFirstName: Erika
              approverLastName: Mustermann
              approverSalutationId: 2
              approverEmail: erika.mustermann@muster.de
              approverFunction: Geschäftsführerin
              acceptType: DIGITAL_SIGNATURE
              employees:
                - firstName: Max
                  lastName: Meier
                  email: max.meier@muster.de
                  type: AUTHORIZATOR
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An updated object reflecting the submission.
              example:
                meta: {}
                content:
                  token:
                    token: a1b2c3d4e5f60718
                    type: AUTHORIZATOR
                    workflowContractId: 7
                  workflowContract:
                    id: 7
                    configId: 12
                    state: SUBMITTED
                  landingPageSubmitResult: SUCCESS
                  configuration:
                    LANDINGPAGE_1_HEADER: Vielen Dank
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/landingPage/contractWorkflow/pdf:
    get:
      operationId: get_api_v1_landingPage_contractWorkflow_pdf
      tags:
        - tickets
      summary: Get workflow pdf
      description: |
        Returns a one-time file-pass handle that lets the recipient of a contract workflow landing page download the contract PDF without an authenticated user session. The caller is identified via the workflow contract token from the current request storage (no JWT user — this is the public landing page side).
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object carrying the temporary file token used to fetch the contract PDF.
              example:
                meta: {}
                content:
                  filePass: f1a2b3c4-d5e6-7890-abcd-ef0123456789
                  fileName: contract-workflow.pdf
                  mimeType: application/pdf
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/landingPage/ticketWorkflow:
    get:
      operationId: get_api_v1_landingPage_ticketWorkflow
      tags:
        - ticket workflows
      summary: Get workflow content
      description: |-
        Returns the form definition the public ticket-workflow landing page should
        render (current step questions, ticket context, allowed inputs). This is the
        initial-load call when an external user opens a workflow link.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Workflow landing-page content (ticket info + form fields).
              example:
                meta: {}
                content:
                  ticketInfos:
                    ticketID: 4711
                    companyName: Beispiel GmbH
                    title: Festplatte defekt
                  currentStep:
                    id: 11
                    name: Bitte Logfile hochladen
                  fields:
                    - name: logfile
                      type: FILE
                      required: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_landingPage_ticketWorkflow
      tags:
        - ticket workflows
      summary: Submit workflow content
      description: |-
        Submits the user's answers for the current workflow step. The service advances
        the workflow state machine and returns the next step's content (or the
        completion content if the workflow is finished).
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                multiSelectId:
                  type: integer
                  description: Identifier of the selected multi-select option for the workflow landing page.
                remark:
                  type: string
                  description: Free-text remark associated with the landing page selection.
                serviceCap:
                  type: number
                  description: Optional service cap value applied to the workflow.
                vars:
                  type: object
                  description: Map of additional key/value variables for the landing page.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Workflow landing-page content (ticket info + form fields).
              example:
                meta: {}
                content:
                  ticketInfos:
                    ticketID: 4711
                    companyName: Beispiel GmbH
                    title: Festplatte defekt
                  currentStep:
                    id: 11
                    name: Bitte Logfile hochladen
                  fields:
                    - name: logfile
                      type: FILE
                      required: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/landingPage/ticketWorkflow/upload:
    post:
      operationId: post_api_v1_landingPage_ticketWorkflow_upload
      tags:
        - ticket workflows
      summary: Upload file
      description: |-
        Uploads files from the public ticket-workflow landing page. The ticket id is
        inferred from the workflow content already stored in the session (no auth
        required — the landing page itself is the access gate). Fails 400 if the
        workflow content has no ticket id.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Upload result (list of stored file names).
              example:
                meta: {}
                content:
                  - id: 1234
                    name: screenshot.png
                    ticketId: 4711
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/log/list/properties:
    get:
      operationId: get_api_v1_log_list_properties
      tags:
        - logging
      summary: Get log-list UI properties
      description: |
        Returns the metadata the audit-log UI needs to render its filters: the employee select field plus one entry per `linkType` for which a backing log file is available. Used to populate the dropdowns on the log viewer before any actual log query is issued.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: object with the employee selector and the available log files.
              example:
                meta: {}
                content:
                  id: 1
                  linkType: TICKET
                  linkId: 4711
                  employeeId: 5
                  action: UPDATE
                  field: statusId
                  oldValue: '1'
                  newValue: '2'
                  date: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/log/list/{linkType}:
    put:
      operationId: put_api_v1_log_list_linkType
      tags:
        - logging
      summary: Query audit log entries for a link type
      description: |
        Returns the audit-log entries for the given `linkType` (e.g. `TICKET`, `ASSET`, ...). The configuration body lets the caller filter by link ids, employees, date range and pagination; access is checked per link type — if the link type is not supported the request is rejected with `NOT_FOUND`. Both database and file-based log sources are included in the result.
      parameters:
        - in: path
          name: linkType
          required: true
          description: Link type whose audit log entries should be queried (e.g. TICKET).
          example: TICKET
          schema:
            type: string
            description: Link type (e.g. TICKET, ASSET).
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: See the matching schema for the field shape.
              properties:
                linkIds:
                  type: array
                  description: Identifiers of linked entities to filter the log list by.
                  items:
                    type: object
                timeframe:
                  type: object
                  description: Time range used to filter log entries by date.
                logFileTypeIds:
                  type: array
                  description: Identifiers of log entry types to include.
                  items:
                    type: object
                employeeIds:
                  type: array
                  description: Identifiers of employees whose log entries to include.
                  items:
                    type: object
                searchText:
                  type: string
                  description: Free-text search term applied to log entries.
                ticketId:
                  type: integer
                  description: Identifier of a ticket to restrict the log list to.
                supportId:
                  type: integer
                  description: Identifier of a support entry to restrict the log list to.
                newestFirst:
                  type: boolean
                  description: Whether to sort results with the newest entries first.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of object entries matching the configuration.
              example:
                meta: {}
                content:
                  - id: 1
                    linkType: TICKET
                    linkId: 4711
                    employeeId: 5
                    action: UPDATE
                    field: statusId
                    oldValue: '1'
                    newValue: '2'
                    date: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/logo/{type}/{id}:
    get:
      operationId: get_api_v1_logo_type_id
      tags:
        - util routes
      summary: Get avatar / logo
      description: |
        Returns the avatar (logo image) stored for the entity (`type`, `id`) pair — e.g. an employee avatar, a
        company logo, etc. The required permissions depend on the logo type.
      parameters:
        - in: path
          name: type
          required: true
          description: Logo type identifying the entity kind (e.g. EMPLOYEE, COMPANY).
          schema:
            type: string
          example: EMPLOYEE
        - in: path
          name: id
          required: true
          description: Id of the entity whose avatar/logo is addressed.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: payload with the image bytes (base64) and mime type.
              example:
                meta: {}
                content:
                  type: EMPLOYEE
                  id: 42
                  mimeType: image/png
                  avatar: iVBORw0KGgoAAAANSUhEUgAA...
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_logo_type_id
      tags:
        - util routes
      summary: Create/update avatar
      description: |
        Uploads an avatar (logo image) for the (`type`, `id`) pair. The image is sent as a multipart `logo` form
        field. Files larger than 2&nbsp;MB are rejected, and only JPG/PNG/GIF MIME types are accepted (other
        types yield `FILE_WRONG_MIME_TYPE`).

        Permission to upload is enforced per type
        (e.g. an employee can upload their own avatar; a company logo requires company-admin permission).
      parameters:
        - in: path
          name: type
          required: true
          description: Logo type identifying the entity kind (e.g. EMPLOYEE, COMPANY).
          schema:
            type: string
          example: EMPLOYEE
        - in: path
          name: id
          required: true
          description: Id of the entity whose avatar/logo is addressed.
          schema:
            type: integer
          example: 42
        - in: query
          name: file
          required: true
          description: The uploaded logo image (multipart form field).
          schema:
            type: string
          example: avatar.png
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The stored payload.
              example:
                meta: {}
                content:
                  type: EMPLOYEE
                  id: 42
                  mimeType: image/png
                  avatar: iVBORw0KGgoAAAANSUhEUgAA...
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails:
    put:
      operationId: put_api_v1_mails
      tags:
        - mails
      summary: Get mail list
      description: Loads a filtered/paginated list of mails based on the supplied object. Used by techs to browse mailbox contents (e.g. unassigned emails) before linking them to tickets.
      requestBody:
        description: An object describing the desired filters, pagination and sorting.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: integer
                  description: Identifier of the company whose mails should be listed
                fetchTicketInfos:
                  type: boolean
                  description: Whether related ticket information should be loaded alongside each mail
                checkPermissions:
                  type: boolean
                  description: Whether access permissions are enforced when listing mails
                sortField:
                  type: string
                  description: Field the mail list is sorted by
                  enum:
                    - ID
                    - DATE
                sortOrder:
                  type: string
                  description: Sort direction of the mail list
                  enum:
                    - ASC
                    - DESC
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of object entries matching the supplied configuration.
              example:
                meta: {}
                content:
                  - id: 1024
                    subject: 'Re: Festplatte defekt'
                    from: kunde@example.com
                    to:
                      - support@example-it.de
                    body: Vielen Dank für Ihre Anfrage...
                    attachments: []
                  - id: 1025
                    subject: Backup Status
                    from: monitoring@example-it.de
                    to:
                      - support@example-it.de
                    body: Backup nightly run finished.
                    attachments: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/identify:
    get:
      operationId: get_api_v1_mails_identify
      tags:
        - mails
      summary: Identify mail
      description: |
        Looks up the company/employee/ticket TANSS associates with a given email address so that an incoming mail can be auto-assigned to the right customer record. Returns `NOT_FOUND` if no match exists.
      parameters:
        - in: query
          name: email
          description: Email address to look up the associated company/employee/ticket for.
          required: true
          schema:
            type: string
          example: kunde@example.com
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object describing the matched company/employee, or `null` when no match exists.
              example:
                meta: {}
                content:
                  email: kunde@example.com
                  companyId: 17
                  companyName: Example GmbH
                  employeeId: 42
                  employeeName: Max Mustermann
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/retry:
    get:
      operationId: get_api_v1_mails_retry
      tags:
        - mails
      summary: Get pending retries
      description: |
        Lists all outgoing mails whose delivery has failed and is queued for another attempt, including their linked entities (ticket, company, sender). Used by the mail-retry administration view.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of pending object entries.
              example:
                meta: {}
                content:
                  - id: 7
                    mailId: 1024
                    subject: 'Re: Festplatte defekt'
                    to:
                      - kunde@example.com
                    lastError: 'smtp: temporary failure'
                    attempts: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/retry/resend/{retryId}:
    get:
      operationId: get_api_v1_mails_retry_resend_retryId
      tags:
        - mails
      summary: Retry sending mail
      description: |
        Re-attempts delivery of a previously failed outgoing mail (identified by its retry id) and reports whether the send succeeded this time. Used from the mail-retry list when a tech manually requests another delivery attempt.
      parameters:
        - in: path
          name: retryId
          description: Id of the failed outgoing mail retry entry to resend.
          required: true
          schema:
            type: integer
          example: 7
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: 'A boolean: `true` when the resend succeeded, `false` when it failed again.'
              example:
                meta: {}
                content: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/retry/{retryId}:
    delete:
      operationId: delete_api_v1_mails_retry_retryId
      tags:
        - mails
      summary: Delete retry mail
      description: |
        Removes a pending mail retry so TANSS will no longer try to deliver that outgoing mail. Used to discard mails the tech has decided not to resend.
      parameters:
        - in: path
          name: retryId
          description: Id of the pending mail retry to delete.
          required: true
          schema:
            type: integer
          example: 7
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/send:
    post:
      operationId: post_api_v1_mails_send
      tags:
        - mails
      summary: Send mail via form
      description: Sends a new outgoing mail composed in the TANSS mail form (subject, body, recipients, attachments, template, ticket link). Used by techs to answer customers from inside a ticket. Returns the resulting send response including any failures that were queued for retry.
      requestBody:
        description: An object describing the mail to send.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: integer
                  description: Identifier of the company the mail relates to
                employeeId:
                  type: integer
                  description: Identifier of the contact person the mail relates to
                reasonId:
                  type: integer
                  description: Identifier of the reason or category assigned to the mail
                subject:
                  type: string
                  description: Subject line of the mail
                plainText:
                  type: string
                  description: Plain text body of the mail
                to:
                  type: string
                  description: Primary recipient address
                cc:
                  type: string
                  description: Carbon copy recipient addresses
                bcc:
                  type: string
                  description: Blind carbon copy recipient addresses
                copyToSelf:
                  type: boolean
                  description: Whether a copy of the mail is sent back to the sender
                mailAttachments:
                  type: array
                  description: List of file attachments included with the mail
                  items:
                    type: object
                createTicket:
                  type: object
                  description: Optional ticket to be created together with the mail
            example:
              subject: 'Re: Festplatte defekt'
              to:
                - kunde@example.com
              cc: []
              bcc: []
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object describing the resulting mail and any queued retries.
              example:
                meta: {}
                content:
                  mailId: 1024
                  subject: 'Re: Festplatte defekt'
                  to:
                    - kunde@example.com
                  retryId: null
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/uploadAttachments/{linkTypeId}/{linkId}:
    post:
      operationId: post_api_v1_mails_uploadAttachments_linkTypeId_linkId
      tags:
        - mails
      summary: Mail upload attachments
      description: |
        Uploads one or more files as temporary mail attachments tied to the given linked entity (e.g. ticket). Used by the mail-compose form to stage attachments before the mail is sent; returns the resulting object records.
      parameters:
        - in: path
          name: linkTypeId
          description: Type of the linked entity the attachments belong to (e.g. ticket).
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: linkId
          description: Id of the linked entity the attachments are staged for.
          required: true
          schema:
            type: integer
          example: 4711
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of created object records, one per uploaded file.
              example:
                meta: {}
                content:
                  - id: 901
                    filename: festplatte-rma.pdf
                    size: 184320
                  - id: 902
                    filename: screenshot.png
                    size: 41010
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/{mailId}:
    delete:
      operationId: delete_api_v1_mails_mailId
      tags:
        - mails
      summary: Mail delete
      description: |
        Removes a mail. If `ticketId` is given, the mail is only detached from that ticket; if no ticket assignments remain afterwards the mail itself is deleted. Used by techs to clean up obsolete or misassigned mails.
      parameters:
        - in: path
          name: mailId
          description: Id of the mail to delete.
          required: true
          schema:
            type: integer
          example: 1024
        - in: query
          name: ticketId
          description: If given, the mail is only detached from this ticket instead of being deleted.
          required: false
          schema:
            type: integer
            default: 0
          example: 4711
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_mails_mailId
      tags:
        - mails
      summary: Get mail
      description: |
        Returns a single mail (subject, body, sender, attachments, status). With `translateCid=true` the HTML body has its `cid:` references rewritten to TANSS attachment URLs so the mail renders correctly in the browser.
      parameters:
        - in: path
          name: mailId
          description: Id of the mail to retrieve.
          required: true
          schema:
            type: integer
          example: 1024
        - in: query
          name: translateCid
          description: If true, rewrites `cid:` references in the HTML body to TANSS attachment URLs.
          required: false
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The requested object.
              example:
                meta: {}
                content:
                  id: 1024
                  subject: 'Re: Festplatte defekt'
                  from: kunde@example.com
                  to:
                    - support@example-it.de
                  body: Vielen Dank für Ihre Anfrage...
                  attachments: []
                  internal: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_mails_mailId
      tags:
        - mails
      summary: Mail update
      description: |
        Updates the editable flags on a stored mail (currently the `internal` flag), used by techs to mark a mail as internal so it stays hidden from the customer portal.
      parameters:
        - in: path
          name: mailId
          description: Id of the mail to update.
          required: true
          schema:
            type: integer
          example: 1024
      requestBody:
        description: Partial object body. Only the `internal` flag is honoured here (other fields are read-only).
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              internal: true
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated object with the new `internal` flag applied.
              example:
                meta: {}
                content:
                  id: 1024
                  subject: 'Re: Festplatte defekt'
                  internal: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/{mailId}/assignTo/{ticketId}:
    put:
      operationId: put_api_v1_mails_mailId_assignTo_ticketId
      tags:
        - mails
      summary: Assign to ticket
      description: |
        Moves (or with `copy=true` copies) an existing mail into the given ticket so it appears in that ticket's mail history. Used by techs to attach an incoming mail to the correct support case.
      parameters:
        - in: path
          name: mailId
          description: Id of the mail to assign to the ticket.
          required: true
          schema:
            type: integer
          example: 1024
        - in: path
          name: ticketId
          description: Id of the target ticket the mail is assigned to.
          required: true
          schema:
            type: integer
          example: 4711
        - in: query
          name: copy
          description: If true, the mail is copied into the ticket instead of moved.
          required: false
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object describing the resulting mail-to-ticket assignment.
              example:
                meta: {}
                content:
                  mailId: 1024
                  ticketId: 5012
                  copied: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mails/{mailId}/reply:
    get:
      operationId: get_api_v1_mails_mailId_reply
      tags:
        - mails
      summary: Mail reply
      description: |
        Builds a prefilled reply payload (subject, quoted body, recipients) for an existing mail so the tech can answer it. With `allReceivers=true` the reply addresses every recipient on the original mail; otherwise only the original sender.
      parameters:
        - in: path
          name: mailId
          description: Id of the mail to build a reply for.
          required: true
          schema:
            type: integer
          example: 1024
        - in: query
          name: allReceivers
          description: If true, the reply addresses all recipients of the original mail, not just the sender.
          required: false
          schema:
            type: boolean
          example: true
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object carrying the prefilled subject/body/recipients.
              example:
                meta: {}
                content:
                  subject: 'Re: Festplatte defekt'
                  to:
                    - kunde@example.com
                  cc: []
                  body: Vielen Dank für Ihre Anfrage...
                  templateId: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mass/from:
    post:
      operationId: post_api_v1_mass_from
      tags:
        - tickets
      summary: Create mass ticket from project
      description: |-
        Creates (or overwrites, if one already exists for the same project) a
        "mass ticket" — a bulk-billing record that aggregates the supports of all
        tickets in a project into a single billable line item. The response status is
        `CREATED` for new mass tickets and `UPDATED` when an existing one is
        overwritten. Admin permission on the mass ticket aspect is required.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Name of the mass ticket to create
                projectId:
                  type: integer
                  description: Identifier of the project the mass ticket belongs to
                phaseIds:
                  type: array
                  description: Identifiers of the project phases included in the mass ticket
                  items:
                    type: object
                overwriteExisting:
                  type: boolean
                  description: Whether an already existing mass ticket for the project is overwritten
                overwriteMassTicketId:
                  type: integer
                  description: Identifier of a specific existing mass ticket to overwrite
            example:
              projectId: 5101
              overwriteExisting: false
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The persisted mass ticket.
              example:
                meta: {}
                content:
                  id: 88
                  projectId: 5101
                  title: Sammelticket Server-Migration 2026
                  billingType: 1
                  wasOverwritten: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mention/pdfExport:
    post:
      operationId: post_api_v1_mention_pdfExport
      tags:
        - administration - export & ui-helpers
      summary: Bulk export mention invoice PDFs
      description: |
        Runs a bulk PDF export for the mention accounting system, restricted by date range and/or order id range. With `execute = false` a dry run is performed that reports which documents would be produced; with `execute = true` it generates them on disk and returns a status per document. Requires `VIEW_INVOICE_PDF_OF_VOUCHER` and a user from the own company.
      requestBody:
        description: An object describing the date or id range and whether to execute the export.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fromDate:
                  type: string
                  description: Start date of the export range
                toDate:
                  type: string
                  description: End date of the export range
                fromOrderId:
                  type: integer
                  description: Lower bound order identifier for the export range
                toOrderId:
                  type: integer
                  description: Upper bound order identifier for the export range
                execute:
                  type: boolean
                  description: Whether the export should actually be performed
                fileNameType:
                  type: string
                  description: Naming scheme applied to the exported files
                  enum:
                    - CUSTOMER_FIRST
                    - INVOICE_FIRST
            example:
              fromDate: '2025-01-01'
              toDate: '2025-01-31'
              fromOrderId: 0
              toOrderId: 0
              execute: false
              fileNameType: INVOICE_NUMBER
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      status:
                        type: string
                        example: OK
                      documents:
                        type: array
                        items:
                          type: object
                          properties:
                            invoiceNumber:
                              type: string
                              example: RE-2025-0001
                            fileName:
                              type: string
                              example: RE-2025-0001.pdf
                            status:
                              type: string
                              example: OK
              example:
                meta: {}
                content:
                  status: OK
                  documents:
                    - invoiceNumber: RE-2025-0001
                      fileName: RE-2025-0001.pdf
                      status: OK
                    - invoiceNumber: RE-2025-0002
                      fileName: RE-2025-0002.pdf
                      status: OK
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/mention/pdfExport/document/{invoiceNumber}:
    get:
      operationId: get_api_v1_mention_pdfExport_document_invoiceNumber
      tags:
        - administration - export & ui-helpers
      summary: Fetch single mention invoice PDF
      description: |
        Loads a single previously generated invoice PDF from the mention export archive, identified by its invoice number. Requires a user from the own company with `VIEW_INVOICE_PDF_OF_VOUCHER`.

        Note: this endpoint is mounted as GET — any request body is ignored.
      parameters:
        - in: path
          name: invoiceNumber
          required: true
          description: Invoice number identifying the mention export PDF to load.
          schema:
            type: string
          example: RE-2025-0042
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      invoiceNumber:
                        type: string
                        example: RE-2025-0001
                      status:
                        type: string
                        example: OK
                      fileName:
                        type: string
                        example: RE-2025-0001.pdf
                      bytes:
                        type: string
                        format: byte
                        example: JVBERi0xLjQKJeLjz9MK
              example:
                meta: {}
                content:
                  invoiceNumber: RE-2025-0001
                  status: OK
                  fileName: RE-2025-0001.pdf
                  bytes: JVBERi0xLjQKJeLjz9MK
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/duplicate/{offerId}:
    get:
      operationId: get_api_v1_offers_duplicate_offerId
      tags:
        - offer
      summary: Duplicate offer
      description: Clones the offer with all its variables and materials. The new offer gets a "(Kopie)" suffix in its name, a fresh creation date, no invoice number, and a recomputed `validTill` based on the template's `validInDays`. Requires the CONTRACT_WORKFLOW module and MANAGE_OWN_OFFERS or MANAGE_ALL_OFFERS permission.
      parameters:
        - in: path
          name: offerId
          required: true
          description: Id of the offer to duplicate
          example: 1
          schema:
            type: integer
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The newly created duplicated offer.
              example:
                meta: {}
                content:
                  id: 502
                  name: Migration auf M365 (Kopie)
                  templateId: 3
                  companyId: 100023
                  createdByEmployeeId: 17
                  date: 1748256000
                  validTill: 1779792000
                  number: 2026-0042
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/pdf/{offerId}:
    get:
      operationId: get_api_v1_offers_pdf_offerId
      tags:
        - offer
      summary: Create offer PDF (not yet implemented)
      description: |
        On-demand offer-PDF generation is not currently available. The offer PDF is served by the `/api/v1/offers/pdf/{offerId}/{workflowId}` endpoint, which returns the PDF that was generated when a contract workflow was started.
      parameters:
        - in: path
          name: offerId
          required: true
          description: Id of the offer
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Placeholder response — endpoint is currently not implemented.
              example:
                meta: {}
                content: null
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/pdf/{offerId}/{workflowId}:
    get:
      operationId: get_api_v1_offers_pdf_offerId_workflowId
      tags:
        - offer
      summary: Get offer PDF for a workflow
      description: 'Returns the stored offer PDF that belongs to a specific contract workflow (typically the version the customer accepted or that was sent out). With `Accept: application/pdf` the PDF is streamed directly; otherwise a file-pass response is returned for asynchronous download.'
      parameters:
        - in: path
          name: offerId
          required: true
          description: Id of the offer
          example: 1
          schema:
            type: integer
        - in: path
          name: workflowId
          required: true
          description: Id of the contract workflow the offer PDF belongs to
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: File-pass response pointing to the stored offer PDF (or direct application/pdf binary when requested via Accept).
              example:
                meta: {}
                content:
                  fileKey: d1c2b3a4-5e6f-7081-92a3-b4c5d6e7f809
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/templates/footer:
    post:
      operationId: post_api_v1_offers_templates_footer
      tags:
        - offer templates
      summary: Create offer template footer
      description: |
        Stores a footer (HTML/text block) that is appended to every PDF rendered from the given offer template. One footer per template.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - templateId
              properties:
                templateId:
                  type: integer
                  description: Identifier of the offer template this footer belongs to
                footer:
                  type: string
                  description: Footer text shown on the offer template
            example:
              templateId: 1
              footer: string
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created template footer.
              example:
                meta: {}
                content:
                  templateId: 3
                  footer: <p>Vielen Dank für Ihr Vertrauen. Bei Rückfragen erreichen Sie uns unter +49 ...</p>
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/templates/globalSettings:
    get:
      operationId: get_api_v1_offers_templates_globalSettings
      tags:
        - offer templates
      summary: Get offer template global settings
      description: |
        Returns the system-wide default settings for offer templates (a virtual template with id `-1`). Used to seed defaults shown in the template editor.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The global default offer-template settings (virtual id -1).
              example:
                meta: {}
                content:
                  id: -1
                  name: Globale Vorgaben
                  validInDays: 30
                  createdByEmployeeId: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_offers_templates_globalSettings
      tags:
        - offer templates
      summary: Edit offer template global settings
      description: |
        Updates the system-wide default settings for offer templates (virtual template id `-1`). Changes only affect new templates; existing per-template overrides are kept.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              linkedEntities:
                employees:
                  '2':
                    name: some employee name
              properties:
                fields:
                  someFieldIndex: {}
                extras:
                  someExtraIndex: someExtraValue
                editable: false
                message: example
              listProperties: {}
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The global default offer-template settings (virtual id -1).
              example:
                meta: {}
                content:
                  id: -1
                  name: Globale Vorgaben
                  validInDays: 30
                  createdByEmployeeId: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/templates/{templateId}/footer:
    delete:
      operationId: delete_api_v1_offers_templates_templateId_footer
      tags:
        - offer templates
      summary: Delete offer template footer
      description: |
        Removes the footer block from the given offer template. Future PDFs rendered from this template will then fall back to no footer (or the global default).
      parameters:
        - in: path
          name: templateId
          required: true
          description: Id of the offer template
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_offers_templates_templateId_footer
      tags:
        - offer templates
      summary: Get offer template footer
      description: |
        Returns the footer block configured for the given offer template, used to render the bottom area of generated offer PDFs.
      parameters:
        - in: path
          name: templateId
          required: true
          description: Id of the offer template
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The offer template footer block.
              example:
                meta: {}
                content:
                  templateId: 3
                  footer: <p>Vielen Dank für Ihr Vertrauen. Bei Rückfragen erreichen Sie uns unter +49 ...</p>
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_offers_templates_templateId_footer
      tags:
        - offer templates
      summary: Update offer template footer
      description: |
        Updates the footer block of an offer template (HTML/text rendered at the bottom of every PDF generated from this template).
      parameters:
        - in: path
          name: templateId
          required: true
          description: Id of the offer template
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - templateId
              properties:
                templateId:
                  type: integer
                  description: Identifier of the offer template this footer belongs to
                footer:
                  type: string
                  description: Footer text shown on the offer template
            example:
              templateId: 1
              footer: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The offer template footer block.
              example:
                meta: {}
                content:
                  templateId: 3
                  footer: <p>Vielen Dank für Ihr Vertrauen. Bei Rückfragen erreichen Sie uns unter +49 ...</p>
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/offers/{offerId}:
    delete:
      operationId: delete_api_v1_offers_offerId
      tags:
        - offer
      summary: Delete offer
      description: |
        Deletes an offer. Only allowed if no associated workflow contract has reached state `CONTRACT_AVAILABLE` (i.e. the offer was not yet confirmed by the customer). Requires MANAGE_ALL_OFFERS, or MANAGE_OWN_OFFERS when the caller created the offer.
      parameters:
        - in: path
          name: offerId
          required: true
          description: Id of the offer
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_offers_offerId
      tags:
        - offer
      summary: Get offer
      description: |
        Returns a single offer with its variables, materials and decorated meta properties (`editable`, `canStartContractWorkflow`, existing workflow contracts). Requires CONTRACT_WORKFLOW module, VIEW_OFFERS permission and company access to the offer.
      parameters:
        - in: path
          name: offerId
          required: true
          description: Id of the offer
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The offer including variables, materials and workflow info.
              example:
                meta: {}
                content:
                  id: 501
                  name: Migration auf M365
                  templateId: 3
                  companyId: 100023
                  createdByEmployeeId: 17
                  date: 1748256000
                  validTill: 1779792000
                  number: 2026-0042
                  linkTypeId: 0
                  linkId: 0
                  invoiceNumber: null
                  vars: []
                  mats: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_offers_offerId
      tags:
        - offer
      summary: Edit offer
      description: |
        Updates an offer including its variables and materials (existing ones are diffed and inserted/updated/removed). Also extends the expiry date of any still-open contract workflow tokens to match the new `validTill`. Requires MANAGE_ALL_OFFERS, or MANAGE_OWN_OFFERS when the caller created the offer.
      parameters:
        - in: path
          name: offerId
          required: true
          description: Id of the offer
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the offer
                name:
                  type: string
                  description: Display name of the offer
                templateId:
                  type: integer
                  description: Identifier of the template the offer is based on
                date:
                  type: integer
                  format: int64
                  description: Creation timestamp of the offer
                createdByEmployeeId:
                  type: integer
                  description: Identifier of the employee who created the offer
                companyId:
                  type: integer
                  description: Identifier of the company the offer belongs to
                linkTypeId:
                  type: integer
                  description: Type of object the offer is linked to
                linkId:
                  type: integer
                  description: Identifier of the linked object
                validTill:
                  type: integer
                  format: int64
                  description: Timestamp until which the offer is valid
                number:
                  type: string
                  description: Offer number
                erpProjectId:
                  type: string
                  description: Identifier of the associated ERP project
                invoiceNumber:
                  type: string
                  description: Invoice number associated with the offer
            example:
              id: 42
              name: Example name
              templateId: 1
              date: 1748256000
              createdByEmployeeId: 1
              companyId: 1
              linkTypeId: 1
              linkId: 1
              validTill: 1
              number: string
              erpProjectId: string
              invoiceNumber: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The offer including variables, materials and workflow info.
              example:
                meta: {}
                content:
                  id: 501
                  name: Migration auf M365
                  templateId: 3
                  companyId: 100023
                  createdByEmployeeId: 17
                  date: 1748256000
                  validTill: 1779792000
                  number: 2026-0042
                  linkTypeId: 0
                  linkId: 0
                  invoiceNumber: null
                  vars: []
                  mats: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/approve:
    get:
      operationId: get_api_v1_overtime_approve
      tags:
        - vacationRequests
      summary: Get approveable requests
      description: Returns the overtime requests the current user is allowed to approve.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/balance:
    get:
      operationId: get_api_v1_overtime_balance
      tags:
        - vacationRequests
      summary: Get overtime balance
      description: Returns the current overtime balance for the caller.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/history:
    get:
      operationId: get_api_v1_overtime_history
      tags:
        - vacationRequests
      summary: Get overtime history
      description: Returns the overtime history of the calling employee.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/open:
    get:
      operationId: get_api_v1_overtime_open
      tags:
        - vacationRequests
      summary: Get open requests
      description: Returns the caller's open overtime requests that have not yet been decided.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/payOut:
    post:
      operationId: post_api_v1_overtime_payOut
      tags:
        - vacationRequests
      summary: Create overtime pay out request
      description: Creates a new overtime pay-out request for the caller.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - employeeId
              properties:
                id:
                  type: integer
                  description: Unique identifier of the overtime request
                employeeId:
                  type: integer
                  description: Identifier of the employee submitting the overtime request
                date:
                  type: integer
                  format: int64
                  description: Timestamp when the request was created
                day:
                  type: string
                  format: date
                  description: Calendar day the overtime applies to (yyyy-MM-dd)
                minutesRequested:
                  type: integer
                  description: Number of overtime minutes requested
                minutesApproved:
                  type: integer
                  description: Number of overtime minutes approved
                approvedByEmployeeId:
                  type: integer
                  description: Identifier of the employee who approved the request
                commentRequest:
                  type: string
                  description: Comment provided with the request
                commentApproved:
                  type: string
                  description: Comment provided upon approval
                status:
                  type: string
                  description: Current status of the overtime request
                  enum:
                    - NEW
                    - APPROVED
                    - DECLINED
                    - PAYOUT_REQUESTED
                    - PAYOUT_APPROVED
                    - PAYOUT_DECLINED
                    - VACATION_REQUESTED
                    - VACATION_APPROVED
                    - VACATION_DECLINED
                hourlyRate:
                  type: number
                  description: Hourly rate used to calculate the payout amount
                paymentDate:
                  type: integer
                  format: int64
                  description: Timestamp when the overtime was paid out
            example:
              id: 42
              employeeId: 1
              date: 1748256000
              day: VALUE
              minutesRequested: 1
              minutesApproved: 1
              approvedByEmployeeId: 1
              commentRequest: Example content
              commentApproved: Example content
              status:
                value: 1
              hourlyRate: 19
              paymentDate: 1748256000
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/payOut/{id}:
    put:
      operationId: put_api_v1_overtime_payOut_id
      tags:
        - vacationRequests
      summary: Edit overtime pay out request
      description: Updates the overtime pay-out request identified by its id.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the overtime pay out request
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              linkedEntities:
                employees:
                  '2':
                    name: some employee name
              properties:
                fields:
                  someFieldIndex: {}
                extras:
                  someExtraIndex: someExtraValue
                editable: false
                message: example
              listProperties: {}
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/request/{id}:
    put:
      operationId: put_api_v1_overtime_request_id
      tags:
        - vacationRequests
      summary: Edit overtime request
      description: Updates the overtime request identified by its id.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the overtime request
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - employeeId
              properties:
                id:
                  type: integer
                  description: Unique identifier of the overtime request
                employeeId:
                  type: integer
                  description: Identifier of the employee submitting the overtime request
                date:
                  type: integer
                  format: int64
                  description: Timestamp when the request was created
                day:
                  type: string
                  format: date
                  description: Calendar day the overtime applies to (yyyy-MM-dd)
                minutesRequested:
                  type: integer
                  description: Number of overtime minutes requested
                minutesApproved:
                  type: integer
                  description: Number of overtime minutes approved
                approvedByEmployeeId:
                  type: integer
                  description: Identifier of the employee who approved the request
                commentRequest:
                  type: string
                  description: Comment provided with the request
                commentApproved:
                  type: string
                  description: Comment provided upon approval
                status:
                  type: string
                  description: Current status of the overtime request
                  enum:
                    - NEW
                    - APPROVED
                    - DECLINED
                    - PAYOUT_REQUESTED
                    - PAYOUT_APPROVED
                    - PAYOUT_DECLINED
                    - VACATION_REQUESTED
                    - VACATION_APPROVED
                    - VACATION_DECLINED
                hourlyRate:
                  type: number
                  description: Hourly rate used to calculate the payout amount
                paymentDate:
                  type: integer
                  format: int64
                  description: Timestamp when the overtime was paid out
            example:
              id: 42
              employeeId: 1
              date: 1748256000
              day: VALUE
              minutesRequested: 1
              minutesApproved: 1
              approvedByEmployeeId: 1
              commentRequest: Example content
              commentApproved: Example content
              status:
                value: 1
              hourlyRate: 19
              paymentDate: 1748256000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/supports:
    get:
      operationId: get_api_v1_overtime_supports
      tags:
        - vacationRequests
      summary: Get requestable supports
      description: Returns the supports that can be booked as overtime within the given time range.
      parameters:
        - in: query
          name: from
          required: true
          description: Unix timestamp of the start of the period
          example: 1748256000
          schema:
            type: integer
            format: int64
        - in: query
          name: till
          required: true
          description: Unix timestamp of the end of the period
          example: 1748256000
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_overtime_supports
      tags:
        - vacationRequests
      summary: Create overtime request
      description: Creates a new overtime request.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - employeeId
              properties:
                id:
                  type: integer
                  description: Unique identifier of the overtime request
                employeeId:
                  type: integer
                  description: Identifier of the employee submitting the overtime request
                date:
                  type: integer
                  format: int64
                  description: Timestamp when the request was created
                day:
                  type: string
                  format: date
                  description: Calendar day the overtime applies to (yyyy-MM-dd)
                minutesRequested:
                  type: integer
                  description: Number of overtime minutes requested
                minutesApproved:
                  type: integer
                  description: Number of overtime minutes approved
                approvedByEmployeeId:
                  type: integer
                  description: Identifier of the employee who approved the request
                commentRequest:
                  type: string
                  description: Comment provided with the request
                commentApproved:
                  type: string
                  description: Comment provided upon approval
                status:
                  type: string
                  description: Current status of the overtime request
                  enum:
                    - NEW
                    - APPROVED
                    - DECLINED
                    - PAYOUT_REQUESTED
                    - PAYOUT_APPROVED
                    - PAYOUT_DECLINED
                    - VACATION_REQUESTED
                    - VACATION_APPROVED
                    - VACATION_DECLINED
                hourlyRate:
                  type: number
                  description: Hourly rate used to calculate the payout amount
                paymentDate:
                  type: integer
                  format: int64
                  description: Timestamp when the overtime was paid out
            example:
              id: 42
              employeeId: 1
              date: 1748256000
              day: VALUE
              minutesRequested: 1
              minutesApproved: 1
              approvedByEmployeeId: 1
              commentRequest: Example content
              commentApproved: Example content
              status:
                value: 1
              hourlyRate: 19
              paymentDate: 1748256000
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/toBePaidOut:
    get:
      operationId: get_api_v1_overtime_toBePaidOut
      tags:
        - vacationRequests
      summary: Ge to be paid out requests
      description: Returns the overtime pay-out requests that are pending pay-out.
      parameters:
        - in: query
          name: employeeId
          required: false
          description: Restrict the result to a single employee; omit for all accessible employees
          example: 5
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/overtime/toBePaidOut/mark/{id}:
    post:
      operationId: post_api_v1_overtime_toBePaidOut_mark_id
      tags:
        - vacationRequests
      summary: Mark as paid out
      description: Marks the given overtime pay-out request as paid out.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the overtime pay out request to mark as paid out
          example: 1
          schema:
            type: integer
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ownDailyServices/{day}:
    get:
      operationId: get_api_v1_ownDailyServices_day
      tags:
        - daily services
      summary: Get own daily services for a day
      description: |
        Returns the calling employee's own daily-services view for the given day: booked supports, not-yet-confirmed days, day-confirm
        infos, older days that still need attention (open appointments/consultations) and the relevant holidays. Requires the caller to
        be a technician or freelancer with the `ACCESS_DAILY_SUPPORTS` permission. If the employee still has earlier days to confirm,
        the returned `day` is silently shifted to the oldest unconfirmed date — the requested `day` is not always echoed back.
      parameters:
        - in: path
          name: day
          required: true
          description: Day to fetch the daily-services view for, formatted as YYYY-MM-DD.
          schema:
            type: string
          example: '2025-05-26'
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The employee's daily-services view for the requested day.
              example:
                meta: {}
                content:
                  date: '2025-05-26'
                  totalSeconds: 28800
                  bookedSeconds: 23400
                  supports:
                    - supportId: 5004
                      duration: 1800
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ownDailyServices/{day}/charts:
    get:
      operationId: get_api_v1_ownDailyServices_day_charts
      tags:
        - daily services
      summary: Get own daily services day charts (calling user)
      description: |
        Returns the chart data (working-schedule minutes, public/internal support minutes, productivity ratio) for the calling employee
        on the given day — the "Wie viel habe ich heute gebucht?" doughnut. Requires technician/freelancer with `ACCESS_DAILY_SUPPORTS`.
        Always restricted to the caller's own user id; for foreign employees use the `statisticAllServicesByDay` variant instead.
      parameters:
        - in: path
          name: day
          required: true
          description: Day to report on, formatted as YYYY-MM-DD.
          schema:
            type: string
          example: '2025-05-26'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Chart data with working-schedule, support and productivity minutes for the day.
              example:
                meta: {}
                content:
                  date: '2025-05-26'
                  totalSeconds: 28800
                  bookedSeconds: 23400
                  supports:
                    - supportId: 5004
                      duration: 1800
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ownDailyServices/{day}/charts/statisticAllServicesByDay:
    get:
      operationId: get_api_v1_ownDailyServices_day_charts_statisticAllServicesByDay
      tags:
        - daily services
      summary: Get daily-services charts for one or more employees
      description: |
        Returns the chart data (working-schedule, supports, productivity minutes) for the given day across the requested employee ids —
        aggregated into a single chart, or split per employee when `asList=true`. Requires the caller to be a user of the own company
        with the `STATISTICS_ALL_SERVICES_OF_A_DAY` permission; intended for the team-overview chart, not for self-bookings.
      parameters:
        - in: path
          name: day
          required: true
          description: Day to report on, formatted as YYYY-MM-DD.
          schema:
            type: string
          example: '2025-05-26'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Aggregated chart, or a map keyed by employee id when `asList=true`.
              example:
                meta: {}
                content:
                  date: '2025-05-26'
                  totalSeconds: 28800
                  bookedSeconds: 23400
                  supports:
                    - supportId: 5004
                      duration: 1800
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ownDailyServices/{day}/confirm:
    get:
      operationId: get_api_v1_ownDailyServices_day_confirm
      tags:
        - daily services
      summary: Confirm own daily services for a day
      description: |
        Marks the given day as confirmed ("Tagesabschluss") for the calling employee — a daily-services completion record is persisted.
        Requires technician/freelancer with `ACCESS_DAILY_SUPPORTS`. The call fails if open appointments exist on that day, or — for
        employees with the timestamp module enabled — if the last work timestamp/change-request is not properly closed and the user is
        not marked as fully absent.
      parameters:
        - in: path
          name: day
          required: true
          description: Day to confirm ("Tagesabschluss"), formatted as YYYY-MM-DD.
          schema:
            type: string
          example: '2025-05-26'
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty — only the meta envelope is returned.
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ownDailyServices/{day}/statisticAllServicesByDay:
    get:
      operationId: get_api_v1_ownDailyServices_day_statisticAllServicesByDay
      tags:
        - daily services
      summary: Get daily-services overview across employees
      description: |
        Returns an aggregated daily-services view (remote supports, phone calls, timers, appointments, not-documented time) summed
        across the given `employeeIds` for the day. Requires the caller to be from the own company with the
        `STATISTICS_ALL_SERVICES_OF_A_DAY` permission. The per-employee booked-time list (`documentedTimes`) is intentionally stripped
        from the response — only the totals are exposed here.
      parameters:
        - in: path
          name: day
          required: true
          description: Day to report on, formatted as YYYY-MM-DD.
          schema:
            type: string
          example: '2025-05-26'
        - in: query
          name: employeeIds
          required: false
          description: Comma-separated list of employee ids to aggregate; empty means all employees.
          schema:
            type: string
            default: ''
          example: 5,7,9
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Aggregated counters across the requested employee ids.
              example:
                meta: {}
                content:
                  date: '2025-05-26'
                  totalSeconds: 28800
                  bookedSeconds: 23400
                  supports:
                    - supportId: 5004
                      duration: 1800
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ownDailyServices/{day}/statisticAllServicesByDay/completionInfos:
    get:
      operationId: get_api_v1_ownDailyServices_day_statisticAllServicesByDay_completionInfos
      tags:
        - daily services
      summary: Get day-completion status for each employee
      description: |
        Returns one completion-status entry per requested employee for the given day — telling the team-overview screen whether each
        employee `HAS_TO_COMPLETE`, has `COMPLETED` the day, completed on `COMPLETED_OTHER_DAY`, or `NONE` (no daily-services
        configuration / not active yet). Requires `STATISTICS_ALL_SERVICES_OF_A_DAY` from the own company.
      parameters:
        - in: path
          name: day
          required: true
          description: Day to report on, formatted as YYYY-MM-DD.
          schema:
            type: string
          example: '2025-05-26'
        - in: query
          name: employeeIds
          required: false
          description: Comma-separated list of employee ids to include; empty means all employees.
          schema:
            type: string
            default: ''
          example: 5,7,9
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of per-employee completion statuses for the day.
              example:
                meta: {}
                content:
                  - date: '2025-05-26'
                    totalSeconds: 28800
                    bookedSeconds: 23400
                    supports:
                      - supportId: 5004
                        duration: 1800
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/passkey/status:
    get:
      operationId: get_api_v1_passkey_status
      tags:
        - employees
      summary: Check whether passkey login is enabled
      description: |
        Returns whether WebAuthn / passkey login is enabled on the server. Used by
        the login page to decide whether to show the passkey button.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      enabled:
                        type: boolean
              example:
                meta: {}
                content:
                  enabled: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/passwords:
    post:
      operationId: post_api_v1_passwords
      tags:
        - employees
      summary: Create password
      description: |
        Creates a new stored password (credential vault entry) linked to an entity such as an employee. Access requires the caller to have permission for the target link (own employee record is always allowed; otherwise `MANAGE_PASSWORDS_FOR_EMPLOYEES` and, for own-company employees, also `MANAGE_EMPLOYEE_PASSWORD_OF_OWN_COMPANY`). The creation is journalled to the password log.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the stored password entry
                passwordTypeId:
                  type: integer
                  description: Identifier of the password type/category
                linkType:
                  type: string
                  description: Type of entity the password entry is linked to
                  enum:
                    - EMPLOYEE
                linkId:
                  type: integer
                  description: Identifier of the linked entity the password belongs to
                userName:
                  type: string
                  description: User name associated with the password entry
                password:
                  type: string
                  description: The stored password value
                comment:
                  type: string
                  description: Free-text comment for the password entry
            example:
              id: 42
              passwordTypeId: 1
              linkType:
                value: 1
              linkId: 1
              userName: max.mustermann
              password: '********'
              comment: Example content
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The newly created password record.
              example:
                meta: {}
                content:
                  id: 42
                  passwordTypeId: 1
                  linkType: EMPLOYEE
                  linkId: 5
                  userName: max.mustermann
                  password: '********'
                  comment: VPN Zugang
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/passwords/employee/{employeeId}:
    get:
      operationId: get_api_v1_passwords_employee_employeeId
      tags:
        - employees
      summary: Get employee passwords
      description: |
        Returns all stored passwords (credential vault entries) linked to the given employee. The caller may always read their own passwords; otherwise `MANAGE_PASSWORDS_FOR_EMPLOYEES` is required, and for employees of the own company `MANAGE_EMPLOYEE_PASSWORD_OF_OWN_COMPANY` is additionally enforced.
      parameters:
        - in: path
          name: employeeId
          required: true
          description: Id of the employee whose passwords should be returned.
          example: 5
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of password records linked to the employee.
              example:
                meta: {}
                content:
                  - id: 42
                    passwordTypeId: 1
                    linkType: EMPLOYEE
                    linkId: 5
                    userName: max.mustermann
                    password: '********'
                    comment: VPN Zugang
                  - id: 43
                    passwordTypeId: 2
                    linkType: EMPLOYEE
                    linkId: 5
                    userName: mmustermann@example.com
                    password: '********'
                    comment: Mail-Konto
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/passwords/types:
    get:
      operationId: get_api_v1_passwords_types
      tags:
        - employees
      summary: Get password types
      description: |
        Returns the list of available password type classifications (e.g. VPN, Mail, RDP) used to categorise stored credentials in the password vault.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of password type classifications.
              example:
                meta: {}
                content:
                  - id: 1
                    name: VPN
                  - id: 2
                    name: E-Mail
                  - id: 3
                    name: RDP
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/passwords/{id}:
    delete:
      operationId: delete_api_v1_passwords_id
      tags:
        - employees
      summary: Delete password
      description: |
        Deletes a stored password record. Access is gated by the same rules as reading: the user must have permission for the linked target (own employee always allowed, otherwise `MANAGE_PASSWORDS_FOR_EMPLOYEES` plus, for own-company employees, `MANAGE_EMPLOYEE_PASSWORD_OF_OWN_COMPANY`). The deletion is journalled to the password log.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the stored password record.
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_passwords_id
      tags:
        - employees
      summary: Update password
      description: |
        Updates an existing stored password. `linkType` and `linkId` cannot be changed once the record exists; the assignment is locked. Access checks mirror the read path (own employee always, otherwise `MANAGE_PASSWORDS_FOR_EMPLOYEES` plus `MANAGE_EMPLOYEE_PASSWORD_OF_OWN_COMPANY` for own-company employees), and changes are journalled.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the stored password record.
          example: 42
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the stored password entry
                passwordTypeId:
                  type: integer
                  description: Identifier of the password type/category
                linkType:
                  type: string
                  description: Type of entity the password entry is linked to
                  enum:
                    - EMPLOYEE
                linkId:
                  type: integer
                  description: Identifier of the linked entity the password belongs to
                userName:
                  type: string
                  description: User name associated with the password entry
                password:
                  type: string
                  description: The stored password value
                comment:
                  type: string
                  description: Free-text comment for the password entry
            example:
              id: 42
              passwordTypeId: 1
              linkType:
                value: 1
              linkId: 1
              userName: max.mustermann
              password: '********'
              comment: Example content
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated password record.
              example:
                meta: {}
                content:
                  id: 42
                  passwordTypeId: 1
                  linkType: EMPLOYEE
                  linkId: 5
                  userName: max.mustermann
                  password: '********'
                  comment: VPN Zugang (neu)
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/paymentMethods:
    get:
      operationId: get_api_v1_paymentMethods
      tags:
        - payment methods
      summary: Get all payment methods
      description: |
        Returns every payment method configured in the system. The list contains the term in months and an optional discount percentage that drive invoice generation. Mutations require `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` and a user from the own company.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Sofort
                        monthCount:
                          type: integer
                          example: 0
                        percent:
                          type: number
                          example: 2
                        mentionArticleNumber:
                          type: string
                          example: PM-NET-0
              example:
                meta: {}
                content:
                  - id: 1
                    name: Sofort
                    monthCount: 0
                    percent: 2
                    mentionArticleNumber: PM-NET-0
                  - id: 2
                    name: 14 Tage netto
                    monthCount: 1
                    percent: 0
                    mentionArticleNumber: PM-NET-14
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_paymentMethods
      tags:
        - payment methods
      summary: Create payment method
      description: |
        Creates a payment method that can later be assigned to companies and invoices. Requires a user from the own company with `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`.
      requestBody:
        description: JSON body. An object.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the payment method
                monthCount:
                  type: integer
                  description: Number of months associated with the payment method
                name:
                  type: string
                  description: Display name of the payment method
                percent:
                  type: number
                  description: Percentage value applied for this payment method
                mentionArticleNumber:
                  type: string
                  description: Article number referenced by this payment method
            example:
              id: 0
              name: 14 Tage netto
              monthCount: 1
              percent: 0
              mentionArticleNumber: PM-NET-14
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 2
                      name:
                        type: string
                        example: 14 Tage netto
                      monthCount:
                        type: integer
                        example: 1
                      percent:
                        type: number
                        example: 0
                      mentionArticleNumber:
                        type: string
                        example: PM-NET-14
              example:
                meta: {}
                content:
                  id: 2
                  name: 14 Tage netto
                  monthCount: 1
                  percent: 0
                  mentionArticleNumber: PM-NET-14
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/paymentMethods/{id}:
    delete:
      operationId: delete_api_v1_paymentMethods_id
      tags:
        - payment methods
      summary: Delete payment method by id
      description: |
        Generic admin delete endpoint. Used by accounting types, currencies, payment methods, etc.; Requires the corresponding admin permission (e.g. `MANAGE_ACCOUNTING_TYPES` or `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`) and checks for blocking references before the row is removed.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the payment method.
          schema:
            type: string
          example: '42'
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_paymentMethods_id
      tags:
        - payment methods
      summary: Get payment method by id
      description: |
        Generic admin read endpoint. Returns the single configured entity (accounting type, currency, payment method, etc.) addressed by `id`. Standard admin access checks apply.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the payment method.
          schema:
            type: string
          example: '42'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    example:
                      id: 1
                      name: Standard
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_paymentMethods_id
      tags:
        - payment methods
      summary: Edit payment method by id
      description: |
        Generic admin update endpoint. Applies the JSON patch to the entity addressed by `id` and persists it. Requires the corresponding admin permission (e.g. `MANAGE_ACCOUNTING_TYPES`, `BASE_DATA_MANAGEMENT_SYSTEM_TABLES`).
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the payment method.
          schema:
            type: string
          example: '42'
      requestBody:
        description: JSON body with the updated entity fields.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              id: 1
              name: Standard
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    example:
                      id: 1
                      name: Standard
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/pcs/company/{companyId}/export/excel:
    get:
      operationId: get_api_v1_pcs_company_companyId_export_excel
      tags:
        - device management
      summary: Export company peripheries to Excel
      description: |
        Builds an Excel export of all peripheries assigned to the given company. Honors the `Accept` header to decide between a direct binary download and a file-pass response for asynchronous retrieval.
      parameters:
        - in: path
          name: companyId
          description: ID of the company whose peripheries are exported.
          required: true
          schema:
            type: integer
          example: 100023
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: File-pass response (or direct .xlsx binary if requested via Accept header).
              example:
                meta: {}
                content:
                  fileKey: b71c4e2f-8a91-4c2f-a1ee-7d9e2c0a1b34
                  filename: peripherie-list.xlsx
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/pcs/pdf:
    put:
      operationId: put_api_v1_pcs_pdf
      tags:
        - device management
      summary: Get PC list PDF
      description: |
        Generates a PDF rendering of the PC list matching the supplied configuration filter. Same filter semantics as the regular list endpoint, but the result is a PDF (or file-pass key depending on the Accept header).
      requestBody:
        description: A configuration filter object describing which PCs to include; same filter semantics as the PC list endpoint.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Configuration filter for the PC list.
            example:
              text: Example content
              extras: {}
              linkedEntities: {}
              assignments:
                infos: {}
              properties:
                fields: {}
                extras: {}
                permissions: {}
                editable: false
                message: Example content
              pagination:
                itemsPerPage: 1
                totalItems: 1
                page: 1
              listProperties: {}
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: File-pass response pointing to the generated PC-list PDF.
              example:
                meta: {}
                content:
                  fileKey: c92a0d11-3e4b-4f6c-9b21-58a3c1d20a7e
                  filename: pc-list.pdf
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/peripheries/company/{companyId}/export/excel:
    get:
      operationId: get_api_v1_peripheries_company_companyId_export_excel
      tags:
        - device management
      summary: Export company peripheries to Excel
      description: |
        Builds an Excel export of all peripheries assigned to the given company. Honors the `Accept` header to decide between a direct binary download and a file-pass response for asynchronous retrieval.
      parameters:
        - in: path
          name: companyId
          description: ID of the company whose peripheries are exported.
          required: true
          schema:
            type: integer
          example: 100023
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: File-pass response (or direct .xlsx binary if requested via Accept header).
              example:
                meta: {}
                content:
                  fileKey: b71c4e2f-8a91-4c2f-a1ee-7d9e2c0a1b34
                  filename: peripherie-list.xlsx
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/peripheries/pdf:
    put:
      operationId: put_api_v1_peripheries_pdf
      tags:
        - device management
      summary: Get periphery list PDF
      description: |
        Generates a PDF rendering of the periphery list matching the supplied configuration filter. Same filter semantics as the regular list endpoint, but the result is a PDF (or file-pass key depending on the Accept header).
      requestBody:
        description: A configuration filter object describing which peripheries to include; same filter semantics as the periphery list endpoint.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Configuration filter for the periphery list.
            example:
              text: Example content
              extras: {}
              linkedEntities: {}
              assignments:
                infos: {}
              properties:
                fields: {}
                extras: {}
                permissions: {}
                editable: false
                message: Example content
              pagination:
                itemsPerPage: 1
                totalItems: 1
                page: 1
              listProperties: {}
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: File-pass response pointing to the generated periphery-list PDF.
              example:
                meta: {}
                content:
                  fileKey: c92a0d11-3e4b-4f6c-9b21-58a3c1d20a7e
                  filename: peripherie-list.pdf
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/permissions/employee/{employeeId}:
    get:
      operationId: get_api_v1_permissions_employee_employeeId
      tags:
        - permissions
      summary: Get permission list for an employee
      description: |
        Returns the list of permissions effectively granted to the employee with
        the given id. The caller must be from the own company and hold both
        `MANAGE_PERMISSIONS` and `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: path
          name: employeeId
          description: Id of the employee whose permission list should be returned.
          required: true
          schema:
            type: string
          example: '5'
      responses:
        '200':
          description: Permission definitions assigned to the employee.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        categoryId:
                          type: integer
                        assigned:
                          type: boolean
              example:
                meta: {}
                content:
                  - id: 12
                    name: MANAGE_EMPLOYEES
                    categoryId: 1
                    assigned: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/permissions/employeesWithPermission:
    get:
      operationId: get_api_v1_permissions_employeesWithPermission
      tags:
        - permissions
      summary: Get employees with permission
      description: |-
        Returns, for the given `companyId`, every employee whose status (`HAS_PERMISSION`,
        `INHERITED`, `NONE`, ...) is computed from whether they actually have the
        given `permissionId` assigned. The caller must be from the own company and
        hold both `MANAGE_PERMISSIONS` and `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: query
          name: permissionId
          description: Id of the permission to check against.
          required: true
          schema:
            type: integer
          example: 1
        - in: query
          name: companyId
          description: Id of the company whose employees should be evaluated.
          required: true
          schema:
            type: integer
          example: 100023
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        employeeId:
                          type: integer
                        name:
                          type: string
                        status:
                          type: string
                          enum:
                            - HAS_PERMISSION
                            - INHERITED_FROM_PACKAGE
                            - NONE
              example:
                meta: {}
                content:
                  - employeeId: 5
                    name: Max Mustermann
                    status: HAS_PERMISSION
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/permissions/packages:
    get:
      operationId: get_api_v1_permissions_packages
      tags:
        - permissions
      summary: Get permission packages available for an employee
      description: |
        Returns the permission packages that may be assigned to the given employee
        (filtered by employee type). Caller must be from the own company and hold
        `MANAGE_PERMISSIONS` + `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: query
          name: employeeId
          description: Id of the employee whose assignable permission packages should be returned.
          required: true
          schema:
            type: integer
          example: 5
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        info:
                          type: string
                        type:
                          type: integer
              example:
                meta: {}
                content:
                  - id: 1
                    name: Standard Technician
                    info: Default permissions for technicians
                    type: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/permissions/permissionPackage/{permissionPackageId}/to/{employeeId}:
    delete:
      operationId: delete_api_v1_permissions_permissionPackage_permissionPackageId_to_employeeId
      tags:
        - permissions
      summary: Remove all permissions of a package from an employee
      description: |
        Removes from the employee every permission that the given permission
        package grants. Caller must be from the own company and hold
        `MANAGE_PERMISSIONS` + `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: path
          name: permissionPackageId
          description: Id of the permission package to remove from the employee.
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: employeeId
          description: Id of the employee the package permissions should be removed from.
          required: true
          schema:
            type: integer
          example: 5
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_permissions_permissionPackage_permissionPackageId_to_employeeId
      tags:
        - permissions
      summary: Apply a permission package to an employee
      description: |
        Grants every permission contained in the given package to the employee.
        Caller must be from the own company and hold `MANAGE_PERMISSIONS` +
        `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: path
          name: permissionPackageId
          description: Id of the permission package to apply to the employee.
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: employeeId
          description: Id of the employee the package permissions should be granted to.
          required: true
          schema:
            type: integer
          example: 5
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/permissions/removeAllFrom/{employeeId}:
    delete:
      operationId: delete_api_v1_permissions_removeAllFrom_employeeId
      tags:
        - permissions
      summary: Remove every permission from an employee
      description: |
        Strips every direct permission assignment from the given employee. Caller
        must be from the own company and hold `MANAGE_PERMISSIONS` +
        `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: path
          name: employeeId
          description: Id of the employee to strip all direct permissions from.
          required: true
          schema:
            type: integer
          example: 5
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/permissions/setAllFor/{employeeId}:
    put:
      operationId: put_api_v1_permissions_setAllFor_employeeId
      tags:
        - permissions
      summary: Grant every available permission to an employee
      description: |
        Adds every permission that the employee's type is allowed to receive
        to the given employee. Caller must be from the own company and hold
        `MANAGE_PERMISSIONS` + `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: path
          name: employeeId
          description: Id of the employee to grant all available permissions to.
          required: true
          schema:
            type: integer
          example: 5
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/permissions/type/{employeeType}:
    get:
      operationId: get_api_v1_permissions_type_employeeType
      tags:
        - permissions
      summary: Get permission list for an employee type
      description: |
        Returns the catalog of available permissions for a given `employeeType`
        (e.g. `TECHNICIAN`, `CONTACT_PERSON`, `FREELANCER`). Caller must be from
        the own company and hold `MANAGE_PERMISSIONS` + `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: path
          name: employeeType
          description: Employee type whose permission catalog should be returned (e.g. TECHNICIAN, CONTACT_PERSON, FREELANCER).
          required: true
          schema:
            type: string
          example: TECHNICIAN
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        categoryId:
                          type: integer
              example:
                meta: {}
                content:
                  - id: 12
                    name: MANAGE_EMPLOYEES
                    categoryId: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/permissions/{permissionId}:
    delete:
      operationId: delete_api_v1_permissions_permissionId
      tags:
        - permissions
      summary: Remove a permission from multiple employees
      description: |
        Revokes the given `permissionId` from each employee in the comma-separated
        `employeeIds` query parameter. Caller must be from the own company and hold
        `MANAGE_PERMISSIONS` + `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: path
          name: permissionId
          description: Id of the permission to revoke.
          required: true
          schema:
            type: integer
          example: 1
        - in: query
          name: employeeIds
          description: Comma-separated list of employee ids to revoke the permission from.
          required: true
          schema:
            type: string
          example: 5,6,7
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_permissions_permissionId
      tags:
        - permissions
      summary: Grant a permission to multiple employees
      description: |
        Grants the given `permissionId` to each employee in the comma-separated
        `employeeIds` query parameter. Caller must be from the own company and hold
        `MANAGE_PERMISSIONS` + `EMPLOYEE_ADMINISTRATION`.
      parameters:
        - in: path
          name: permissionId
          description: Id of the permission to grant.
          required: true
          schema:
            type: integer
          example: 1
        - in: query
          name: employeeIds
          description: Comma-separated list of employee ids to grant the permission to.
          required: true
          schema:
            type: string
          example: 5,6,7
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/phoneCalls/notification:
    post:
      operationId: post_api_v1_phoneCalls_notification
      tags:
        - calls (user context)
      summary: Create call notification
      description: |
        Broadcasts a phone-call notification (typically an incoming call) to the relevant technicians so their TANSS client pops up the call card. Used by external PBX bridges that don't run their own websocket subscription. Returns the notification payload as accepted. Requires basic phone-call permissions.
      requestBody:
        description: Phone-call notification payload.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              phoneNumber: '+4915112345678'
              direction: INCOMING
              employeeId: 42
              companyId: 5
              date: 1716700800000
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  phoneNumber: '+4915112345678'
                  direction: INCOMING
                  employeeId: 42
                  companyId: 5
                  date: 1716700800000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/phoneCalls/notification/close:
    post:
      operationId: post_api_v1_phoneCalls_notification_close
      security:
        - PhoneToken: []
        - ApiTokenAuth: []
      tags:
        - calls (user context)
      summary: Close call notification
      description: |
        Dismisses the calling employee's currently displayed phone-call notification (e.g. after the call has ended or the user clicked away). Sends a server-side close event to all subscribed clients of that user. Requires basic phone-call permissions.
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/phoneCalls/popUp:
    post:
      operationId: post_api_v1_phoneCalls_popUp
      tags:
        - calls (user context)
      summary: Pop up action
      description: |
        Builds the data shown in the TANSS call pop-up for the given phone call: looks up the customer/company by number, lists the employee's recent tickets with that company, and returns a object ready to render. Filters strip fields the calling user is not allowed to see. Requires basic phone-call permissions.
      requestBody:
        description: Phone-call descriptor for which the pop-up should be built. Only `phoneNumber` is strictly required; other fields refine the lookup.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              phoneNumber: '+4915112345678'
              direction: INCOMING
              employeeId: 42
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  phoneNumber: '+4915112345678'
                  companyId: 5
                  companyName: Beispiel GmbH
                  employeeId: 42
                  recentTickets:
                    - id: 1234
                      title: Druckerproblem
                    - id: 1240
                      title: VPN bricht ab
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/planning/overview:
    put:
      operationId: put_api_v1_planning_overview
      tags:
        - planning
      summary: Get planning overview
      description: |
        Returns the combined planning overview (capacity vs. scheduled work) for a list of technicians over a given timeframe: their absences, fix and proposed appointments, contract tasks and their open tickets whose due date or deadline falls in the window. The configuration must contain at least `employeeIds` and a complete `timeframe`; appointments belonging to each ticket are eagerly attached.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timeframe:
                  type: object
                  description: Time range (from/to) the planning overview covers
                employeeIds:
                  type: array
                  description: Identifiers of the employees to include in the overview
                  items:
                    type: object
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: 'Aggregated planning data: absences, appointments, tasks and tickets per employee.'
              example:
                meta: {}
                content:
                  absences: []
                  appointments:
                    - id: 5004
                      employeeId: 5
                      ticketId: 4711
                      date: 1748256000
                      duration: 60
                      planningType: APPOINTMENT_FIX
                  tasks: []
                  tickets:
                    - id: 4711
                      title: Server reboot
                      companyId: 100023
                      assignedToEmployeeId: 5
                      deadlineDate: 1748342400
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/popUpNotifications:
    get:
      operationId: get_api_v1_popUpNotifications
      tags:
        - popup notifications
      summary: Get all notifications for user
      description: |
        Returns the pop-up notification container for the logged-in user, including their current Do-Not-Disturb
        state and all unconfirmed notifications. Newly arrived notifications are evaluated first so they appear in
        the same response.

        Requires an authenticated session.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: object with `dndActive` flag and a list of notifications.
              example:
                meta: {}
                content:
                  dndActive: false
                  notifications:
                    - linkTypeId: 1
                      linkId: 100023
                      employeeId: 42
                      notifyAfter: 1748256000
                      confirmedDate: 0
                      title: Beispiel-Erinnerung
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/popUpNotifications/check:
    get:
      operationId: get_api_v1_popUpNotifications_check
      tags:
        - popup notifications
      summary: Check for new notifications
      description: |
        Polls for any newly-due pop-up notifications for the logged-in user (notifications whose `notifyAfter`
        timestamp has passed but that have not been confirmed yet). Used by the client's notification ticker
        to receive incremental updates without re-fetching the full container.

        Requires an authenticated session.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of newly-due object items.
              example:
                meta: {}
                content:
                  - linkTypeId: 1
                    linkId: 100023
                    employeeId: 42
                    notifyAfter: 1748256000
                    confirmedDate: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/popUpNotifications/confirm:
    put:
      operationId: put_api_v1_popUpNotifications_confirm
      tags:
        - popup notifications
      summary: Confirm notification
      description: |
        Marks a pop-up notification as confirmed (dismissed) by setting its `confirmedDate` to now. The notification
        is located via the (`linkId`, `linkTypeId`) pair scoped to the logged-in user, so users cannot confirm
        other users' notifications. Throws `OBJECT_NOT_FOUND` if no matching unconfirmed notification exists.
      requestBody:
        description: An object identifying the notification to confirm.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                linkId:
                  type: integer
                  description: Identifier of the linked entity the notification refers to
                linkTypeId:
                  type: integer
                  description: Type identifier of the linked entity
                delayInMin:
                  type: integer
                  description: Delay in minutes before the notification pops up
            example:
              linkId: 100023
              linkTypeId: 1
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty content; only `meta.text = UPDATED` is set.
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/popUpNotifications/delay:
    put:
      operationId: put_api_v1_popUpNotifications_delay
      tags:
        - popup notifications
      summary: Delay notification
      description: |
        Postpones a pop-up notification by setting its `notifyAfter` to `now + delayInMin * 60s`. Used by the
        "snooze" action on the client. The notification is located via the (`linkId`, `linkTypeId`) pair scoped
        to the logged-in user.
      requestBody:
        description: An object containing the link id/type and the desired `delayInMin`.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                linkId:
                  type: integer
                  description: Identifier of the linked entity the notification refers to
                linkTypeId:
                  type: integer
                  description: Type identifier of the linked entity
                delayInMin:
                  type: integer
                  description: Delay in minutes before the notification pops up
            example:
              linkId: 100023
              linkTypeId: 1
              delayInMin: 15
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty content; only `meta.text = UPDATED` is set.
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/priorities:
    get:
      operationId: get_api_v1_priorities
      tags:
        - ticket priorities
      summary: Get all entities
      description: |-
        Returns the full list of ticket priorities ordered by `sortOrder`. Priorities are
        a customer-configurable enum used to flag urgency on tickets and SLAs. Open to
        any authenticated user — write operations require the
        `SERVICE_LEVEL_AGREEMENT_ADMINISTRATION` permission.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: List of priorities, ordered by `sortOrder`.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Low
                    sortOrder: 1
                    active: true
                  - id: 2
                    name: Normal
                    sortOrder: 2
                    active: true
                  - id: 3
                    name: High
                    sortOrder: 3
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_priorities
      tags:
        - ticket priorities
      summary: Create entity
      description: |-
        Creates a new ticket priority. The new priority is automatically appended at
        the end of the `sortOrder` sequence. Requires the
        `SERVICE_LEVEL_AGREEMENT_ADMINISTRATION` permission; the caller must also be a
        technician or freelancer.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the priority.
                name:
                  type: string
                  description: Display name of the priority.
                sortOrder:
                  type: integer
                  description: Position used to order priorities in lists.
                active:
                  type: boolean
                  description: Whether the priority is currently active and selectable.
            example:
              id: 42
              name: Example name
              sortOrder: 1
              active: false
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created priority.
              example:
                meta: {}
                content:
                  id: 4
                  name: Critical
                  sortOrder: 4
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/priorities/sort:
    put:
      operationId: put_api_v1_priorities_sort
      tags:
        - ticket priorities
      summary: Sort priorities
      description: |-
        Reorders ticket priorities by applying the `sortOrder` values from the request
        payload. Each item must reference an existing priority id. Requires the
        `SERVICE_LEVEL_AGREEMENT_ADMINISTRATION` permission; the caller must also be a
        technician or freelancer. Fails 400 if the body is empty.
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - id: 1
                sortOrder: 3
              - id: 2
                sortOrder: 1
              - id: 3
                sortOrder: 2
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty — confirmation is in `meta.text`.
              example:
                meta: {}
                content: null
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/priorities/{id}:
    delete:
      operationId: delete_api_v1_priorities_id
      tags:
        - ticket priorities
      summary: Delete entity
      description: |-
        Deletes a ticket priority by id. Fails if any active ticket still references this
        priority (linked-entity delete check). Requires the
        `SERVICE_LEVEL_AGREEMENT_ADMINISTRATION` permission.
      parameters:
        - in: path
          name: id
          description: Id of the ticket priority.
          example: '42'
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_priorities_id
      tags:
        - ticket priorities
      summary: Get entity
      description: Returns a single ticket priority by id. Available to any authenticated user.
      parameters:
        - in: path
          name: id
          description: Id of the ticket priority.
          example: '42'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The priority.
              example:
                meta: {}
                content:
                  id: 2
                  name: Normal
                  sortOrder: 2
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_priorities_id
      tags:
        - ticket priorities
      summary: Edit entity
      description: |-
        Updates fields of an existing ticket priority (name, active flag, sortOrder).
        Requires the `SERVICE_LEVEL_AGREEMENT_ADMINISTRATION` permission.
      parameters:
        - in: path
          name: id
          description: Id of the ticket priority.
          example: '42'
          required: true
          schema:
            type: string
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the priority.
                name:
                  type: string
                  description: Display name of the priority.
                sortOrder:
                  type: integer
                  description: Position used to order priorities in lists.
                active:
                  type: boolean
                  description: Whether the priority is currently active and selectable.
            example:
              id: 42
              name: Example name
              sortOrder: 1
              active: false
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The priority.
              example:
                meta: {}
                content:
                  id: 2
                  name: Normal
                  sortOrder: 2
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/projects/phases:
    post:
      operationId: post_api_v1_projects_phases
      tags:
        - projects
      summary: Create project phase
      description: |-
        Creates a new phase inside a project. The request body must include the parent
        `projectId`; the caller must have access to that project. Phases let
        sub-tickets be grouped by stage (planning, implementation, billing, etc.) and
        can carry their own billing and clearance settings.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the project phase.
                projectId:
                  type: integer
                  description: Identifier of the project this phase belongs to.
                rank:
                  type: integer
                  description: Ordering rank of the phase within the project.
                name:
                  type: string
                  description: Display name of the project phase.
                startDate:
                  type: integer
                  format: int64
                  description: Start date of the phase as a Unix timestamp.
                endDate:
                  type: integer
                  format: int64
                  description: End date of the phase as a Unix timestamp.
                closedPrePhasesRequired:
                  type: boolean
                  description: Whether all preceding phases must be closed before this one can start.
                billingType:
                  type: string
                  description: Billing mode governing how work in the phase is invoiced.
                  enum:
                    - DEFAULT
                    - TICKET_MUST_BE_CLOSED
                    - ALL_TICKETS_MUST_BE_CLOSED
                clearanceMode:
                  type: string
                  description: Clearance mode controlling whether tickets in the phase may be cleared.
                  enum:
                    - DEFAULT
                    - DONT_CLEAR_SUPPORTS
                    - MAY_CLEAR_SUPPORTS
            example:
              id: 42
              projectId: 1
              rank: 1
              name: Example name
              startDate: 1748256000
              endDate: 1748256000
              closedPrePhasesRequired: false
              billingType:
                value: 1
              clearanceMode:
                value: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created project phase.
              example:
                meta: {}
                content:
                  id: 42
                  projectId: 5101
                  rank: 1
                  name: Planung
                  startDate: 1748256000
                  endDate: 1748860800
                  closedPrePhasesRequired: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/projects/phases/{phaseId}:
    delete:
      operationId: delete_api_v1_projects_phases_phaseId
      tags:
        - projects
      summary: Delete project phase
      description: |-
        Removes a phase from a project. The deletion fails if the phase still has child tickets linked.
        Permissions are checked against the parent project's access rules.
      parameters:
        - in: path
          name: phaseId
          description: Id of the project phase to delete.
          example: 12
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_projects_phases_phaseId
      tags:
        - projects
      summary: Update project phase
      description: |-
        Updates a project phase (name, dates, billing/clearance settings, rank). When
        `adjustStart` / `adjustEnd` are set, neighbouring phases are automatically
        shifted to keep the project timeline consistent. The caller must have access to
        the parent project.
      parameters:
        - in: path
          name: phaseId
          description: Id of the project phase to update.
          example: 12
          required: true
          schema:
            type: integer
        - in: query
          name: adjustStart
          description: When true, shift neighbouring phases to keep the timeline consistent after changing this phase's start.
          example: true
          required: false
          schema:
            type: boolean
            default: false
        - in: query
          name: adjustEnd
          description: When true, shift neighbouring phases to keep the timeline consistent after changing this phase's end.
          example: true
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the project phase.
                projectId:
                  type: integer
                  description: Identifier of the project this phase belongs to.
                rank:
                  type: integer
                  description: Ordering rank of the phase within the project.
                name:
                  type: string
                  description: Display name of the project phase.
                startDate:
                  type: integer
                  format: int64
                  description: Start date of the phase as a Unix timestamp.
                endDate:
                  type: integer
                  format: int64
                  description: End date of the phase as a Unix timestamp.
                closedPrePhasesRequired:
                  type: boolean
                  description: Whether all preceding phases must be closed before this one can start.
                billingType:
                  type: string
                  description: Billing mode governing how work in the phase is invoiced.
                  enum:
                    - DEFAULT
                    - TICKET_MUST_BE_CLOSED
                    - ALL_TICKETS_MUST_BE_CLOSED
                clearanceMode:
                  type: string
                  description: Clearance mode controlling whether tickets in the phase may be cleared.
                  enum:
                    - DEFAULT
                    - DONT_CLEAR_SUPPORTS
                    - MAY_CLEAR_SUPPORTS
            example:
              id: 42
              projectId: 1
              rank: 1
              name: Example name
              startDate: 1748256000
              endDate: 1748256000
              closedPrePhasesRequired: false
              billingType:
                value: 1
              clearanceMode:
                value: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated project phase.
              example:
                meta: {}
                content:
                  id: 42
                  projectId: 5101
                  rank: 2
                  name: Migration durchführen
                  startDate: 1748256000
                  endDate: 1750848000
                  closedPrePhasesRequired: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/projects/{projectId}/phaseInit:
    get:
      operationId: get_api_v1_projects_projectId_phaseInit
      tags:
        - projects
      summary: Get new phase start date
      description: |-
        Returns initialisation data for creating a new phase in a project — typically
        the next free `startDate` (end of the last existing phase) plus defaults for
        billing and clearance. Pre-fills the "Neue Phase" dialog.
      parameters:
        - in: path
          name: projectId
          description: Id of the project a new phase is being initialised for.
          example: 900
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Suggested defaults for the new phase.
              example:
                meta: {}
                content:
                  startDate: 1748256000
                  endDate: 1750848000
                  rank: 3
                  defaultBillingType: 1
                  defaultClearanceMode: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/projects/{projectId}/phases:
    get:
      operationId: get_api_v1_projects_projectId_phases
      tags:
        - projects
      summary: Get phases from project
      description: |-
        Returns all phases of a project ordered by rank, together with extras (linked
        tickets and supports) needed by the phase Gantt view. The caller must have
        access to the project.
      parameters:
        - in: path
          name: projectId
          description: Id of the project whose phases should be returned.
          example: 900
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Phases of the project, ordered by rank.
              example:
                meta: {}
                content:
                  - id: 41
                    projectId: 5101
                    rank: 1
                    name: Planung
                    startDate: 1748256000
                    endDate: 1748860800
                  - id: 42
                    projectId: 5101
                    rank: 2
                    name: Migration
                    startDate: 1748860800
                    endDate: 1750848000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/projects/{projectId}/status:
    get:
      operationId: get_api_v1_projects_projectId_status
      tags:
        - projects
      summary: Get project status
      description: |-
        Returns aggregated status information for a project — overall progress, number
        of open vs. done sub-tickets, budget consumption — used to render the project
        header KPIs. Requires the caller to be a technician or freelancer and to have
        access to the project.
      parameters:
        - in: path
          name: projectId
          description: Id of the project whose aggregated status should be returned.
          example: 900
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Aggregated project KPIs.
              example:
                meta: {}
                content:
                  projectId: 5101
                  ticketCountTotal: 24
                  ticketCountOpen: 7
                  ticketCountDone: 17
                  budgetMinutesTotal: 2400
                  budgetMinutesUsed: 1530
                  percentDone: 71
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/projects/{projectId}/tickets:
    get:
      operationId: get_api_v1_projects_projectId_tickets
      tags:
        - projects
      summary: Get tickets from project
      description: |-
        Returns the sub-tickets and appointments belonging to a project, used to render
        the "Mini-Ticketliste" panel inside the project detail view. The caller must
        have access to the project.
      parameters:
        - in: path
          name: projectId
          description: Id of the project whose sub-tickets should be returned.
          example: 900
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Sub-tickets of the project.
              example:
                meta: {}
                content:
                  - id: 4711
                    companyId: 100023
                    title: Festplatte defekt
                    statusId: 1
                    typeId: 1
                    projectId: 5101
                    phaseId: 42
                    assignedToEmployeeId: 5
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/qr:
    put:
      operationId: put_api_v1_qr
      tags:
        - device management
      summary: Get qr code for assignments
      description: |
        Generates a single PDF containing QR codes for a batch of device assignments (PC, periphery, component, etc.). When the `Accept` header is `application/pdf` the PDF is streamed directly; otherwise a file-pass key is returned for asynchronous download. Assignments the caller has no access to are silently skipped.
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - text: Example content
                extras: {}
                linkedEntities: {}
                assignments:
                  infos: {}
                properties:
                  fields: {}
                  extras: {}
                  permissions: {}
                  editable: false
                  message: Example content
                pagination:
                  itemsPerPage: 1
                  totalItems: 1
                  page: 1
                listProperties: {}
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: File-pass response pointing to the generated QR-code PDF (when not requesting application/pdf directly).
              example:
                meta: {}
                content:
                  fileKey: a5f3b2c1-9d11-4e02-8e3a-1f3c8b9a0e21
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/qr/{linkTypeId}/{linkId}:
    get:
      operationId: get_api_v1_qr_linkTypeId_linkId
      tags:
        - device management
      summary: Get qr code for single assignment
      description: |
        Generates a QR-code PDF for a single device assignment identified by linkTypeId + linkId. Access to the assignment is verified first. With `Accept: application/pdf` the PDF is returned directly; otherwise a file-pass response is returned.
      parameters:
        - in: path
          name: linkTypeId
          description: Link type of the device assignment (e.g. 1 = pc).
          required: true
          schema:
            type: integer
          example: 1
        - in: path
          name: linkId
          description: Link id of the device assignment.
          required: true
          schema:
            type: integer
          example: 100
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: File-pass response pointing to the generated QR-code PDF (when not requesting application/pdf directly).
              example:
                meta: {}
                content:
                  fileKey: a5f3b2c1-9d11-4e02-8e3a-1f3c8b9a0e21
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/recurrence:
    post:
      operationId: post_api_v1_recurrence
      tags:
        - recurrence
      summary: Create recurrence rule
      description: |
        Stores a new RRULE-based recurrence definition that drives repeating appointments / supports. Requires a start date and a valid assignment (linkTypeId/linkId) that the caller has access to; only technicians or freelancers may create rules. After persisting, the calculated occurrences are pre-computed for the rule.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - rrule
              properties:
                id:
                  type: integer
                  description: Unique identifier of the recurrence rule.
                linkTypeId:
                  type: integer
                  description: Type of the linked object the rule is attached to.
                linkId:
                  type: integer
                  description: Identifier of the linked object the rule applies to.
                rrule:
                  type: string
                  description: Recurrence pattern expressed as an iCalendar RRULE string.
                startDate:
                  type: integer
                  format: int64
                  description: Start of the recurrence as a Unix timestamp.
                endDate:
                  type: integer
                  format: int64
                  description: End of the recurrence as a Unix timestamp.
                employeeIds:
                  type: array
                  description: Identifiers of the employees assigned to the recurrence.
                  items:
                    type: object
            example:
              id: 42
              linkTypeId: 1
              linkId: 1
              rrule: string
              startDate: 1748256000
              endDate: 1748256000
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The newly created recurrence rule.
              example:
                meta: {}
                content:
                  id: 1
                  rrule: FREQ=WEEKLY;BYDAY=MO;UNTIL=20260101T000000Z
                  startDate: 1748256000
                  endDate: 1779792000
                  linkTypeId: 1
                  linkId: 4711
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/recurrence/assignment:
    post:
      operationId: post_api_v1_recurrence_assignment
      tags:
        - recurrence
      summary: Create recurrence assignment
      description: |
        Links an existing entity (typically a support) to a recurrence rule, so the occurrence is treated as "converted" into that concrete entity. Caller needs access both to the rule and to the target assignment.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - ruleId
                - linkTypeId
                - linkId
              properties:
                ruleId:
                  type: integer
                  description: Identifier of the recurrence rule this assignment belongs to.
                linkTypeId:
                  type: integer
                  description: Type of the linked entity the recurrence is assigned to.
                linkId:
                  type: integer
                  description: Identifier of the linked entity the recurrence is assigned to.
                excludeId:
                  type: integer
                  description: Optional identifier of an exclusion applied to this assignment.
            example:
              ruleId: 1
              linkTypeId: 1
              linkId: 1
              excludeId: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created recurrence assignment.
              example:
                meta: {}
                content:
                  ruleId: 1
                  linkTypeId: 1
                  linkId: 4711
                  excludeId: 5
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/recurrence/assignment/{ruleId}/{linkTypeId}/{linkId}:
    delete:
      operationId: delete_api_v1_recurrence_assignment_ruleId_linkTypeId_linkId
      tags:
        - recurrence
      summary: Delete recurrence assignment
      description: |
        Removes the link between a rule and a concrete entity identified by the composite (ruleId, linkTypeId, linkId). If the linked support was a converted appointment it is deleted as well. Note: the related exclude is intentionally kept so the occurrence does not reappear in the calendar.
      parameters:
        - in: path
          name: ruleId
          required: true
          description: Id of the recurrence rule.
          example: 1
          schema:
            type: integer
        - in: path
          name: linkTypeId
          required: true
          description: Link type id of the assigned entity.
          example: 1
          schema:
            type: integer
        - in: path
          name: linkId
          required: true
          description: Id of the linked entity.
          example: 4711
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/recurrence/exclude:
    post:
      operationId: post_api_v1_recurrence_exclude
      tags:
        - recurrence
      summary: Create recurrence exclude
      description: |
        Excludes a single occurrence of a recurrence rule by timestamp (or by `sequenceId`, which is resolved against the pre-calculated items). May optionally carry assignments so the excluded occurrence is converted into a new linked entity (e.g. a support). Triggers SUPPORT_DELETED webhook events when no replacement assignment is given.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the recurrence exclusion.
                ruleId:
                  type: integer
                  description: Identifier of the recurrence rule this exclusion applies to.
                timestamp:
                  type: integer
                  format: int64
                  description: Unix timestamp of the excluded occurrence.
                isoDateString:
                  type: string
                  description: Excluded occurrence date in ISO date format.
                employeeId:
                  type: integer
                  description: Identifier of the employee who created the exclusion.
                indexed:
                  type: integer
                  format: int64
                  description: Timestamp indicating when the exclusion was indexed.
            example:
              id: 42
              ruleId: 1
              timestamp: 1748256000
              isoDateString: string
              employeeId: 1
              indexed: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created recurrence exclude.
              example:
                meta: {}
                content:
                  id: 5
                  ruleId: 1
                  timestamp: 1748860800
                  isoDateString: '2026-06-02T08:00:00Z'
                  employeeId: 17
                  indexed: 1748860800
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/recurrence/query:
    put:
      operationId: put_api_v1_recurrence_query
      tags:
        - recurrence
      summary: Get recurrence calculations
      description: |
        Expands recurrence rules into concrete occurrences for the given timeframe and employee list. Excludes are subtracted per employee, and when `checkEmployeesInSupport` is true, occurrences whose underlying support does not include the employee are filtered out as well. Restricted to technicians / freelancers.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timeframe:
                  type: object
                  description: Time window (from/to timestamps) within which recurrences are calculated.
                ruleIds:
                  type: array
                  description: Identifiers of the recurrence rules to query.
                  items:
                    type: object
                employeeIds:
                  type: array
                  description: Identifiers of the employees to restrict the query to.
                  items:
                    type: object
                checkEmployeesInSupport:
                  type: boolean
                  description: If true, also checks which employees are assigned to the recurrence rule's master and linked employees.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Expanded recurrence calculations per employee, plus assignment information for already converted excludes.
              example:
                meta: {}
                content:
                  items:
                    - employeeId: 17
                      ruleId: 1
                      timestamp: 1748256000
                    - employeeId: 17
                      ruleId: 1
                      timestamp: 1748860800
                  assignments:
                    - employeeId: 17
                      ruleId: 1
                      linkTypeId: 1
                      linkId: 4711
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/recurrence/readableText:
    post:
      operationId: post_api_v1_recurrence_readableText
      tags:
        - recurrence
      summary: Get readable string
      description: |
        Returns a human-readable description of a recurrence rule (e.g. "every Monday until 2026-01-01") for display in the UI. The rule itself is not persisted; this is a formatting helper.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rrule
              properties:
                id:
                  type: integer
                  description: Unique identifier of the recurrence rule.
                linkTypeId:
                  type: integer
                  description: Type of the linked object the rule is attached to.
                linkId:
                  type: integer
                  description: Identifier of the linked object the rule applies to.
                rrule:
                  type: string
                  description: Recurrence pattern expressed as an iCalendar RRULE string.
                startDate:
                  type: integer
                  format: int64
                  description: Start of the recurrence as a Unix timestamp.
                endDate:
                  type: integer
                  format: int64
                  description: End of the recurrence as a Unix timestamp.
                employeeIds:
                  type: array
                  description: Identifiers of the employees assigned to the recurrence.
                  items:
                    type: object
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: string
                    description: Human-readable representation of the recurrence rule.
              example:
                meta: {}
                content: Every Monday until 2026-01-01
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/recurrence/{ruleId}:
    delete:
      operationId: delete_api_v1_recurrence_ruleId
      tags:
        - recurrence
      summary: Delete recurrence rule
      description: |
        Removes a recurrence rule together with its excludes, assignments and pre-calculated occurrences. Only technicians or freelancers with access to the rule's assignment may delete it.
      parameters:
        - in: path
          name: ruleId
          required: true
          description: Id of the recurrence rule.
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_recurrence_ruleId
      tags:
        - recurrence
      summary: Get recurrence rule
      description: |
        Returns a single recurrence rule by id, including the attached excludes, assignments and pre-calculated occurrences that are decorated for output.
      parameters:
        - in: path
          name: ruleId
          required: true
          description: Id of the recurrence rule.
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The recurrence rule with its decorated excludes, assignments and calculated occurrences.
              example:
                meta: {}
                content:
                  id: 1
                  rrule: FREQ=WEEKLY;BYDAY=MO;UNTIL=20260101T000000Z
                  startDate: 1748256000
                  endDate: 1779792000
                  linkTypeId: 1
                  linkId: 4711
                  excluded: []
                  assignments: []
                  calculated: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_recurrence_ruleId
      tags:
        - recurrence
      summary: Update recurrence rule
      description: |
        Updates the RRULE, start or end of a recurrence rule. The assignment (linkTypeId/linkId) is immutable on update. If the timing changes the pre-calculated occurrences are rebuilt; if `excludeDelta` is set, existing excludes are shifted accordingly.
      parameters:
        - in: path
          name: ruleId
          required: true
          description: Id of the recurrence rule.
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - rrule
              properties:
                id:
                  type: integer
                  description: Unique identifier of the recurrence rule.
                linkTypeId:
                  type: integer
                  description: Type of the linked object the rule is attached to.
                linkId:
                  type: integer
                  description: Identifier of the linked object the rule applies to.
                rrule:
                  type: string
                  description: Recurrence pattern expressed as an iCalendar RRULE string.
                startDate:
                  type: integer
                  format: int64
                  description: Start of the recurrence as a Unix timestamp.
                endDate:
                  type: integer
                  format: int64
                  description: End of the recurrence as a Unix timestamp.
                employeeIds:
                  type: array
                  description: Identifiers of the employees assigned to the recurrence.
                  items:
                    type: object
            example:
              id: 42
              linkTypeId: 1
              linkId: 1
              rrule: string
              startDate: 1748256000
              endDate: 1748256000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The recurrence rule with its decorated excludes, assignments and calculated occurrences.
              example:
                meta: {}
                content:
                  id: 1
                  rrule: FREQ=WEEKLY;BYDAY=MO;UNTIL=20260101T000000Z
                  startDate: 1748256000
                  endDate: 1779792000
                  linkTypeId: 1
                  linkId: 4711
                  excluded: []
                  assignments: []
                  calculated: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/remoteSupports:
    put:
      operationId: put_api_v1_remoteSupports
      tags:
        - remote supports
      summary: List remote-support sessions (TANSS internal)
      description: |-
        Returns recorded remote-support sessions (TeamViewer, AnyDesk, IslOnline, PCVisit, …) matching the filter in the body — used by
        the TANSS web UI. Requires the `REMOTE` module to be licensed; further per-entity company-access filtering is enforced.
        PUT is used so the filter object can live in the request body.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timeframe:
                  type: object
                  description: Time range used to constrain the remote maintenance query.
                employeeId:
                  type: integer
                  description: Identifier of a single employee to filter by.
                employeeIds:
                  type: array
                  description: Identifiers of multiple employees to filter by.
                  items:
                    type: object
                companyId:
                  type: integer
                  description: Identifier of the company to filter by.
                typeId:
                  type: integer
                  description: Identifier of the remote maintenance type to filter by.
                text:
                  type: string
                  description: Free-text search term used to filter results.
                onlyExternalAllowed:
                  type: boolean
                  description: Whether to include only externally allowed remote maintenance entries.
                permissionChecks:
                  type: boolean
                  description: Whether permission checks are applied to the query.
            example:
              text: Example content
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of remote-support sessions matching the filter, after company-access checks.
              example:
                meta: {}
                content:
                  - id: 1
                    supportId: 5004
                    sessionTool: TEAMVIEWER
                    sessionId: '1234567890'
                    startedAt: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/remoteSupports/configuration:
    put:
      operationId: put_api_v1_remoteSupports_configuration
      tags:
        - remote supports
      summary: Update remote-support provider configuration
      description: |-
        Persists the configuration for a remote-support provider (endpoint, token, fetching flags). Typically called after a successful
        `configuration/check`. Restricted to users with the `ONLINE_SYSTEM_CONFIGURATION` permission or technician/freelancer role
        (OSK admin scope).
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: Remote maintenance provider to check against.
                  enum:
                    - TEAMVIEWER
                    - FASTVIEWER
                    - PCVISIT
                    - GO2ASSIST
                    - REMOTEDESKTOPMANAGER
                    - ANYDESK
                    - ISL
                host:
                  type: string
                  description: Hostname or address of the remote maintenance server.
                port:
                  type: integer
                  description: Network port used to reach the remote maintenance server.
                username:
                  type: string
                  description: Username for authenticating against the remote maintenance service.
                password:
                  type: string
                  description: Password for authenticating against the remote maintenance service.
                licenseId:
                  type: string
                  description: License identifier used for the AnyDesk provider.
                accessToken:
                  type: string
                  description: Access token used for the TeamViewer provider.
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty — only the meta envelope is returned.
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/remoteSupports/configuration/check:
    put:
      operationId: put_api_v1_remoteSupports_configuration_check
      tags:
        - remote supports
      summary: Validate remote-support provider configuration
      description: |-
        Dry-runs the credentials/parameters for a remote-support provider (e.g. TeamViewer API token, AnyDesk endpoint) by attempting an
        authenticated probe call. Returns the literal string `"OK"` on success; otherwise returns an error with the provider's
        error message. Restricted to technicians/freelancers or users with the `ONLINE_SYSTEM_CONFIGURATION` permission (OSK admin).
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: Remote maintenance provider to check against.
                  enum:
                    - TEAMVIEWER
                    - FASTVIEWER
                    - PCVISIT
                    - GO2ASSIST
                    - REMOTEDESKTOPMANAGER
                    - ANYDESK
                    - ISL
                host:
                  type: string
                  description: Hostname or address of the remote maintenance server.
                port:
                  type: integer
                  description: Network port used to reach the remote maintenance server.
                username:
                  type: string
                  description: Username for authenticating against the remote maintenance service.
                password:
                  type: string
                  description: Password for authenticating against the remote maintenance service.
                licenseId:
                  type: string
                  description: License identifier used for the AnyDesk provider.
                accessToken:
                  type: string
                  description: Access token used for the TeamViewer provider.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Literal string `"OK"` on a successful probe.
              example:
                meta: {}
                content: OK
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/remoteSupports/configuration/{type}:
    get:
      operationId: get_api_v1_remoteSupports_configuration_type
      tags:
        - remote supports
      summary: Get remote-support provider configuration
      description: |-
        Returns the stored configuration parameters (endpoint, credentials placeholders, fetching flags) for the requested provider
        `type` — e.g. `TEAMVIEWER`, `ANYDESK`, `ISL_ONLINE`. Intended for the OSK admin screen, so it requires either the
        `ONLINE_SYSTEM_CONFIGURATION` permission or technician/freelancer role.
      parameters:
        - in: path
          name: type
          description: Remote-support provider type, e.g. TEAMVIEWER, ANYDESK, ISL_ONLINE.
          required: true
          schema:
            type: string
          example: TEAMVIEWER
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Configuration parameters of the requested provider.
              example:
                meta: {}
                content:
                  id: 1
                  supportId: 5004
                  sessionTool: TEAMVIEWER
                  sessionId: '1234567890'
                  startedAt: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/remoteSupports/import:
    put:
      operationId: put_api_v1_remoteSupports_import
      tags:
        - remote supports
      summary: Trigger remote-support import
      description: |-
        Triggers a synchronous fetch+import of remote-support sessions from the configured external provider matching the
        query parameters body (type, timeframe). Used to manually re-run an import when the scheduled fetcher missed a
        session. Restricted to users with `ONLINE_SYSTEM_CONFIGURATION` or technician/freelancer role.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                remoteMaintenanceType:
                  type: string
                  description: Remote maintenance provider whose sessions should be fetched.
                  enum:
                    - TEAMVIEWER
                    - FASTVIEWER
                    - PCVISIT
                    - GO2ASSIST
                    - REMOTEDESKTOPMANAGER
                    - ANYDESK
                    - ISL
                userId:
                  type: integer
                  description: Identifier of the user whose remote support sessions should be fetched.
                numberOfDays:
                  type: integer
                  description: Number of past days to include in the fetch.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty — only the meta envelope is returned.
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/roles/ticket/{id}:
    delete:
      operationId: delete_api_v1_roles_ticket_id
      tags:
        - ticket roles
      summary: Remove a role assignment from a ticket
      description: |
        Removes a single role assignment from a ticket — i.e. revokes the access a specific role grants a specific employee on that ticket. Verifies that the caller can access the ticket and the role-picker parameters, then deletes the matching object (link type `TICKET`, role type `EMPLOYEE`). After the deletion the route returns the current set of role assignments for the ticket, so the UI can refresh without a follow-up call.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the ticket whose role assignments are addressed.
          example: '4711'
          schema:
            type: string
      requestBody:
        description: Identifies which role assignment to remove from the ticket.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                employeeId:
                  type: integer
                  description: Id of the employee whose role assignment is removed.
                departmentId:
                  type: integer
                  description: Id of the department the assignment applies to (optional; used for department-level roles).
                roleId:
                  type: integer
                  description: Id of the role to revoke.
                kindOfInheritance:
                  type: string
                  description: How the assignment relates to inheritance across projects and sub-tickets.
                  enum:
                    - DEFAULT
                    - REVOKED_IN_PROJECT
                    - REVOKED_IN_SUB_TICKET
                    - OVERWRITTEN_IN_SUB_TICKET
            example:
              employeeId: 5
              roleId: 3
              kindOfInheritance: DEFAULT
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_roles_ticket_id
      tags:
        - ticket roles
      summary: List role assignments on a ticket
      description: |
        Returns all role assignments on the given ticket (which employees have which role on it). The response `meta` also carries role-picker properties used by the UI to render which roles can still be added or changed. The caller must be able to access the ticket; the underlying ticket access check is therefore enforced.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the ticket whose role assignments are addressed.
          example: '4711'
          schema:
            type: string
      responses:
        '200':
          description: Role assignments currently in effect on the ticket.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - ticketId: 4711
                    roleId: 1
                    employeeIds:
                      - 5
                      - 6
                  - ticketId: 4711
                    roleId: 2
                    employeeIds:
                      - 7
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_roles_ticket_id
      tags:
        - ticket roles
      summary: Add role assignments to a ticket
      description: |
        Adds one or more role assignments to a ticket in a single call (each item maps an employee to a role on this ticket and optionally describes the inheritance kind). Every assignment in the body is access-checked individually before persistence. Returns the resulting list of role assignments for the ticket so the UI can pick up the new state immediately.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the ticket whose role assignments are addressed.
          example: '4711'
          schema:
            type: string
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - text: Example content
                extras: {}
                linkedEntities: {}
                assignments:
                  infos: {}
                properties:
                  fields: {}
                  extras: {}
                  permissions: {}
                  editable: false
                  message: Example content
                pagination:
                  itemsPerPage: 1
                  totalItems: 1
                  page: 1
                listProperties: {}
      responses:
        '201':
          description: The updated set of role assignments for the ticket.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - ticketId: 4711
                    roleId: 1
                    employeeIds:
                      - 5
                      - 6
                  - ticketId: 4711
                    roleId: 2
                    employeeIds:
                      - 7
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_roles_ticket_id
      tags:
        - ticket roles
      summary: Change inheritance of a role assignment
      description: |
        Updates how an existing role assignment on a ticket is inherited (the `kindOfInheritance` flag — e.g. inherited from the company versus pinned directly on the ticket). The employee and role on the assignment are not changed; for those, use the DELETE + POST pair. The response again contains the full list of role assignments for the ticket.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the ticket whose role assignments are addressed.
          example: '4711'
          schema:
            type: string
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                employeeId:
                  type: integer
                  description: Identifier of the employee whose roles are being picked.
                departmentId:
                  type: integer
                  description: Identifier of the department scope for role selection.
                roleId:
                  type: integer
                  description: Identifier of the role being selected.
                kindOfInheritance:
                  type: string
                  description: How the role assignment is inherited or overridden.
                  enum:
                    - DEFAULT
                    - REVOKED_IN_PROJECT
                    - REVOKED_IN_SUB_TICKET
                    - OVERWRITTEN_IN_SUB_TICKET
      responses:
        '200':
          description: The updated set of role assignments for the ticket.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - ticketId: 4711
                    roleId: 1
                    employeeIds:
                      - 5
                      - 6
                  - ticketId: 4711
                    roleId: 2
                    employeeIds:
                      - 7
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/round/support/{mins}:
    get:
      operationId: get_api_v1_round_support_mins
      tags:
        - supports
      summary: Round a duration using the matching rounding rule
      description: Looks up the rounding rule (object) that matches the given context (location, company, support type, employee, contract) and applies it to `mins`. Used by the UI to display the duration that would actually be billed when the tech stops the stopwatch. Returns `NOT_FOUND` (no body content) when no rounding rule applies.
      parameters:
        - in: path
          name: mins
          required: true
          description: Raw duration in minutes to be rounded.
          schema:
            type: integer
            description: Raw duration in minutes to be rounded.
          example: 1
        - in: query
          name: location
          required: false
          description: Support location used to select the matching rounding rule.
          schema:
            type: string
            description: enumeration value (e.g. OFFICE, ON_SITE, REMOTE).
            default: OFFICE
          example: OFFICE
        - in: query
          name: companyId
          required: false
          description: Company context used to select the matching rounding rule; 0 means none.
          schema:
            type: integer
            default: 0
          example: 100023
        - in: query
          name: typeId
          required: false
          description: Support-type context used to select the matching rounding rule; 0 means none.
          schema:
            type: integer
            default: 0
          example: 1
        - in: query
          name: employeeId
          required: false
          description: Employee context used to select the matching rounding rule; 0 means none.
          schema:
            type: integer
            default: 0
          example: 5
        - in: query
          name: contractId
          required: false
          description: Contract context used to select the matching rounding rule; 0 means none.
          schema:
            type: integer
            default: 0
          example: 1
      responses:
        '200':
          description: Rounded duration, or empty body when no rounding rule matches.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      mins:
                        type: integer
              example:
                meta: {}
                content:
                  mins: 30
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/salesTarget/departments:
    get:
      operationId: get_api_v1_salesTarget_departments
      tags:
        - employees - departments
      summary: Get sales target departments
      description: |
        Returns the list of departments the caller may pick when querying or
        setting sales targets. The caller must be a technician or freelancer.
      responses:
        '200':
          description: Selectable departments for sales-target views.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
              example:
                meta: {}
                content:
                  - id: 3
                    name: Support
                  - id: 4
                    name: Sales
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/salesTarget/employees:
    get:
      operationId: get_api_v1_employees
      tags:
        - employees
      summary: Get sales target employees
      description: |
        Returns the list of employees the caller may select when querying or
        editing sales targets. The caller must be a technician or freelancer.
      responses:
        '200':
          description: Selectable employees for sales-target views.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee-Short'
              example:
                meta: {}
                content:
                  - id: 5
                    name: Max Mustermann
                    listType: TECHNICIAN
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/salesTarget/get:
    put:
      operationId: put_api_v1_salesTarget_get
      tags:
        - employees
      summary: Get sales target for employee or department
      description: |
        Returns the calculated sales-target result(s) for the given employee or
        department in the given month/year window. Caller must be a technician or
        freelancer; additional per-employee/-department access is verified.
      requestBody:
        description: Query parameters describing whose targets to fetch and for which timeframe.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                employeeId:
                  type: integer
                departmentId:
                  type: integer
                month:
                  type: integer
                  description: 1-12, or 0 for whole year
                year:
                  type: integer
                includeDepartmentValues:
                  type: boolean
                getAchievedWhenNoTargetIsSet:
                  type: boolean
            example:
              employeeId: 5
              departmentId: 0
              month: 0
              year: 2026
              includeDepartmentValues: true
              getAchievedWhenNoTargetIsSet: false
      responses:
        '200':
          description: Sales-target calculation results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        employeeId:
                          type: integer
                        target:
                          type: number
                        achieved:
                          type: number
                        percent:
                          type: number
              example:
                meta: {}
                content:
                  - employeeId: 5
                    target: 50000
                    achieved: 32000
                    percent: 64
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/salesTarget/set:
    put:
      operationId: put_api_v1_salesTarget_set
      tags:
        - employees
      summary: Update sales targets
      description: |
        Persists the given list of sales targets in one batch. Existing entries
        are updated, new ones are inserted. Caller must be a technician or
        freelancer and pass the admin permission check.
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  employeeId:
                    type: integer
                  month:
                    type: integer
                    description: 1-12
                  year:
                    type: integer
                  amount:
                    type: number
            example:
              - employeeId: 5
                month: 6
                year: 2026
                amount: 5000
      responses:
        '200':
          description: Result summary (created / updated counts).
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      created:
                        type: integer
                      updated:
                        type: integer
              example:
                meta: {}
                content:
                  created: 1
                  updated: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/search/api/v1/search/devices:
    get:
      operationId: get_api_v1_search_api_v1_search_devices
      tags:
        - search
      summary: Find devices
      description: |
        Full-text search for devices and personal computers matching `query`. The result
        list is filtered to remove devices the caller cannot see (company-access checks).

        Note: clients should use the
        unified `PUT /api/v1/search` route. This route is documented for backwards compatibility only.
      parameters:
        - in: query
          name: query
          required: true
          description: Full-text search term used to match devices and personal computers.
          schema:
            type: string
          example: Drucker
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: object containing matched devices and personal computers.
              example:
                meta: {}
                content:
                  devices:
                    - id: 42
                      name: Beispiel-Server-01
                      companyId: 100023
                  personalComputers:
                    - id: 17
                      name: Max-Mustermann-Laptop
                      companyId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/search/api/v1/search/employees:
    get:
      operationId: get_api_v1_search_api_v1_search_employees
      tags:
        - search
      summary: Find employees
      description: |
        Full-text search for employees (technicians, freelancers, customer contacts) matching `query`. The result
        list is filtered by company-access rules so callers only see employees they may view.

        Note: clients should use the
        unified `PUT /api/v1/search` route.
      parameters:
        - in: query
          name: query
          required: true
          description: Full-text search term used to match employees.
          schema:
            type: string
          example: Müller
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: object with matched employees and callback hints.
              example:
                meta: {}
                content:
                  employees:
                    - id: 42
                      name: Max Mustermann
                      companyId: 100023
                      email: max.mustermann@example.com
                      phone: +49 30 1234567
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/search/api/v1/search/knowledgebase:
    get:
      operationId: get_api_v1_search_api_v1_search_knowledgebase
      tags:
        - search
      summary: Find knowledge-base entries
      description: |
        Full-text search for knowledge-base (wiki) postings matching `query`. Result postings the caller cannot
        read (department / visibility restrictions) are filtered out.

        Note: clients should use the
        unified `PUT /api/v1/search` route.
      parameters:
        - in: query
          name: query
          required: true
          description: Full-text search term used to match knowledge-base entries.
          schema:
            type: string
          example: VPN einrichten
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: object with matched postings.
              example:
                meta: {}
                content:
                  postings:
                    - id: 42
                      title: 'Beispiel-Anleitung: VPN einrichten'
                      excerpt: Diese Anleitung beschreibt...
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/search/api/v1/search/mailaccounts:
    get:
      operationId: get_api_v1_search_api_v1_search_mailaccounts
      tags:
        - search
      summary: Find mail accounts
      description: |
        Full-text search for mail accounts matching `query`. Mail accounts the caller cannot administer are
        filtered out by the standard mail-account filter.

        Note: clients should use the
        unified `PUT /api/v1/search` route.
      parameters:
        - in: query
          name: query
          required: true
          description: Full-text search term used to match mail accounts.
          schema:
            type: string
          example: support
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of matched mail-account entries.
              example:
                meta: {}
                content:
                  - id: 42
                    address: support@example.com
                    companyId: 100023
                  - id: 43
                    address: info@example.com
                    companyId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/search/api/v1/search/supports:
    get:
      operationId: get_api_v1_search_api_v1_search_supports
      tags:
        - search
      summary: Find supports
      description: |
        Full-text search for support (time-tracking) records matching `query`. Results respect company-access rules.

        Note: clients should use the
        unified `PUT /api/v1/search` route.
      parameters:
        - in: query
          name: query
          required: true
          description: Full-text search term used to match support time-tracking records.
          schema:
            type: string
          example: Müller
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of matched object time-tracking records.
              example:
                meta: {}
                content:
                  - id: 42
                    description: VPN-Konfiguration bei Beispiel GmbH
                    employeeId: 17
                    companyId: 100023
                    date: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/search/api/v1/search/tickets:
    get:
      operationId: get_api_v1_search_api_v1_search_tickets
      tags:
        - search
      summary: Find tickets
      description: |
        Full-text search for tickets matching `query` (by ticket number, title, description, ...). Tickets the caller cannot access (company / department /
        visibility rules) are filtered out by the standard ticket filter.

        Note: clients should use the
        unified `PUT /api/v1/search` route.
      parameters:
        - in: query
          name: query
          required: true
          description: Full-text search term used to match tickets.
          schema:
            type: string
          example: Drucker
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of matched object results.
              example:
                meta: {}
                content:
                  - id: 100023
                    title: VPN funktioniert nicht
                    companyId: 42
                    statusId: 1
                    assignedToEmployeeId: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sla:
    get:
      operationId: get_api_v1_sla
      tags:
        - sla
      summary: Get all SLAs
      description: |
        Returns every Service-Level-Agreement template configured in the system. SLAs are referenced by contracts and tickets to derive reaction and deadline times. Requires the SERVICE_LEVEL_AGREEMENT_ADMINISTRATION permission.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of SLA templates.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Gold SLA
                    reactionTimeMinutes: 60
                    deadlineMinutes: 240
                    imagePath: sla/gold.svg
                  - id: 2
                    name: Silver SLA
                    reactionTimeMinutes: 240
                    deadlineMinutes: 1440
                    imagePath: sla/silver.svg
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_sla
      tags:
        - sla
      summary: Create SLA
      description: |
        Creates a new SLA template (name, image, reaction/deadline times, conditions are added separately). Requires the SERVICE_LEVEL_AGREEMENT_ADMINISTRATION permission and access to all companies.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the service level agreement.
                name:
                  type: string
                  description: Name of the service level agreement.
                description:
                  type: string
                  description: Descriptive text of the service level agreement.
                image:
                  type: string
                  description: Reference to the graphic representing the service level agreement.
                reactionTime:
                  type: integer
                  description: Guaranteed reaction time in hours.
                deadlineHours:
                  type: integer
                  description: Resolution deadline expressed in hours.
                deadlineDays:
                  type: integer
                  description: Resolution deadline expressed in days.
                priority:
                  type: integer
                  description: Priority ranking of the service level agreement.
                cost:
                  type: number
                  description: Cost associated with the service level agreement.
                buyingPrice:
                  type: number
                  description: Purchase price associated with the service level agreement.
                active:
                  type: boolean
                  description: Whether the service level agreement is currently active.
            example:
              name: Gold SLA
              description: 1h Reaktion, 4h Lösung
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created SLA.
              example:
                meta: {}
                content:
                  id: 3
                  name: Gold SLA
                  reactionTimeMinutes: 60
                  deadlineMinutes: 240
                  imagePath: sla/gold.svg
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_sla
      tags:
        - sla
      summary: Get SLA list
      description: |
        Returns SLAs filtered/sorted/paginated according to the configuration in the request body. The route is intended for the SLA administration list view; use GET for an unfiltered dump.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                searchText:
                  type: string
                  description: Free-text search term matched against SLA name and description
                active:
                  type: string
                  description: Filter for active, inactive, or both kinds of SLAs
                  enum:
                    - ACTIVE_ONLY
                    - INACTIVE_ONLY
                    - ACTIVE_AND_INACTIVE
                page:
                  type: integer
                  description: Page number of the paginated result, starting at 1
                itemsPerPage:
                  type: integer
                  description: Maximum number of items returned per page
                omitTotalCount:
                  type: boolean
                  description: Whether to skip calculating the total result count for performance
            example:
              searchText: Gold
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of SLAs matching the configuration.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Gold SLA
                    reactionTimeMinutes: 60
                    deadlineMinutes: 240
                    imagePath: sla/gold.svg
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sla/conditions/sort:
    put:
      operationId: put_api_v1_sla_conditions_sort
      tags:
        - sla
      summary: Sort conditions
      description: |
        Persists a new rank order for SLA conditions in bulk. The body is an array of `{id, rank}` records describing where each condition should land. Evaluation order matters: the first matching condition decides which SLA applies. Requires SERVICE_LEVEL_AGREEMENT_ADMINISTRATION.
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - id: 7
                rank: 1
              - id: 9
                rank: 2
              - id: 12
                rank: 3
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty payload; HTTP status indicates success.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sla/conditions/{id}:
    delete:
      operationId: delete_api_v1_sla_conditions_id
      tags:
        - sla
      summary: Delete condition
      description: |
        Removes a single SLA matching condition. SLAs are selected for a ticket by evaluating their conditions in rank order — deleting one changes which SLA applies. Requires SERVICE_LEVEL_AGREEMENT_ADMINISTRATION.
      parameters:
        - in: path
          name: id
          description: ID of the SLA condition.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_sla_conditions_id
      tags:
        - sla
      summary: Get single condition
      description: |
        Returns one SLA condition by id (field, operator, value, rank).
      parameters:
        - in: path
          name: id
          description: ID of the SLA condition.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Single SLA condition.
              example:
                meta: {}
                content:
                  id: 7
                  slaId: 1
                  field: ticketType
                  operator: EQUALS
                  value: incident
                  rank: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_sla_conditions_id
      tags:
        - sla
      summary: Update condition
      description: |
        Modifies an existing SLA condition (field, operator, comparison value, rank). Requires SERVICE_LEVEL_AGREEMENT_ADMINISTRATION.
      parameters:
        - in: path
          name: id
          description: ID of the SLA condition.
          required: true
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the SLA condition
                slaId:
                  type: integer
                  description: Identifier of the SLA this condition belongs to
                reactionTime:
                  type: integer
                  description: Reaction time in hours
                reactionTimeMinutes:
                  type: integer
                  description: Additional reaction time in minutes
                deadlineHours:
                  type: integer
                  description: Deadline time in hours
                deadlineMinutes:
                  type: integer
                  description: Additional deadline time in minutes
                workingTimeModel:
                  type: integer
                  description: Identifier of the working time model used to calculate deadlines
                sortOrder:
                  type: integer
                  description: Position used to order conditions within the SLA
                priorities:
                  type: array
                  description: List of ticket priority identifiers this condition applies to
                  items:
                    type: object
                ticketTypes:
                  type: array
                  description: List of ticket type identifiers this condition applies to
                  items:
                    type: object
            example:
              id: 7
              slaId: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Updated SLA condition.
              example:
                meta: {}
                content:
                  id: 7
                  slaId: 1
                  field: ticketType
                  operator: EQUALS
                  value: incident
                  rank: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sla/images:
    get:
      operationId: get_api_v1_sla_images
      tags:
        - sla
      summary: Get SLA images
      description: |
        Returns the list of SLA icon/image paths available for selection in the SLA editor. Requires access to all companies plus SERVICE_LEVEL_AGREEMENT_ADMINISTRATION.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of available SLA image paths.
              example:
                meta: {}
                content:
                  - sla/gold.svg
                  - sla/silver.svg
                  - sla/bronze.svg
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sla/permissions:
    get:
      operationId: get_api_v1_sla_permissions
      tags:
        - sla
      summary: Get SLA permissions
      description: |
        Returns the caller's effective SLA-related permissions as meta-properties (no content payload). Used by the frontend to decide which buttons/actions to render in the SLA module.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty content; permissions are exposed via meta.properties.
              example:
                meta:
                  properties: {}
                content: null
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sla/sort:
    put:
      operationId: put_api_v1_sla_sort
      tags:
        - sla
      summary: Sort SLAs
      description: |
        Persists a new rank order for SLAs in bulk. The body is a non-empty array of `{id, rank}` records — order matters because the SLA picked for a ticket is the first one whose conditions match. Requires admin-level SLA permissions.
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - id: 1
                rank: 1
              - id: 2
                rank: 2
              - id: 3
                rank: 3
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty payload; HTTP status indicates success.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sla/{id}:
    delete:
      operationId: delete_api_v1_sla_id
      tags:
        - sla
      summary: Delete task
      description: |
        Removes a contract task. Requires MAINTENANCE_CONTRACT_ADMINISTRATION and the parent contract must not be locked or being edited elsewhere.
      parameters:
        - in: path
          name: id
          description: ID of the contract task.
          required: true
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_sla_id
      tags:
        - sla
      summary: Get task
      description: |
        Returns one contract task by id. Restricted to technicians and freelancers; standard service-layer access checks apply.
      parameters:
        - in: path
          name: id
          description: ID of the contract task.
          required: true
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Contract task.
              example:
                meta: {}
                content:
                  id: 1
                  contractId: 100
                  name: Quartalsweise Server-Wartung
                  estimatedDurationMinutes: 120
                  nextExecution: 1748256000
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_sla_id
      tags:
        - sla
      summary: Update task
      description: |
        Updates a contract task. The service validates that the caller may edit the parent contract before applying the merge. Returns the persisted task.
      parameters:
        - in: path
          name: id
          description: ID of the contract task.
          required: true
          example: 42
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the task
                contractId:
                  type: integer
                  description: Identifier of the maintenance contract the task belongs to
                companyId:
                  type: integer
                  description: Identifier of the company the task is assigned to
                name:
                  type: string
                  description: Name of the task
                text:
                  type: string
                  description: Descriptive text of the task
                date:
                  type: integer
                  format: int64
                  description: Scheduled date of the task as a unix timestamp
                expirationDate:
                  type: integer
                  format: int64
                  description: Date after which the task expires as a unix timestamp
                supportTypeId:
                  type: integer
                  description: Identifier of the support type associated with the task
                supportDuration:
                  type: integer
                  description: Planned support duration in minutes
                preferredEmployeeId:
                  type: integer
                  description: Identifier of the preferred employee for the task
                ticketId:
                  type: integer
                  description: Identifier of the ticket linked to the task
                price:
                  type: number
                  description: Price associated with the task
                active:
                  type: boolean
                  description: Whether the task is currently active
            example:
              id: 1
              contractId: 100
              name: Quartalsweise Server-Wartung
              active: true
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Updated contract task.
              example:
                meta: {}
                content:
                  id: 1
                  contractId: 100
                  name: Quartalsweise Server-Wartung
                  estimatedDurationMinutes: 120
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sla/{slaId}/conditions:
    get:
      operationId: get_api_v1_sla_slaId_conditions
      tags:
        - sla
      summary: Get SLA conditions
      description: |
        Returns all matching conditions configured for the given SLA, ordered by rank. The conditions decide whether the SLA applies to a particular ticket. Requires admin-level SLA permissions.
      parameters:
        - in: path
          name: slaId
          description: ID of the SLA.
          required: true
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: SLA conditions, ordered by rank.
              example:
                meta: {}
                content:
                  - id: 7
                    slaId: 1
                    field: ticketType
                    operator: EQUALS
                    value: incident
                    rank: 1
                  - id: 9
                    slaId: 1
                    field: companyId
                    operator: EQUALS
                    value: '100023'
                    rank: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_sla_slaId_conditions
      tags:
        - sla
      summary: Add SLA condition
      description: |
        Adds a new matching condition (field, operator, value) to the given SLA. The new condition is appended at the end of the rank order; use the sort route to move it. Requires SERVICE_LEVEL_AGREEMENT_ADMINISTRATION.
      parameters:
        - in: path
          name: slaId
          description: ID of the SLA.
          required: true
          example: 1
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the SLA condition
                slaId:
                  type: integer
                  description: Identifier of the SLA this condition belongs to
                reactionTime:
                  type: integer
                  description: Reaction time in hours
                reactionTimeMinutes:
                  type: integer
                  description: Additional reaction time in minutes
                deadlineHours:
                  type: integer
                  description: Deadline time in hours
                deadlineMinutes:
                  type: integer
                  description: Additional deadline time in minutes
                workingTimeModel:
                  type: integer
                  description: Identifier of the working time model used to calculate deadlines
                sortOrder:
                  type: integer
                  description: Position used to order conditions within the SLA
                priorities:
                  type: array
                  description: List of ticket priority identifiers this condition applies to
                  items:
                    type: object
                ticketTypes:
                  type: array
                  description: List of ticket type identifiers this condition applies to
                  items:
                    type: object
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created SLA condition.
              example:
                meta: {}
                content:
                  id: 12
                  slaId: 1
                  field: ticketType
                  operator: EQUALS
                  value: incident
                  rank: 3
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/expire:
    get:
      operationId: get_api_v1_softwarelicenses_expire
      tags:
        - software licenses
      summary: List soon-to-expire software licenses
      description: |
        Returns the licenses whose `expirationDate` falls inside the upcoming reminder window — used to drive the
        expiry warnings in the software-license dashboard. When `companyId` is provided the result is restricted to a
        single customer, otherwise it spans every company the caller has access to. Requires the standard software
        license read permission.
      parameters:
        - in: query
          name: companyId
          required: false
          description: Restrict the result to a single company; omit to span all accessible companies
          example: 100023
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Expiring software licenses, grouped/structured per the expiry response DTO.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  expired:
                    - id: 1
                      companyId: 100023
                      name: Microsoft 365 E3
                      expirationDate: 1746748800
                  expiringSoon:
                    - id: 2
                      companyId: 100023
                      name: Adobe Creative Cloud
                      expirationDate: 1779792000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/pdf:
    put:
      operationId: put_api_v1_softwarelicenses_pdf
      tags:
        - software licenses
      summary: Render the filtered software-license list as PDF
      description: |
        Generates a PDF report for the same filtered/paginated license list that `PUT /softwarelicenses` returns —
        typically used for licence audits or to hand a customer a printable inventory. The body uses the regular
        configuration filters (type, company link, expiry filter, over-licensing) and `Accept`
        decides whether the PDF is streamed inline or wrapped in the standard envelope.
      requestBody:
        description: Filter configuration for the license list — same shape as `PUT /softwarelicenses`.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSoftwarelicenseConfiguration'
            example:
              softwarelicenseTypeId: 1
              includeSubTypes: true
              expiryFilter: ALL
              onlyOverlicenced: false
      responses:
        '200':
          description: Generated PDF, either streamed directly or wrapped in the standard envelope.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              example: JVBERi0xLjQKJeLjz9MK
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  filename: software-license-list.pdf
                  downloadUrl: /api/v1/downloads/software-license-list.pdf
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/types/treeview:
    get:
      operationId: get_api_v1_softwarelicenses_types_treeview
      tags:
        - software license types
      summary: List all software-license types
      description: |
        Returns the catalogue of software-license types (Office, Adobe, custom in-house products …) that licenses can be
        classified under. With `treeView=true` the result is nested using each type's `previousId` so the UI can render
        the parent/child hierarchy directly; with `treeView=false` it is a flat list. Used by the type pickers and the
        software-license administration screens.
      parameters:
        - in: query
          name: treeView
          required: false
          description: Return the types nested as a parent/child tree (true) or as a flat list (false)
          example: true
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Software-license types — flat list or nested tree depending on `treeView`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsSoftwarelicenseType'
              example:
                meta: {}
                content:
                  - id: 1
                    name: Microsoft 365
                    previousId: 0
                    active: true
                  - id: 2
                    name: Microsoft 365 E3
                    previousId: 1
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/{id}/assignments:
    get:
      operationId: get_api_v1_softwarelicenses_id_assignments
      tags:
        - software licenses
      summary: List assignments of a software license
      description: |
        Returns every device/employee/installation that currently consumes a seat of this license. This is what the
        "Zuweisungen" tab of the license detail view shows and is the basis for the over-licensing detection (compare
        the number of assignments against `numberOfVolumes`/`maxNumberOfInstall`). Both a basic read permission and
        access to the license's company are required.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the software license
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Active license assignments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 51
                    softwarelicenseId: 1
                    assignmentType: DEVICE
                    deviceId: 4711
                    installationDate: 1748256000
                  - id: 52
                    softwarelicenseId: 1
                    assignmentType: EMPLOYEE
                    employeeId: 5
                    installationDate: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/{id}/contracts:
    get:
      operationId: get_api_v1_softwarelicenses_id_contracts
      tags:
        - software licenses
      summary: List contracts linked to a software license
      description: |
        Returns the customer contracts this software license is referenced from — useful when a license is part of a
        recurring billing item or a service agreement and the technician needs to know which contract drives its
        renewal. Result is filtered to a small contract shape (id, title, customer). Caller must be allowed to read the
        license and its company.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the software license
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Contracts that reference the license.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 301
                    title: Microsoft 365 Lizenzbereitstellung
                    companyId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/{id}/copy:
    post:
      operationId: post_api_v1_softwarelicenses_id_copy
      tags:
        - software licenses
      summary: Copy a software license
      description: |
        Duplicates an existing software license — handy for renewals or when a customer buys an additional bundle that
        mirrors an existing license. The configuration request body controls which related data
        (assignments, contracts, custom properties) is carried over to the copy. Requires admin-level software license
        permission plus access to the source company.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the source software license to copy
          example: 42
          schema:
            type: integer
      requestBody:
        description: Copy options (which related data to clone) — the request payload.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                count:
                  type: integer
                  description: Number of license copies to create
                serialNumbers:
                  type: array
                  description: List of serial numbers to assign to the copied licenses
                  items:
                    type: object
      responses:
        '201':
          description: License copy created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 2
                  companyId: 100023
                  name: Microsoft 365 E3
                  licenseKey: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
                  validFrom: 1748256000
                  validTo: 1779792000
                  seats: 25
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/{id}/pdf:
    get:
      operationId: get_api_v1_softwarelicenses_id_pdf
      tags:
        - software licenses
      summary: Render a single software license as PDF
      description: |-
        Generates a printable detail sheet for one license — fields, expiry, vendor, key, assignments. The `internal`
        flag toggles between the customer-facing layout and the internal version (which adds remarks/notes that are not
        meant to leave the company). Honours the `Accept` header to either return the PDF inline or as the standard JSON
        envelope with a download URL.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the software license
          example: 42
          schema:
            type: integer
        - in: query
          name: internal
          required: false
          description: Use the internal PDF layout (includes internal remarks/notes) instead of the customer-facing one
          example: true
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Generated PDF, either streamed directly or wrapped in the standard envelope.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              example: JVBERi0xLjQKJeLjz9MK
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  filename: software-license-1-detail.pdf
                  downloadUrl: /api/v1/downloads/software-license-1-detail.pdf
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/softwarelicenses/{id}/properties:
    get:
      operationId: get_api_v1_softwarelicenses_id_properties
      tags:
        - software licenses
      summary: Get custom property values of a software license
      description: |
        Returns the customer-defined extra fields ("Eigenschaften") that have been filled in for this license. These are
        the dynamic key/value attributes that admins configure per object type and that the detail view renders in the
        Eigenschaften tab. The response uses `addWithProperties`, so the values come back together with their field
        metadata (label, type, editability).
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the software license
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Custom property values for the license.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta:
                  properties:
                    fields: {}
                    editable: true
                content:
                  purchaseOrderNumber: PO-2025-0815
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/starface/config:
    delete:
      operationId: delete_api_v1_starface_config
      tags:
        - calls (user context)
      summary: Delete starface config
      description: |
        Removes the calling user's Starface XML-RPC user settings and tears down the live websocket subscription that pushes incoming-call events to TANSS. Used when an employee unlinks their Starface account. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_starface_config
      tags:
        - calls (user context)
      summary: Get starface config
      description: |
        Returns the calling user's stored Starface XML-RPC user settings (host, port, login, etc.) used to register call-event subscriptions. Secrets are masked by the default filter. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  employeeId: 42
                  host: starface.example.com
                  port: 443
                  login: j.doe
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_starface_config
      tags:
        - calls (user context)
      summary: Update starface config
      description: |
        Creates or replaces the calling user's Starface XML-RPC settings. The new credentials are stored but the subscription is not automatically restarted — call `subscribe` (or `resubscribeAll`) to reconnect afterwards. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      requestBody:
        description: Starface XML-RPC user settings to persist for the calling employee.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              host: starface.example.com
              port: 443
              login: j.doe
              password: secret
              active: true
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  employeeId: 42
                  host: starface.example.com
                  port: 443
                  login: j.doe
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/starface/inc/{userId}/{userToken}:
    post:
      operationId: post_api_v1_starface_inc_userId_userToken
      tags:
        - calls (user context)
      summary: Incoming call
      description: |
        Webhook the Starface PBX calls when an inbound call hits a TANSS-linked extension. The raw XML-RPC body is parsed and forwarded to the employee identified by `userId`/`userToken`, which triggers their call pop-up. Authenticated solely by the per-user token in the URL (no JWT required).
      parameters:
        - in: path
          name: userId
          required: true
          description: Id of the employee the incoming call is forwarded to.
          example: 5
          schema:
            type: integer
        - in: path
          name: userToken
          required: true
          description: Per-user token authenticating the Starface webhook call.
          example: a1b2c3d4e5f6
          schema:
            type: string
      requestBody:
        description: Raw string body (no JSON wrapping).
        required: true
        content:
          application/json:
            schema:
              type: string
            example: <?xml version="1.0"?><methodCall><methodName>incomingCall</methodName><params><param><value><string>+49301234567</string></value></param></params></methodCall>
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: string
                    description: XML-RPC boolean response.
              example:
                meta: {}
                content: <methodResponse><params><param><value><boolean>1</boolean></value></param></params></methodResponse>
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/starface/resubscribeAll:
    get:
      operationId: get_api_v1_starface_resubscribeAll
      tags:
        - calls (user context)
      summary: Resubscribe all employees to Starface events
      description: |
        Walks every employee with active Starface XML-RPC settings and reopens their event subscription. Used after a server restart or PBX outage to bulk-reconnect all linked users in one call. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 1
                    employeeId: 42
                    host: starface.example.com
                    port: 443
                    login: j.doe
                    active: true
                  - id: 2
                    employeeId: 43
                    host: starface.example.com
                    port: 443
                    login: a.miller
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/starface/subscribe:
    delete:
      operationId: delete_api_v1_starface_subscribe
      tags:
        - calls (user context)
      summary: Unsubscribe from Starface call events
      description: |
        Closes the calling user's live Starface event subscription so the PBX stops pushing call events to TANSS. Stored credentials are kept; only the runtime websocket is torn down. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_starface_subscribe
      tags:
        - calls (user context)
      summary: Subscribe to Starface call events
      description: |
        Opens the live Starface event subscription for the calling user using the stored XML-RPC settings; incoming-call events are then routed into TANSS pop-ups. Returns the subscribed settings (with secrets masked). Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  employeeId: 42
                  host: starface.example.com
                  port: 443
                  login: j.doe
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supportRules:
    get:
      operationId: get_api_v1_supportRules
      tags:
        - support rules
      summary: Get all support rules
      description: |
        Returns every configured support rule (`leistungen_regeln` table). A support rule fires on a defined trigger (e.g. a support that exceeds a duration threshold) and runs configured events such as sending notifications. Requires the ESCALATION module licence and technician/freelancer status.
      responses:
        '200':
          description: List of support rules.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 12
                    name: Mehr als 8h Arbeitszeit pro Tag
                    description: Sendet eine Erinnerung, wenn die tägliche Arbeitszeit 8h überschreitet
                    active: true
                    auto: true
                    mailReceiversOnErrors: admin@example.com
                  - id: 13
                    name: Leistung ohne Vertrag
                    description: Markiert Leistungen ohne Vertragszuordnung
                    active: false
                    auto: false
                    mailReceiversOnErrors: ''
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_supportRules
      tags:
        - support rules
      summary: Create support rule
      description: |
        Creates a new support rule. Conditions and events submitted with the rule are persisted by the `afterCreate` hook. Requires the `SUPPORT_RULE_ADMINISTRATION` permission and the ESCALATION module licence.
      requestBody:
        description: Body the request payload. The nested `conditions` and `events` arrays drive when and what the rule executes.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              name: Mehr als 8h Arbeitszeit pro Tag
              description: Sendet eine Erinnerung, wenn die tägliche Arbeitszeit 8h überschreitet
              active: true
              auto: true
              mailReceiversOnErrors: admin@example.com
      responses:
        '201':
          description: Support rule created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 12
                  name: Mehr als 8h Arbeitszeit pro Tag
                  description: Sendet eine Erinnerung, wenn die tägliche Arbeitszeit 8h überschreitet
                  active: true
                  auto: true
                  mailReceiversOnErrors: admin@example.com
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_supportRules
      tags:
        - support rules
      summary: Load support rules (paginated)
      description: |
        Loads support rules filtered/sorted/paginated according to object. Used by the rules-administration list views. Requires the ESCALATION module licence and technician/freelancer status.
      requestBody:
        description: 'List configuration: sorting, paging and filter fields.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                searchText:
                  type: string
                  description: Free-text search term used to filter support rules
                active:
                  type: string
                  description: Whether to include active, inactive or both kinds of rules
                  enum:
                    - ACTIVE_ONLY
                    - INACTIVE_ONLY
                    - ACTIVE_AND_INACTIVE
                sortOrder:
                  type: string
                  description: Sort direction for the result list
                  enum:
                    - ASC
                    - DESC
                sortField:
                  type: string
                  description: Field the result list is sorted by
                  enum:
                    - ID
                    - NAME
                    - DESCRIPTION
                page:
                  type: integer
                  description: One-based page number to retrieve
                itemsPerPage:
                  type: integer
                  description: Number of items returned per page
                omitTotalCount:
                  type: boolean
                  description: Skip calculating the total result count for faster paging
            example:
              sortField: NAME
              searchText: ''
      responses:
        '200':
          description: Paginated list of support rules.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  items:
                    - id: 12
                      name: Mehr als 8h Arbeitszeit pro Tag
                      description: Sendet eine Erinnerung, wenn die tägliche Arbeitszeit 8h überschreitet
                      active: true
                      auto: true
                  pagination:
                    page: 1
                    itemsPerPage: 25
                    totalItems: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supportRules/frontend/conditions/{type}:
    get:
      operationId: get_api_v1_supportRules_frontend_conditions_type
      tags:
        - support rules
      summary: Get UI field definition for a rule condition type
      description: |
        Returns the frontend field definition (object) used to render the value picker for the given support-rule condition type — for example the list of selectable companies, durations or weekdays the condition can be configured against. Requires technician/freelancer status, the ESCALATION module licence and `SUPPORT_RULE_ADMINISTRATION` permission.
      parameters:
        - in: path
          name: type
          required: true
          description: Support-rule condition type whose UI field definition is requested.
          schema:
            type: string
            description: enumeration value.
          example: TIME
      responses:
        '200':
          description: Field definition for the condition value picker.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  fieldType: SELECT_MULTI
                  fieldName: companies
                  label: Firmen
                  options:
                    - value: 100023
                      label: Acme GmbH
                    - value: 100024
                      label: Beispiel AG
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supportRules/frontend/events/{type}:
    get:
      operationId: get_api_v1_supportRules_frontend_events_type
      tags:
        - support rules
      summary: Get UI field definition for a rule event type
      description: |
        Returns the frontend field definition (object) used to configure an event of the given type within a support rule — for example which mail template, recipient list or status update to apply when the rule fires. Requires technician/freelancer status, the ESCALATION module licence and `SUPPORT_RULE_ADMINISTRATION` permission.
      parameters:
        - in: path
          name: type
          required: true
          description: Support-rule event type whose UI field definition is requested.
          schema:
            type: string
            description: enumeration value.
          example: TICKET_CREATED
      responses:
        '200':
          description: Field definition for the event configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  fieldType: SELECT_SINGLE
                  fieldName: mailTemplate
                  label: E-Mail-Vorlage
                  options:
                    - value: 3
                      label: Eskalation Techniker
                    - value: 7
                      label: Eskalation Manager
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supportRules/trigger:
    put:
      operationId: put_api_v1_supportRules_trigger
      tags:
        - support rules
      summary: Trigger / test-run support rules
      description: |
        Evaluates the configured support rules against the supplied options (e.g. specific rule ids, a date range, dry-run flag) and returns the results — which rules matched and which events would/did fire. Used both for manual trigger runs and for the rules-editor "test" button. Requires technician/freelancer status, the ESCALATION module licence and the rule-execution permission check.
      requestBody:
        description: 'Trigger options. `dryRun: true` evaluates without persisting any events.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleId:
                  type: integer
                  description: Identifier of the support rule to evaluate
                checkMode:
                  type: string
                  description: 'How the rule is evaluated: preview only, simulate, or actually escalate'
                  enum:
                    - SHOW
                    - SIMULATE
                    - ESCALATE
                supportIds:
                  type: array
                  description: Identifiers of the support entries the rule should be applied to
                  items:
                    type: object
                processAlreadyProcessedSupports:
                  type: boolean
                  description: Re-process support entries that were already handled by the rule
                sendMailOnErrors:
                  type: boolean
                  description: Send a notification email if errors occur during evaluation
      responses:
        '200':
          description: Per-rule evaluation results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - ruleId: 12
                    ruleName: Mehr als 8h Arbeitszeit pro Tag
                    matched: true
                    matchedSupportIds:
                      - 5004
                      - 5006
                    events:
                      - type: SEND_MAIL
                        success: true
                        details: Mail an admin@example.com versendet
                  - ruleId: 13
                    ruleName: Leistung ohne Vertrag
                    matched: false
                    matchedSupportIds: []
                    events: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supportRules/{id}:
    delete:
      operationId: delete_api_v1_supportRules_id
      tags:
        - support rules
      summary: Delete support rule
      description: Deletes the support rule with the given id. The `afterDelete` hook also removes the rule's conditions and events and writes a log entry. Requires `SUPPORT_RULE_ADMINISTRATION` permission and the ESCALATION module licence.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the support rule to delete.
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: Support rule deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_supportRules_id
      tags:
        - support rules
      summary: Get support rule
      description: Returns a single support rule including its conditions and events (loaded by `decorateObjectBeforeOutput`). Requires technician/freelancer status and the ESCALATION module licence.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the support rule to fetch.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: The support rule.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 12
                  name: Mehr als 8h Arbeitszeit pro Tag
                  description: Sendet eine Erinnerung, wenn die tägliche Arbeitszeit 8h überschreitet
                  active: true
                  auto: true
                  mailReceiversOnErrors: admin@example.com
                  conditions:
                    - id: 21
                      type: DURATION_PER_DAY
                      value: '28800'
                  events:
                    - id: 33
                      type: SEND_MAIL
                      details:
                        mailTemplate: 3
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_supportRules_id
      tags:
        - support rules
      summary: Update support rule
      description: Updates the support rule with the given id. Conditions and events submitted along with the rule are reconciled (created/updated/deleted) by the `afterUpdate` hook. Requires `SUPPORT_RULE_ADMINISTRATION` permission and the ESCALATION module licence.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the support rule to update.
          schema:
            type: integer
          example: 42
      requestBody:
        description: Body the request payload. Only changed fields need to be supplied; nested `conditions`/`events` lists fully replace the persisted set.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              id: 12
              name: Mehr als 8h Arbeitszeit pro Tag
              description: Sendet eine Erinnerung, wenn die tägliche Arbeitszeit 8h überschreitet
              active: true
              auto: true
              mailReceiversOnErrors: admin@example.com
      responses:
        '200':
          description: Updated support rule.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 12
                  name: Mehr als 8h Arbeitszeit pro Tag
                  description: Sendet eine Erinnerung, wenn die tägliche Arbeitszeit 8h überschreitet
                  active: true
                  auto: true
                  mailReceiversOnErrors: admin@example.com
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/appointmentWizard:
    put:
      operationId: put_api_v1_supports_appointmentWizard
      tags:
        - supports
      summary: Find free appointment slots
      description: |
        Searches for free appointment slots that match the supplied criteria (estimated duration, candidate technicians/departments, timeframe, weekdays). The wizard inspects each employee's working-hours model and existing supports/appointments to compute available windows; it can optionally include drive parameters and apply tolerance to shift adjacent appointments.
      requestBody:
        description: Search query for the appointment wizard. `appointmentDuration` is in minutes; `timeframe` bounds the search.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - appointmentDuration
                - timeframe
              properties:
                appointmentDuration:
                  type: integer
                  description: Estimated duration of the appointment in minutes.
                timeframe:
                  type: object
                  description: Time window (from/to timestamps) within which available slots are searched.
                minHour:
                  type: integer
                  description: Earliest hour of the day to consider; if left at zero the employee working hours are used.
                maxHour:
                  type: integer
                  description: Latest hour of the day to consider; if left at zero the employee working hours are used.
                employeeIds:
                  type: array
                  description: Identifiers of the technicians to check availability for.
                  items:
                    type: object
                departmentIds:
                  type: array
                  description: Identifiers of the departments to check availability for, as an alternative to specific employees.
                  items:
                    type: object
                weekDays:
                  type: array
                  description: Restricts the search to the given weekdays.
                  items:
                    type: string
                    enum:
                      - SUNDAY
                      - MONDAY
                      - TUESDAY
                      - WEDNESDAY
                      - THURSDAY
                      - FRIDAY
                      - SATURDAY
                      - EVERYDAY
                      - HOLIDAY
                      - HOLIDAY_AM
                      - HOLIDAY_PM
                companyId:
                  type: integer
                  description: Identifier of the company the appointment is for.
                includeDrive:
                  type: boolean
                  description: Whether drive time parameters are included in the proposed slots.
                allEmployeesMustParticipate:
                  type: boolean
                  description: Whether every listed technician must be available for a slot to match.
                numberOfEmployeesWhoMustParticipate:
                  type: integer
                  description: Minimum number of technicians that must be available when not all are required.
                tolerance:
                  type: integer
                  description: Tolerance in minutes allowing a slightly smaller gap to still qualify as a slot.
            example:
              appointmentDuration: 60
              timeframe:
                from: 1748256000
                to: 1748860800
              employeeIds:
                - 5
                - 7
              companyId: 100023
              allEmployeesMustParticipate: false
              numberOfEmployeesWhoMustParticipate: 1
              includeDrive: true
              tolerance: 0
      responses:
        '200':
          description: Computed free time slots.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - from: 1748332800
                    to: 1748336400
                    employeeIds:
                      - 5
                    companyId: 100023
                  - from: 1748419200
                    to: 1748422800
                    employeeIds:
                      - 7
                    companyId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/appointments/{ticketId}:
    get:
      operationId: get_api_v1_supports_appointments_ticketId
      tags:
        - supports
      summary: Get appointments for a ticket
      description: Returns the appointments (supports flagged as planning appointments) linked to the given ticket. The caller must have access to the ticket; the result list uses the SMALL filter (only essential support fields are exposed).
      parameters:
        - in: path
          name: ticketId
          required: true
          description: Id of the ticket whose appointments are requested.
          schema:
            type: integer
          example: 4711
      responses:
        '200':
          description: Appointments belonging to the ticket.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TnsSupport-Small'
              example:
                meta: {}
                content:
                  - id: 5004
                    ticketId: 4711
                    employeeId: 5
                    date: 1748256000
                    duration: 1800
                    text: 'Vor-Ort-Termin: Festplatte tauschen'
                  - id: 5005
                    ticketId: 4711
                    employeeId: 5
                    date: 1748342400
                    duration: 3600
                    text: Nachkontrolle
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/bookDirectly:
    post:
      operationId: post_api_v1_supports_bookDirectly
      tags:
        - supports
      summary: Book internal supports directly
      description: Marks the given supports as booked without going through a voucher / invoice run. Only `internal` supports that are not already booked can be booked this way; non-internal entries are skipped and reported back with an exception type. Requires technician/freelancer status plus the `BOOK_SUPPORTS` permission.
      requestBody:
        description: Array of support ids to book directly.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
            example:
              - 5004
              - 5005
      responses:
        '200':
          description: Per-support booking results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - supportId: 5004
                    success: true
                    exceptionType: null
                    exceptionMessage: null
                  - supportId: 5005
                    success: false
                    exceptionType: BOOK_CHECK_ONLY_INTERNAL_SUPPORTS
                    exceptionMessage: Nur interne Leistungen können direkt gebucht werden.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/clear:
    post:
      operationId: post_api_v1_supports_clear
      tags:
        - supports
      summary: Clear supports for billing
      description: |
        Marks supports as cleared (`clearanceStatus = CLEARED`), making them eligible to appear on the next invoice run. Already-cleared and `internal` supports are skipped and reported with an exception type. Requires technician/freelancer status; individual support permission checks happen inside the service.
      requestBody:
        description: Array of support ids to clear.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
            example:
              - 5004
              - 5005
      responses:
        '200':
          description: Per-support clearance results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - supportId: 5004
                    success: true
                    exceptionType: null
                    exceptionMessage: null
                  - supportId: 5005
                    success: false
                    exceptionType: INTERNAL_SUPPORT_CANT_BE_CLEARED
                    exceptionMessage: Interne Leistungen können nicht freigegeben werden.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/list/properties:
    put:
      operationId: put_api_v1_supports_list_properties
      tags:
        - supports
      summary: Get UI properties for the support list filter form
      description: Returns the form-property metadata (visible/editable fields, allowed values, labels) for the support-list filter UI. The caller specifies which configuration `fields` and the `context` (e.g. ticket-, company- or planning-view) so the backend can hide/disable filters that don't apply.
      requestBody:
        description: Which list configuration fields should be returned and in which UI context.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: array
                  description: List of configured column or field definitions for the support view
                  items:
                    type: object
                context:
                  type: string
                  description: Context in which the support configuration is applied
                  enum:
                    - SUPPORT_HISTORY
                    - SUPPORT_STATISTICS_GENERAL
                    - DEVICE_LIST
                    - CLEAR_SUPPORTS
            example:
              fields:
                - TIMEFRAME
                - COMPANIES
                - EMPLOYEES
                - INTERNAL_SUPPORT
              context: SUPPORT_LIST
      responses:
        '200':
          description: Field-property metadata for the requested fields.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  fields:
                    TIMEFRAME:
                      editable: true
                      visible: true
                    COMPANIES:
                      editable: true
                      visible: true
                    EMPLOYEES:
                      editable: true
                      visible: true
                    INTERNAL_SUPPORT:
                      editable: true
                      visible: true
                      options:
                        - ALL
                        - ONLY_INTERNAL
                        - ONLY_PUBLIC
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/matPicker:
    get:
      operationId: get_api_v1_supports_matPicker
      tags:
        - supports
      summary: Search materials for adding to a support
      description: |
        Returns the materials matching `searchText`, filtered by source (TANSS catalogue vs. external Wawi), type and optionally a car (mobile stock). Used by the material-picker dropdown when techs add materials to a support entry. Optionally includes serial numbers when the `XML_WAWI_MATERIAL_SEARCH_SN` config flag is set. Standard access checks apply.
      parameters:
        - in: query
          name: source
          required: false
          description: Material source to search (e.g. TANSS catalogue or external Wawi).
          schema:
            type: string
            description: enumeration value.
            default: TANSS
          example: TANSS
        - in: query
          name: searchText
          required: false
          description: Text the material name/number is matched against.
          schema:
            type: string
            default: ''
          example: Festplatte
        - in: query
          name: type
          required: false
          description: Material type to filter the results by.
          schema:
            type: string
            description: enumeration value.
            default: ALL
          example: ALL
        - in: query
          name: carId
          required: false
          description: Id of the car (mobile stock) to restrict the search to; 0 means no car filter.
          schema:
            type: integer
            default: 0
          example: 1
      responses:
        '200':
          description: Materials matching the search.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 281
                    name: Festplatte SSD 1TB
                    articleNumber: SSD-1TB-001
                    stock: 12
                    price: 89
                  - id: 305
                    name: Festplatte SSD 2TB
                    articleNumber: SSD-2TB-001
                    stock: 4
                    price: 149
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/notChargedReason:
    get:
      operationId: get_api_v1_supports_notChargedReason
      tags:
        - not charged reasons
      summary: Get all not-charged reasons
      description: |
        Returns all "not charged" reasons used by supports. When a support is fully or partially not billed, one of these reasons can be referenced (`reasonNotChargedId` / `reasonPartialNotChargedId`) and its `longText` is appended to the support's `reasonNotChargedText`. Inherited admin CRUD route — requires technician/freelancer status and `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      responses:
        '200':
          description: List of not-charged reasons.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 1
                    shortText: Kulanz
                    longText: Aus Kulanz nicht berechnet.
                    hidden: false
                  - id: 2
                    shortText: Garantie
                    longText: Im Rahmen der Garantieleistung erbracht.
                    hidden: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_supports_notChargedReason
      tags:
        - not charged reasons
      summary: Create not-charged reason
      description: |
        Creates a new not-charged reason. `shortText` is shown in dropdowns/lists; `longText` is the explanatory text appended to a support's not-charged-reason text. Requires technician/freelancer status and `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      requestBody:
        description: Body the request payload.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              shortText: Kulanz
              longText: Aus Kulanz nicht berechnet.
              hidden: false
      responses:
        '201':
          description: Not-charged reason created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 7
                  shortText: Kulanz
                  longText: Aus Kulanz nicht berechnet.
                  hidden: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/notChargedReason/{id}:
    delete:
      operationId: delete_api_v1_supports_notChargedReason_id
      tags:
        - not charged reasons
      summary: Delete not-charged reason
      description: |
        Deletes a not-charged reason. Deletion is rejected if any support still references the reason. Requires technician/freelancer status and `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the not-charged reason to delete.
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: Not-charged reason deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_supports_notChargedReason_id
      tags:
        - not charged reasons
      summary: Get not-charged reason
      description: |
        Returns a single not-charged reason by id. Requires technician/freelancer status and `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the not-charged reason to fetch.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: The not-charged reason.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  shortText: Kulanz
                  longText: Aus Kulanz nicht berechnet.
                  hidden: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_supports_notChargedReason_id
      tags:
        - not charged reasons
      summary: Update not-charged reason
      description: |
        Updates an existing not-charged reason. Setting `hidden = true` keeps the entry for historical supports but removes it from selection dropdowns. Requires technician/freelancer status and `BASE_DATA_MANAGEMENT_SYSTEM_TABLES` permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the not-charged reason to update.
          schema:
            type: integer
          example: 42
      requestBody:
        description: Body the request payload.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              id: 1
              shortText: Kulanz
              longText: Aus Kulanz nicht berechnet.
              hidden: true
      responses:
        '200':
          description: Updated not-charged reason.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  shortText: Kulanz
                  longText: Aus Kulanz nicht berechnet.
                  hidden: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/properties:
    post:
      operationId: post_api_v1_supports_properties
      tags:
        - supports
      summary: Compute form properties for an unsaved support
      description: |
        Given a (possibly unsaved) support payload, returns the form properties — which fields are editable, visible, required, plus computed default values and dropdown options — based on the current state. The frontend calls this on every relevant field change (`changedProperty`) so the backend can re-evaluate dependent rules (e.g. setting `internal` may toggle billing fields). Pass `initAllFields=true` on the first call to populate every field.
      parameters:
        - in: query
          name: changedProperty
          required: false
          description: Name of the field that just changed so dependent rules can be re-evaluated.
          schema:
            type: string
            default: ''
            description: Name of the field that just changed (e.g. `companyId`, `internal`, `duration`).
          example: companyId
        - in: query
          name: initAllFields
          required: false
          description: When true, populate every form field instead of only the changed one (use on the first call).
          schema:
            type: boolean
            default: false
          example: true
      requestBody:
        description: The current support draft plus tracking of what changed.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Body binds to the property-evaluation payload.
            example:
              support:
                id: 5004
                ticketId: 4711
                companyId: 100023
                employeeId: 5
                typeId: 1
                date: 1748256000
                duration: 1800
                text: Festplatte getauscht, System neu installiert
                internal: false
                location: OFFICE
              orgValues:
                id: 5004
                duration: 3600
                internal: false
              changedFields:
                - duration
              initAllFields: false
      responses:
        '201':
          description: Field properties for the support form.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  fields:
                    duration:
                      editable: true
                      visible: true
                      value: 1800
                    internal:
                      editable: true
                      visible: true
                      value: false
                    booked:
                      editable: false
                      visible: true
                      value: false
                  editable: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/split:
    post:
      operationId: post_api_v1_supports_split
      tags:
        - supports
      summary: Preview overtime split of a support
      description: |
        Computes how a support would be split into multiple parts when its duration crosses overtime-surcharge boundaries (see `additionalCharges` config). Read-only — returns the proposed split parts without persisting them, so the UI can show the user a preview before saving. Access is checked on the support before computation.
      requestBody:
        description: The support to be analysed. Only the time-related fields are required.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSupport'
            example:
              id: 5004
              ticketId: 4711
              companyId: 100023
              employeeId: 5
              date: 1748246400
              duration: 18000
              text: Notdienst-Einsatz Wochenende
              internal: false
      responses:
        '200':
          description: Proposed overtime split parts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - date: 1748246400
                    duration: 7200
                    percent: 0
                  - date: 1748253600
                    duration: 7200
                    percent: 25
                  - date: 1748260800
                    duration: 3600
                    percent: 50
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/statistics:
    put:
      operationId: put_api_v1_supports_statistics
      tags:
        - supports
      summary: Get support statistics (aggregated amounts)
      description: |
        Collects supports matching the filter and returns calculated amounts (chargeable/non-chargeable durations, prices, drive km, etc.) summarised into a summary. Pass `groupingType` to group totals by e.g. employee, company or support type. Optionally includes the matching working-time models when `includeWorkingTimeModels` is set on the configuration. Requires technician/freelancer status and the `VIEW_MINI_STATISTICS` permission.
      parameters:
        - in: query
          name: groupingType
          required: false
          description: How the aggregated totals are grouped (e.g. by employee, company or support type).
          schema:
            type: string
            description: enumeration value (e.g. EMPLOYEE, COMPANY, SUPPORT_TYPE).
          example: EMPLOYEE
      requestBody:
        description: Filter that selects which supports to aggregate (same shape as the support list filter).
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TnsSupportConfiguration'
            example:
              timeframe:
                from: 1748131200
                to: 1748736000
              companies:
                - 100023
              employees:
                - 5
              internalSupport: ALL
      responses:
        '200':
          description: Aggregated statistics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  totalDuration: 144000
                  totalDurationCharged: 126000
                  totalDurationNotCharged: 18000
                  totalPrice: 4200
                  totalKm: 320
                  groups:
                    - groupKey: 5
                      groupLabel: Max Mustermann
                      totalDuration: 72000
                      totalPrice: 2100
                    - groupKey: 8
                      groupLabel: Anna Beispiel
                      totalDuration: 72000
                      totalPrice: 2100
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/summary/config:
    get:
      operationId: get_api_v1_supports_summary_config
      tags:
        - supports
      summary: Get default support-summary PDF config
      description: |
        Returns the default configuration for the support-summary PDF (Leistungsnachweis): default supplement-sheet type, print options, grouping and pricing flags — all pre-filled from system config values like `PDF_SUPPORT_PRINT_SUPPLEMENT_SHEET` and `PDF_SUPPORT_PRINT_OPTION`. Requires unrestricted company access and the `CREATE_SERVICE_REPORT_AS_PDF` permission.
      responses:
        '200':
          description: Default summary configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  date: 1748256000
                  supplementSheet: LONG
                  onlySupplementSheet: false
                  grouping: BY_DATE
                  printOptions: STANDARD
                  includePricing: false
                  configuration:
                    timeframe:
                      from: 1748131200
                      to: 1748736000
                    companies: []
                    employees: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/summary/pdf:
    put:
      operationId: put_api_v1_supports_summary_pdf
      tags:
        - supports
      summary: Render support-summary PDF
      description: |
        Generates the support-summary PDF (Leistungsnachweis) for the supports selected by the configuration. Only cleared supports are included (the service forces `bookedSupportFilter = CLEARED`). The response is the binary PDF; depending on the `Accept` header it may also be returned as a download link or sent by email. Requires unrestricted company access and the `CREATE_SERVICE_REPORT_AS_PDF` permission.
      requestBody:
        description: 'Summary configuration: selection filter, supplement sheet, grouping, print options, pricing.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                configuration:
                  type: object
                  description: Support list configuration selecting which entries the summary covers
                invoiceNumber:
                  type: integer
                  description: Invoice number associated with the summary
                date:
                  type: integer
                  format: int64
                  description: Reference date of the summary as a unix timestamp
                supplementSheet:
                  type: string
                  description: Type of supplement sheet to include in the printout
                  enum:
                    - DEFAULT
                    - NONE
                    - PAYTYPES
                    - SUPPORTS
                    - SUPPORTS_TICKETS
                    - EMPLOYEES
                    - EMPLOYEES_INT
                    - PAYTYPES_SHORT
                    - SUPPORTS_SHORT
                    - SUPPORTS_TICKETS_SHORT
                    - EMPLOYEES_SHORT
                    - EMPLOYEES_INT_SHORT
                onlySupplementSheet:
                  type: boolean
                  description: Print only the supplement sheet without the main summary
                grouping:
                  type: string
                  description: How summary entries are grouped in the output
                  enum:
                    - DONT_GROUP
                    - GROUP_BY_TICKETS
                    - GROUP_BY_COST_CENTER
                    - GROUP_BY_DEPARTMENT
                printOptions:
                  type: string
                  description: Which document variant is generated
                  enum:
                    - SUMMARY_PDF
                    - ANALYSIS_PDF
                includePricing:
                  type: boolean
                  description: Include price information in the summary
            example:
              configuration:
                timeframe:
                  from: 1748131200
                  to: 1748736000
                companies:
                  - 100023
                employees:
                  - 5
              date: 1748256000
              supplementSheet: LONG
              onlySupplementSheet: false
              grouping: BY_DATE
              printOptions: STANDARD
              includePricing: true
      responses:
        '200':
          description: Generated PDF (or a download/email response, depending on the `Accept` header).
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              example: JVBERi0xLjQKJeLjz9MK
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  fileName: PDF-Vorschau aller ausgewählten Leistungen.pdf
                  downloadUrl: /api/v1/files/download/xyz
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/unclear:
    post:
      operationId: post_api_v1_supports_unclear
      tags:
        - supports
      summary: Revoke clearance for supports
      description: |
        Reverses a previous clearance (`clearanceStatus` goes back to `NONE`) so the supports leave the billing queue. Already-uncleared and booked supports are skipped and reported back with an exception type. Requires technician/freelancer status; per-support permission checks happen inside the service.
      requestBody:
        description: Array of support ids to unclear.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
            example:
              - 5004
              - 5005
      responses:
        '200':
          description: Per-support unclear results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - supportId: 5004
                    success: true
                    exceptionType: null
                    exceptionMessage: null
                  - supportId: 5005
                    success: false
                    exceptionType: ALREADY_BOOKED
                    exceptionMessage: Bereits gebuchte Leistungen können nicht zurückgesetzt werden.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/supports/{supportId}/properties:
    get:
      operationId: get_api_v1_supports_supportId_properties
      tags:
        - supports
      summary: Get form properties for an existing support
      description: Returns the form properties (editable/visible flags, computed values, dropdown options) for an existing support, used by the support edit form. For appointment series, pass `sequenceId` to evaluate the properties of a specific occurrence rather than the master support.
      parameters:
        - in: path
          name: supportId
          required: true
          description: Id of the existing support whose form properties are requested.
          schema:
            type: integer
          example: 5004
        - in: query
          name: sequenceId
          required: false
          description: Occurrence id within an appointment series; evaluate that occurrence instead of the master support.
          schema:
            type: string
            default: ''
            description: Occurrence id within an appointment series (string-encoded integer).
          example: '1'
      responses:
        '200':
          description: Field properties for this support.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  fields:
                    duration:
                      editable: true
                      visible: true
                      value: 1800
                    internal:
                      editable: true
                      visible: true
                      value: false
                    booked:
                      editable: false
                      visible: true
                      value: false
                    clearanceStatus:
                      editable: false
                      visible: true
                      value: CLEARED
                  editable: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sysTasks:
    get:
      operationId: get_api_v1_sysTasks
      tags:
        - scheduled tasks
      summary: Get sys-task executions
      description: |
        Returns the list of all scheduled system tasks (cron-like background jobs) together with their last/next
        execution time, last error, and a transient `running` flag indicating whether the executor is currently
        processing them.

        Requires both `ONLINE_SYSTEM_CONFIGURATION` and `MANAGE_PERMISSIONS`.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of records with running-state attached.
              example:
                meta: {}
                content:
                  - type: CLEANUP_TEMP_FILES
                    area: ''
                    active: true
                    nextExecution: 1748259600
                    lastExecution: 1748256000
                    lastDurationInMillis: 245
                    secondsInterval: 3600
                    running: false
                  - type: REFRESH_LICENSES
                    area: ''
                    active: true
                    nextExecution: 1748342400
                    lastExecution: 1748256000
                    lastDurationInMillis: 1200
                    secondsInterval: 86400
                    running: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sysTasks/execute/{type}:
    get:
      operationId: get_api_v1_sysTasks_execute_type
      tags:
        - scheduled tasks
      summary: Execute sys task by type
      description: |
        Forces a scheduled system task to run on the next executor tick by resetting its `nextExecution` timestamp
        to `now`. Identified by the task's `type` enum and (optionally) `area` query parameter. Throws
        object if no task of the given type is configured.

        Requires both `ONLINE_SYSTEM_CONFIGURATION` and `MANAGE_PERMISSIONS`.
      parameters:
        - in: path
          name: type
          required: true
          description: Type of the scheduled system task to force-run.
          schema:
            type: string
          example: REFRESH_LICENSES
        - in: query
          name: area
          required: false
          description: Optional area discriminator narrowing the task to run.
          schema:
            type: string
            default: ''
          example: licenses
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The object whose `nextExecution` was reset.
              example:
                meta: {}
                content:
                  type: REFRESH_LICENSES
                  area: ''
                  active: true
                  nextExecution: 1748256000
                  lastExecution: 1748252400
                  secondsInterval: 86400
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sysTasks/restart:
    get:
      operationId: get_api_v1_sysTasks_restart
      tags:
        - scheduled tasks
      summary: Restart sys-task scheduler
      description: |
        Stops the `SYS-TASK` scheduler, waits 5 seconds for in-flight jobs to settle, and restarts it.
        Used by admins to recover from a wedged scheduler without bouncing the JVM.

        Requires the `ONLINE_SYSTEM_CONFIGURATION` permission.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: '`true` when the restart sequence completed successfully.'
              example:
                meta: {}
                content: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/sysTasks/scheduler/jobs:
    get:
      operationId: get_api_v1_sysTasks_scheduler_jobs
      tags:
        - scheduled tasks
      summary: List scheduler job ids
      description: |
        Returns the ids of all jobs currently registered with the scheduler (everything the scheduler is
        keeping alive — sys-task executor, push pollers, etc.). Useful for diagnosing what is actually running
        inside the JVM.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of currently-registered scheduler job ids.
              example:
                meta: {}
                content:
                  - SYS-TASK
                  - PUSH-DELIVERY
                  - TANSS-EVENT-RULES
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/systemhaus_one/articles:
    get:
      operationId: get_api_v1_systemhaus_one_articles
      tags:
        - erp
      summary: Get articles
      description: |
        Returns the list of articles known to the connected SAP Business One system, optionally filtered by free-text search, warehouse, result limit, and active-only flag. Intended for ERP integrations against SAP B1 — must be called with the dedicated API token bound to the role `ERP`, not a normal user login; the `SAP_ONE` module must be licensed.
      parameters:
        - in: query
          name: search
          description: Free-text search term to filter articles.
          required: false
          schema:
            type: string
            default: ''
          example: Heizung
        - in: query
          name: warehouse
          description: Warehouse code to restrict the article list to.
          required: false
          schema:
            type: string
            default: ''
          example: WH-01
        - in: query
          name: limit
          description: Maximum number of articles to return (0 = no limit).
          required: false
          schema:
            type: integer
            default: 0
          example: 1
        - in: query
          name: onlyActive
          description: If true, only active articles are returned.
          required: false
          schema:
            type: boolean
            default: true
          example: true
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/systemhaus_one/invoices:
    get:
      operationId: get_api_v1_systemhaus_one_invoices
      security:
        - ErpToken: []
        - ApiTokenAuth: []
      tags:
        - erp
      summary: Get invoices
      description: |
        Returns the list of invoices for the given customer by delegating to the legacy PHP ERP backend; used by ERP integrations to read invoice data from TANSS. Intended for ERP integrations only — must be called with the dedicated API token bound to the role `ERP`, not a normal user login.
      parameters:
        - in: query
          name: customer
          description: Customer number whose invoices are returned.
          required: false
          schema:
            type: string
            default: ''
          example: K100023
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/systemhaus_one/priceLists:
    get:
      operationId: get_api_v1_systemhaus_one_priceLists
      tags:
        - erp
      summary: Get price lists
      description: |
        Returns the price lists configured in the connected SAP Business One system, used by ERP integrations to map articles to the correct pricing tier. Intended for ERP integrations against SAP B1 — must be called with the dedicated API token bound to the role `ERP`, not a normal user login; the `SAP_ONE` module must be licensed.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/systemhaus_one/warehouses:
    get:
      operationId: get_api_v1_systemhaus_one_warehouses
      tags:
        - erp
      summary: Get warehouses
      description: |
        Returns the list of warehouses configured in the connected SAP Business One system, used by ERP integrations to populate warehouse selectors during article/stock sync. Intended for ERP integrations against SAP B1 — must be called with the dedicated API token bound to the role `ERP`, not a normal user login; the `SAP_ONE` module must be licensed.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tanssEvents/rules/{type}/assignments:
    get:
      operationId: get_api_v1_tanssEvents_rules_type_assignments
      tags:
        - activityFeed
      summary: Get TANSS event rule assignments by link type
      description: |
        Returns the per-link-type assignments configured for TANSS event rules — i.e. which rules trigger for which
        target entity kind. Used by the rule-editor UI to populate the assignment matrix when a rule is being
        edited for a given link type (TICKET, COMPANY, EMPLOYEE,...).

        Standard permission checks apply.
      parameters:
        - in: path
          name: type
          required: true
          description: Link type to fetch event-rule assignments for (TICKET, COMPANY, EMPLOYEE, ...).
          schema:
            type: string
          example: TICKET
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Assignment payload for the requested link type.
              example:
                meta: {}
                content:
                  type: TICKET
                  assignments:
                    - ruleId: 42
                      ruleName: Eskalation bei Prio 1
                      active: true
                    - ruleId: 43
                      ruleName: Erinnerung nach 3 Tagen
                      active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tasks:
    get:
      operationId: get_api_v1_tasks
      tags:
        - tasks
      summary: Get tasks
      description: |
        Returns every contract task the caller is allowed to see. Contract tasks are recurring jobs attached to maintenance contracts (e.g. "quarterly server check"). Requires technician/freelancer role plus MAINTENANCE_CONTRACT_SHOW_TASKS and TASK_ADMINISTRATION.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of contract tasks.
              example:
                meta: {}
                content:
                  - id: 1
                    contractId: 100
                    name: Quartalsweise Server-Wartung
                    nextExecution: 1748256000
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_tasks
      tags:
        - tasks
      summary: Create task
      description: |
        Creates a new contract task. Requires MAINTENANCE_CONTRACT_ADMINISTRATION and that the parent contract is not currently locked or edited by someone else.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Unique identifier of the task
                contractId:
                  type: integer
                  description: Identifier of the maintenance contract the task belongs to
                companyId:
                  type: integer
                  description: Identifier of the company the task is assigned to
                name:
                  type: string
                  description: Name of the task
                text:
                  type: string
                  description: Descriptive text of the task
                date:
                  type: integer
                  format: int64
                  description: Scheduled date of the task as a unix timestamp
                expirationDate:
                  type: integer
                  format: int64
                  description: Date after which the task expires as a unix timestamp
                supportTypeId:
                  type: integer
                  description: Identifier of the support type associated with the task
                supportDuration:
                  type: integer
                  description: Planned support duration in minutes
                preferredEmployeeId:
                  type: integer
                  description: Identifier of the preferred employee for the task
                ticketId:
                  type: integer
                  description: Identifier of the ticket linked to the task
                price:
                  type: number
                  description: Price associated with the task
                active:
                  type: boolean
                  description: Whether the task is currently active
            example:
              contractId: 100
              name: Quartalsweise Server-Wartung
              active: true
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created contract task.
              example:
                meta: {}
                content:
                  id: 1
                  contractId: 100
                  name: Quartalsweise Server-Wartung
                  estimatedDurationMinutes: 120
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tasks
      tags:
        - tasks
      summary: Get tasks with configuration
      description: |
        Returns contract tasks filtered/paginated/sorted using the configuration in the request body. Permission checks are always forced to `true` server-side, so each row in the response respects the caller's actual rights.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                taskIds:
                  type: array
                  description: Restrict results to these task identifiers
                  items:
                    type: object
                companyIds:
                  type: array
                  description: Restrict results to tasks of these companies
                  items:
                    type: object
                linkTypeId:
                  type: integer
                  description: Type identifier of the linked entity to filter by
                linkId:
                  type: integer
                  description: Identifier of the linked entity to filter by
                preferredEmployeeIds:
                  type: array
                  description: Restrict results to tasks preferring these employees
                  items:
                    type: object
                preferredDepartmentIds:
                  type: array
                  description: Restrict results to tasks preferring these departments
                  items:
                    type: object
                search:
                  type: string
                  description: Free-text search term used to filter tasks
                onlyExpired:
                  type: boolean
                  description: Return only expired tasks
                onlyActiveTasks:
                  type: boolean
                  description: Return only active tasks
                withNextExecution:
                  type: boolean
                  description: Include next execution information in the result
                withContract:
                  type: boolean
                  description: Include contract information in the result
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Array of contract tasks matching the configuration.
              example:
                meta: {}
                content:
                  - id: 1
                    contractId: 100
                    name: Quartalsweise Server-Wartung
                    nextExecution: 1748256000
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tasks/series:
    get:
      operationId: get_api_v1_tasks_series
      tags:
        - tasks
      summary: Get task series
      description: |
        Returns the recurrence definition for a contract task, optionally resolved via support/link references.
      parameters:
        - in: query
          name: taskId
          description: (optional) id of the contract task whose series to fetch.
          required: false
          example: 1
          schema:
            type: integer
            default: 0
        - in: query
          name: supportId
          description: (optional) support id used to resolve the task series.
          required: false
          example: 1
          schema:
            type: integer
            default: 0
        - in: query
          name: linkTypeId
          description: (optional) linkTypeId of the related entity (e.g. 11 = ticket).
          required: false
          example: 1
          schema:
            type: integer
            default: 0
        - in: query
          name: linkId
          description: (optional) id of the linked entity.
          required: false
          example: 4711
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Task-series recurrence definition.
              example:
                meta: {}
                content:
                  taskId: 1
                  recurrenceType: MONTHLY
                  interval: 3
                  dayOfMonth: 15
                  endDate: 1779792000
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_tasks_series
      tags:
        - tasks
      summary: Create task series
      description: |
        Creates the recurrence definition for a contract task.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                taskId:
                  type: integer
                  description: Identifier of the task this recurrence series belongs to
                supportId:
                  type: integer
                  description: Identifier of the associated support entry
                linkTypeId:
                  type: integer
                  description: Type identifier of the linked entity
                linkId:
                  type: integer
                  description: Identifier of the linked entity
                seriesType:
                  type: string
                  description: Overall recurrence pattern of the series
                  enum:
                    - DAILY
                    - WEEKLY
                    - MONTHLY
                    - YEARLY
                    - INDIVIDUALLY
                dailyType:
                  type: string
                  description: Sub-pattern used for daily recurrences
                  enum:
                    - NONE
                    - EVERY_X_DAYS
                    - EVERY_WORKINGDAY
                    - EVERY_X_MINUTES_IN_TIMEFRAME
                monthlyType:
                  type: string
                  description: Sub-pattern used for monthly recurrences
                  enum:
                    - NONE
                    - ON_DAY_EVERY_X_MONTH
                    - ON_COUNTED_WEEKDAY_EVERY_X_MONTH
                yearlyType:
                  type: string
                  description: Sub-pattern used for yearly recurrences
                  enum:
                    - NONE
                    - ON_DAY_OF_MONTH_EVERY_X_YEARS
                    - ON_COUNTED_WEEKDAY_OF_MONTH_EVERY_X_YEARS
                firstExecutionDate:
                  type: integer
                  format: int64
                  description: Date of the first execution as a unix timestamp
                nextExecutionDate:
                  type: integer
                  format: int64
                  description: Date of the next scheduled execution as a unix timestamp
                expireDate:
                  type: integer
                  format: int64
                  description: Date after which the series stops recurring as a unix timestamp
            example:
              taskId: 1
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Persisted task-series recurrence definition.
              example:
                meta: {}
                content:
                  taskId: 1
                  recurrenceType: MONTHLY
                  interval: 3
                  dayOfMonth: 15
                  endDate: 1779792000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tasks/series/next:
    post:
      operationId: post_api_v1_tasks_series_next
      tags:
        - tasks
      summary: Calculate next executions of a task series
      description: |
        Given a task series (recurrence rule) and a start date, returns the upcoming execution timestamps. Used by the UI to preview when a recurring contract task will fire next without persisting anything.
      parameters:
        - in: query
          name: startDate
          description: Start date (Unix timestamp) from which to calculate the next executions.
          required: true
          example: 1748256000
          schema:
            type: integer
            format: int64
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                taskId:
                  type: integer
                  description: Identifier of the task this recurrence series belongs to
                supportId:
                  type: integer
                  description: Identifier of the associated support entry
                linkTypeId:
                  type: integer
                  description: Type identifier of the linked entity
                linkId:
                  type: integer
                  description: Identifier of the linked entity
                seriesType:
                  type: string
                  description: Overall recurrence pattern of the series
                  enum:
                    - DAILY
                    - WEEKLY
                    - MONTHLY
                    - YEARLY
                    - INDIVIDUALLY
                dailyType:
                  type: string
                  description: Sub-pattern used for daily recurrences
                  enum:
                    - NONE
                    - EVERY_X_DAYS
                    - EVERY_WORKINGDAY
                    - EVERY_X_MINUTES_IN_TIMEFRAME
                monthlyType:
                  type: string
                  description: Sub-pattern used for monthly recurrences
                  enum:
                    - NONE
                    - ON_DAY_EVERY_X_MONTH
                    - ON_COUNTED_WEEKDAY_EVERY_X_MONTH
                yearlyType:
                  type: string
                  description: Sub-pattern used for yearly recurrences
                  enum:
                    - NONE
                    - ON_DAY_OF_MONTH_EVERY_X_YEARS
                    - ON_COUNTED_WEEKDAY_OF_MONTH_EVERY_X_YEARS
                firstExecutionDate:
                  type: integer
                  format: int64
                  description: Date of the first execution as a unix timestamp
                nextExecutionDate:
                  type: integer
                  format: int64
                  description: Date of the next scheduled execution as a unix timestamp
                expireDate:
                  type: integer
                  format: int64
                  description: Date after which the series stops recurring as a unix timestamp
            example:
              taskId: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Upcoming execution timestamps (unix seconds).
              example:
                meta: {}
                content:
                  - 1748256000
                  - 1755945600
                  - 1763722800
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tasks/{id}:
    delete:
      operationId: delete_api_v1_tasks_id
      tags:
        - tasks
      summary: Delete task
      description: |
        Removes a contract task. Requires MAINTENANCE_CONTRACT_ADMINISTRATION and the parent contract must not be locked or being edited elsewhere.
      parameters:
        - in: path
          name: id
          description: ID of the contract task.
          required: true
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_tasks_id
      tags:
        - tasks
      summary: Get task
      description: |
        Returns one contract task by id. Restricted to technicians and freelancers; standard access checks apply.
      parameters:
        - in: path
          name: id
          description: ID of the contract task.
          required: true
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Contract task.
              example:
                meta: {}
                content:
                  id: 1
                  contractId: 100
                  name: Quartalsweise Server-Wartung
                  estimatedDurationMinutes: 120
                  nextExecution: 1748256000
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tasks_id
      tags:
        - tasks
      summary: Update task
      description: |
        Updates a contract task. The caller must be allowed to edit the parent contract before the merge is applied. Returns the persisted task.
      parameters:
        - in: path
          name: id
          description: ID of the contract task.
          required: true
          example: 42
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the task
                contractId:
                  type: integer
                  description: Identifier of the maintenance contract the task belongs to
                companyId:
                  type: integer
                  description: Identifier of the company the task is assigned to
                name:
                  type: string
                  description: Name of the task
                text:
                  type: string
                  description: Descriptive text of the task
                date:
                  type: integer
                  format: int64
                  description: Scheduled date of the task as a unix timestamp
                expirationDate:
                  type: integer
                  format: int64
                  description: Date after which the task expires as a unix timestamp
                supportTypeId:
                  type: integer
                  description: Identifier of the support type associated with the task
                supportDuration:
                  type: integer
                  description: Planned support duration in minutes
                preferredEmployeeId:
                  type: integer
                  description: Identifier of the preferred employee for the task
                ticketId:
                  type: integer
                  description: Identifier of the ticket linked to the task
                price:
                  type: number
                  description: Price associated with the task
                active:
                  type: boolean
                  description: Whether the task is currently active
            example:
              id: 1
              contractId: 100
              name: Quartalsweise Server-Wartung
              active: true
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Updated contract task.
              example:
                meta: {}
                content:
                  id: 1
                  contractId: 100
                  name: Quartalsweise Server-Wartung
                  estimatedDurationMinutes: 120
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/telephoneSystems:
    get:
      operationId: get_api_v1_telephoneSystems
      tags:
        - calls (user context)
      summary: Get all telephone systems
      description: |
        Lists every configured telephone system (PBX adapter) used by the call-import background thread. Each entry is read from the `tanss.telephoneSystems.<id>.*` properties file and returned as a flat key/value map; entries are sorted by id. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                    example:
                      - id: 1
                        type: AGFEO_ES
                        name: AGFEO ES 622
                        host: 192.168.1.100
                        port: '5060'
                        active: 'true'
                      - id: 2
                        type: STARFACE
                        name: Starface Cloud
                        host: pbx.example.com
                        port: '443'
                        active: 'true'
              example:
                meta: {}
                content:
                  - id: 1
                    type: AGFEO_ES
                    name: AGFEO ES 622
                    host: 192.168.1.100
                    port: '5060'
                    active: 'true'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_telephoneSystems
      tags:
        - calls (user context)
      summary: Create telephone system
      description: |
        Registers a new telephone-system config entry. `type` is mandatory and selects which field set is persisted (host, port, credentials, etc. depend on the PBX vendor). If `id` is omitted, the next free id is auto-assigned; if supplied, it must not collide with an existing entry. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      requestBody:
        description: Telephone-system configuration. `type` is required; the remaining fields depend on the PBX vendor (see TelephoneSystemConfigFieldSet).
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              type: AGFEO_ES
              name: AGFEO ES 622
              host: 192.168.1.100
              port: '5060'
              user: tanss
              password: secret
              active: 'true'
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  type: AGFEO_ES
                  name: AGFEO ES 622
                  host: 192.168.1.100
                  port: '5060'
                  active: 'true'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/telephoneSystems/check:
    post:
      operationId: post_api_v1_telephoneSystems_check
      tags:
        - calls (user context)
      summary: Check connection settings
      description: |
        Probes the PBX with the supplied credentials before persisting them — picks the vendor-specific generator from `type` and invokes its `checkConnection`. Returns 200 with `"check successful"` if reachable; throws on errors so the UI can surface the cause. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      requestBody:
        description: Telephone-system connection candidate. Must contain at least `type`; vendor-specific connection fields (host, port, credentials) are required to actually reach the PBX.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              type: AGFEO_ES
              host: 192.168.1.100
              port: '5060'
              user: tanss
              password: secret
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: string
              example:
                meta: {}
                content: check successful
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/telephoneSystems/intervals:
    get:
      operationId: get_api_v1_telephoneSystems_intervals
      tags:
        - calls (user context)
      summary: Get call-import polling intervals
      description: |
        Returns the global polling intervals of the call-import thread: `refreshInterval` (seconds between two PBX queries) and `queryInterval` (how many days into the past each query reaches). Both are shared across every configured telephone system. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      refreshInterval:
                        type: integer
                      queryInterval:
                        type: integer
              example:
                meta: {}
                content:
                  refreshInterval: 60
                  queryInterval: 7
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_telephoneSystems_intervals
      tags:
        - calls (user context)
      summary: Update call-import polling intervals
      description: |
        Sets one or both polling intervals for the call importer. Only positive integers are accepted; missing or invalid fields keep the current value. Returns the freshly stored values. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      requestBody:
        description: New interval values. Either or both fields may be supplied; non-positive values are ignored.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                refreshInterval:
                  type: integer
                  description: Seconds between two PBX queries.
                queryInterval:
                  type: integer
                  description: Days into the past each query reaches.
            example:
              refreshInterval: 60
              queryInterval: 7
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      refreshInterval:
                        type: integer
                      queryInterval:
                        type: integer
              example:
                meta: {}
                content:
                  refreshInterval: 30
                  queryInterval: 14
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/telephoneSystems/restart:
    get:
      operationId: get_api_v1_telephoneSystems_restart
      tags:
        - calls (user context)
      summary: Restart call-import thread
      description: |
        Reboots the background call-import thread. For each configured telephone system the importer either restarts an existing worker, starts one that was newly added, or stops one that was removed. Call this after creating, updating or deleting telephone-system entries. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: string
              example:
                meta: {}
                content: ''
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/telephoneSystems/{id}:
    delete:
      operationId: delete_api_v1_telephoneSystems_id
      tags:
        - calls (user context)
      summary: Delete telephone system
      description: |
        Removes the telephone-system entry with the given id from the properties file (all `tanss.telephoneSystems.<id>.*` keys are dropped). The change does not stop the running import thread on its own — call `restart` afterwards to apply it. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the telephone system.
          example: 1
          schema:
            type: integer
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_telephoneSystems_id
      tags:
        - calls (user context)
      summary: Get telephone system by id
      description: |
        Returns the configuration map for one telephone system, loaded from the `tanss.telephoneSystems.<id>.*` properties. Throws 404 if the id is unknown. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the telephone system.
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  type: AGFEO_ES
                  name: AGFEO ES 622
                  host: 192.168.1.100
                  port: '5060'
                  active: 'true'
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_telephoneSystems_id
      tags:
        - calls (user context)
      summary: Update telephone system
      description: |
        Overwrites the configuration of an existing telephone system. The body must include `id` (must match the path) and `type`; the persisted field set is derived from the stored `type` (vendor-specific). Call `restart` afterwards to apply the change to the running import thread. Requires technician/freelancer plus `ONLINE_SYSTEM_CONFIGURATION`.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the telephone system.
          example: 1
          schema:
            type: integer
      requestBody:
        description: Updated telephone-system configuration. `id` (must match the path) and `type` are required.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              id: 1
              type: AGFEO_ES
              name: AGFEO ES 622
              host: 192.168.1.100
              port: '5060'
              user: tanss
              password: secret
              active: 'true'
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  id: 1
                  type: AGFEO_ES
                  name: AGFEO ES 622
                  host: 192.168.1.100
                  port: '5060'
                  active: 'true'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tempCache/{type}:
    delete:
      operationId: delete_api_v1_tempCache_type
      tags:
        - util routes
      summary: Delete temp cache
      description: |
        Removes the temp-cache row of `type` belonging to the logged-in user. Used when the client discards an
        unsaved draft (form data, search context, ...) backed by the server-side temp cache. Returns `400` if
        no temp cache of that type exists for the user.
      parameters:
        - in: path
          name: type
          required: true
          description: Temp-cache type for the logged-in user (e.g. a draft form context).
          schema:
            type: string
          example: TICKET_DRAFT
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_tempCache_type
      tags:
        - util routes
      summary: Get temp cache
      description: |
        Returns the currently-stored temp-cache value of `type` for the logged-in user, deserialised according to
        its type. The response also exposes the cache's `modified` timestamp and
        `ageInSeconds` via `properties.extras` so the client can decide whether the draft is stale.

        Returns `400` (DATA_NOT_FOUND) when no temp cache of that type exists for the user.
      parameters:
        - in: path
          name: type
          required: true
          description: Temp-cache type for the logged-in user (e.g. a draft form context).
          schema:
            type: string
          example: TICKET_DRAFT
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Deserialised content for the given object; shape depends on the type.
              example:
                meta:
                  properties:
                    extras:
                      modified:
                        value: 1748256000
                      ageInSeconds:
                        value: 120
                content:
                  draftTitle: VPN funktioniert nicht
                  draftDescription: Kunde meldet Probleme mit dem VPN.
                  linkedCompanyId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_tempCache_type
      tags:
        - util routes
      summary: Create or update temp cache
      description: |
        Persists (or updates) a temp-cache entry of `type` for the logged-in user. The request body is the raw
        serialised payload (handled as a string and stored verbatim) — it is deserialised according to its type
        on read. The endpoint always returns the freshly deserialised content together with the new `modified`
        timestamp, so the client can confirm the round-trip.
      parameters:
        - in: path
          name: type
          required: true
          description: Temp-cache type for the logged-in user (e.g. a draft form context).
          schema:
            type: string
          example: TICKET_DRAFT
      requestBody:
        description: Raw serialised payload (no JSON wrapping). Shape depends on the temp-cache type.
        required: true
        content:
          application/json:
            schema:
              type: string
            example: '{"draftTitle":"VPN funktioniert nicht","draftDescription":"Kunde meldet..."}'
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Deserialised content for the given object (echo of the saved payload).
              example:
                meta:
                  properties:
                    extras:
                      modified:
                        value: 1748256000
                      ageInSeconds:
                        value: 0
                content:
                  draftTitle: VPN funktioniert nicht
                  draftDescription: Kunde meldet Probleme mit dem VPN.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates:
    put:
      operationId: put_api_v1_templates
      tags:
        - templates
      summary: Query templates
      description: |
        Returns persisted records filtered by the supplied object
        (template type, name/text search, sort, paging, ...). The response is filtered through the small variant of
        the template filter so the JSON `content` field is omitted; use `GET /templates/{id}` to load the full body.

        Visibility is enforced based on the caller's permissions (own templates, assigned templates,
        admin-of-type templates).
      requestBody:
        description: object describing the query (type, search, paging).
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: Type of object the templates apply to
                  enum:
                    - CONTRACT
                    - TICKET
                    - PROJECT
                    - CHECKLIST
                    - PERSONALCOMPUTER
                    - PERIPHERY
                    - COMPONENT
                    - SOFTWARELICENSE
                    - PLANNING
                    - STATISTIC_ALL_SERVICES_BY_DAY
                    - SUPPORTCONFIGURATION
                    - TICKETCONFIGURATION
                    - SUPPORT
                    - SUPPORT_PERSONAL
                    - STATISTICS_APPROVAL_OF_SUPPORTS
                name:
                  type: string
                  description: Name filter for matching templates
                loadTemplates:
                  type: boolean
                  description: Whether the full template contents are loaded
                companyId:
                  type: integer
                  description: Identifier of the company the templates are scoped to
                employeeId:
                  type: integer
                  description: Identifier of the employee the templates are scoped to
                customerEmployeeId:
                  type: integer
                  description: Identifier of the customer contact the templates are scoped to
                activeFilter:
                  type: string
                  description: Filter for including active, inactive, or all templates
                  enum:
                    - ACTIVE_ONLY
                    - INACTIVE_ONLY
                    - ACTIVE_AND_INACTIVE
                ticketId:
                  type: integer
                  description: Identifier of the ticket the templates relate to
            example:
              type: TICKET
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of records (without `content` body).
              example:
                meta: {}
                content:
                  - id: 42
                    name: Standard-Ticket-Vorlage
                    type: TICKET
                    createdByEmployeeId: 17
                    active: true
                  - id: 43
                    name: VPN-Konfiguration
                    type: TICKET
                    createdByEmployeeId: 17
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/assignments:
    delete:
      operationId: delete_api_v1_templates_assignments
      tags:
        - templates
      summary: Delete template assignment
      description: |
        Removes the assignment binding (`templateId`, `linkTypeId`, `linkId`) so the template is no longer offered
        to that company / employee / department / ticket type, ... The caller must be allowed to modify the
        parent template.
      parameters:
        - in: query
          name: templateId
          required: true
          description: Id of the object template the assignment belongs to.
          schema:
            type: integer
          example: 42
        - in: query
          name: linkTypeId
          required: true
          description: Type of the linked entity (company, employee, department, ticket type, ...).
          schema:
            type: integer
          example: 1
        - in: query
          name: linkId
          required: true
          description: Id of the linked entity to unbind from the template.
          schema:
            type: integer
          example: 4711
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_templates_assignments
      tags:
        - templates
      summary: Create template assignment
      description: |
        Binds a template to a target entity (company, employee, department, ticket type, ...) so that it appears as
        available when working with that entity. Standard admin permission checks apply, and the caller must be
        allowed to modify the parent template.
      requestBody:
        description: JSON request body.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              templateId: 42
              linkTypeId: 1
              linkId: 100023
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created object.
              example:
                meta: {}
                content:
                  templateId: 42
                  linkTypeId: 1
                  linkId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/assignments/{templateId}:
    get:
      operationId: get_api_v1_templates_assignments_templateId
      tags:
        - templates
      summary: Get template assignments
      description: |
        Returns the list of records for the given template (which companies, employees,
        departments, ticket types, ... a template is bound to). Each result is decorated with linked-entity names
        so the client can display human-readable labels.

        The caller must be allowed to edit the template (typically: be the creator or hold the admin permission
        for that template type).
      parameters:
        - in: path
          name: templateId
          required: true
          description: Id of the object template whose assignments are requested.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of records for the template.
              example:
                meta: {}
                content:
                  - templateId: 42
                    linkTypeId: 1
                    linkId: 100023
                  - templateId: 42
                    linkTypeId: 3
                    linkId: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/createFrom/{id}:
    post:
      operationId: post_api_v1_templates_createFrom_id
      tags:
        - templates
      summary: Create entity from template
      description: |
        Creates a real entity (ticket, contract, document, ...) from the persisted template identified by `id`,
        using the supplied vars body to fill placeholder fields. Returns a object
        with the template `type` and the id of the newly-created entity.

        The caller must be permitted to create from this template — assignments and per-type permissions are checked.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the persisted template to create a new entity from.
          schema:
            type: integer
          example: 42
      requestBody:
        description: JSON body containing the vars (field values, linked entities, ...) used to materialise the template.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              fields:
                title: VPN funktioniert nicht
                description: Kunde meldet Probleme mit dem VPN.
              linkedEntities:
                employees:
                  '17':
                    name: Max Mustermann
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Object with the template `type` and the id of the created entity.
              example:
                meta: {}
                content:
                  type: TICKET
                  entityId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/createFrom/{type}/{id}:
    post:
      operationId: post_api_v1_templates_createFrom_type_id
      tags:
        - templates
      summary: Create entity from template (typed alias)
      description: |
        Convenience alias for `POST /templates/createFrom/{id}` that accepts an explicit template `type` in the URL.
        Behaviour and permission checks are identical to the un-typed route. Useful when the client wants the URL
        to record which template type it expected, for routing or telemetry.
      parameters:
        - in: path
          name: type
          required: true
          description: Template type expected for this template (e.g. TICKET).
          schema:
            type: string
          example: TICKET
        - in: path
          name: id
          required: true
          description: Id of the persisted template to create a new entity from.
          schema:
            type: integer
          example: 42
      requestBody:
        description: JSON body containing the vars used to materialise the template.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Body of a template.
            example:
              fields:
                title: VPN funktioniert nicht
                description: Kunde meldet Probleme mit dem VPN.
              linkedEntities:
                employees:
                  '17':
                    name: Max Mustermann
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Object with the template `type` and the id of the created entity.
              example:
                meta: {}
                content:
                  type: TICKET
                  entityId: 100023
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/import/{templateType}:
    post:
      operationId: post_api_v1_templates_import_templateType
      tags:
        - templates
      summary: Import template from JSON
      description: |
        Imports a template of `templateType` from a foreign-system JSON dump. The caller's permission to import
        this template type is verified, the body is deserialised and validated, and the resulting
        object is then persisted. Foreign linked-entity matchings are checked before
        persisting; if `pendingImportId` is supplied, the matching pending-import is consumed as part of the save.
      parameters:
        - in: path
          name: templateType
          required: true
          description: Type of the template being imported (e.g. TICKET).
          schema:
            type: string
          example: TICKET
        - in: query
          name: pendingImportId
          required: false
          description: Optional id of the pending import consumed when saving the template.
          schema:
            type: integer
            default: 0
          example: 1
      requestBody:
        description: JSON dump of the foreign template; fields depend on `templateType`.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              name: VPN-Konfiguration (import)
              description: Importiert aus Fremdsystem
              tucId: 00000000-0000-0000-0000-000000000001
              fields:
                - key: title
                  value: VPN funktioniert nicht
              assignments:
                companies:
                  - 100023
                companyTypes: []
                employees: []
                employeeDepartments:
                  - 3
                customerEmployees: []
                customerEmployeeCategories: []
                ticketTypesVisibilities: []
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created object.
              example:
                meta: {}
                content:
                  id: 42
                  name: VPN-Konfiguration (import)
                  type: TICKET
                  createdByEmployeeId: 17
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/importMatchings:
    post:
      operationId: post_api_v1_templates_importMatchings
      tags:
        - templates
      summary: Save import matchings
      description: |
        Persists the user's choices for resolving foreign-system → local matchings (which foreign company id maps
        to which local company id, etc.) so subsequent imports of the same source can be processed without
        prompting. Each row in the body is created individually. Returns the same list
        back to confirm persistence.

        Requires the admin-of-imports permission.
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - linkType: COMPANY
                foreignId: company-foreign-123
                foreignName: Beispiel GmbH (legacy)
                localId: 100023
              - linkType: EMPLOYEE
                foreignId: user-foreign-42
                foreignName: max.mustermann@legacy
                localId: 17
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The persisted records.
              example:
                meta: {}
                content:
                  - linkType: COMPANY
                    foreignId: company-foreign-123
                    foreignName: Beispiel GmbH (legacy)
                    localId: 100023
                  - linkType: EMPLOYEE
                    foreignId: user-foreign-42
                    foreignName: max.mustermann@legacy
                    localId: 17
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_templates_importMatchings
      tags:
        - templates
      summary: Get import matchings pop-up
      description: |
        Builds the data used to populate the import-matching pop-up: for each foreign id in the body it returns
        the available local entities to choose from. The result object carries selection lists
        grouped by linked-entity type so the UI can render the dropdowns.

        Requires the same admin-of-imports permission as the POST variant.
      requestBody:
        description: Array of object requests describing the foreign ids that need resolving.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - linkType: COMPANY
                foreignId: company-foreign-123
                foreignName: Beispiel GmbH (legacy)
              - linkType: EMPLOYEE
                foreignId: user-foreign-42
                foreignName: max.mustermann@legacy
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: 'Payload: object populated with selection lists per linked-entity type.'
              example:
                meta: {}
                content:
                  matchings:
                    - linkType: COMPANY
                      foreignId: company-foreign-123
                      foreignName: Beispiel GmbH (legacy)
                      candidates:
                        - id: 100023
                          name: Beispiel GmbH
                        - id: 100024
                          name: Beispiel AG
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/pendingImport/{id}:
    get:
      operationId: get_api_v1_templates_pendingImport_id
      tags:
        - templates
      summary: Get pending import by id
      description: |
        Returns a single object (a queued foreign-system import not yet committed) with its full
        detail filter applied, so the client can render the full match-resolution view.

        Permission is enforced by the standard CRUD flow.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the pending import to retrieve.
          schema:
            type: string
          example: '42'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: A single object with full details.
              example:
                meta: {}
                content:
                  id: 42
                  type: TICKET
                  createdByEmployeeId: 17
                  createdAt: 1748256000
                  status: PENDING
                  source: legacy-system
                  payload:
                    title: VPN funktioniert nicht
                    description: Importiert aus Fremdsystem
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/pendingImports/{type}:
    get:
      operationId: get_api_v1_templates_pendingImports_type
      tags:
        - templates
      summary: List pending imports by type
      description: |
        Returns all records for the given object. Each row is filtered through the
        standard object filter so heavy payload columns are stripped from the list view.

        Standard permission checks apply.
      parameters:
        - in: path
          name: type
          required: true
          description: Template type to list pending imports for (e.g. TICKET).
          schema:
            type: string
          example: TICKET
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of records for the given type.
              example:
                meta: {}
                content:
                  - id: 42
                    type: TICKET
                    createdByEmployeeId: 17
                    createdAt: 1748256000
                    status: PENDING
                    source: legacy-system
                  - id: 43
                    type: TICKET
                    createdByEmployeeId: 17
                    createdAt: 1748255000
                    status: PENDING
                    source: legacy-system
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/supportProfileConvert/{id}:
    get:
      operationId: get_api_v1_templates_supportProfileConvert_id
      tags:
        - templates
      summary: Convert legacy support template
      description: |
        Converts an old-style PHP-era support template (identified by `id`) into the new
        object shape, returning the converted object without persisting it. Used for
        one-shot migration / preview from the admin UI.

        Note: the route is documented
        for backwards-compatibility planning only.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the legacy support template to convert.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The converted object.
              example:
                meta: {}
                content:
                  id: 0
                  legacyId: 42
                  name: Legacy-Support-Vorlage
                  categoryId: 2
                  entries: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/type/{templateType}:
    get:
      operationId: get_api_v1_templates_type_templateType
      tags:
        - templates
      summary: List templates by type
      description: |
        Returns the list of persisted templates for `templateType`, sized down to the small filter (no full body
        content). Permissions control who can list them, and visibility-filtered
        persist-template rows are decorated with their list-properties (e.g. category names).

        When `showAll=true`, visibility / assignment filters are skipped — used by admin views (notably for
        contract templates) that need to see every template regardless of assignment.
      parameters:
        - in: path
          name: templateType
          required: true
          description: Template type to list persisted templates for (e.g. TICKET).
          schema:
            type: string
          example: TICKET
        - in: query
          name: showAll
          required: false
          description: When true, skips visibility/assignment filters (admin views).
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of records (small filter).
              example:
                meta: {}
                content:
                  - id: 42
                    name: Standard-Ticket-Vorlage
                    type: TICKET
                    createdByEmployeeId: 17
                    active: true
                  - id: 43
                    name: VPN-Konfiguration
                    type: TICKET
                    createdByEmployeeId: 17
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/type/{templateType}/fields:
    get:
      operationId: get_api_v1_templates_type_templateType_fields
      tags:
        - templates
      summary: Get template fields for type
      description: |
        Returns the catalogue of fields available for templates of `templateType` (TICKET, CONTRACT, DEVICE, ...).
        Each field declaration tells the editor which key, label, data type, and group it belongs to, so the UI can
        render the "fields to include" checklist when saving a new template.
      parameters:
        - in: path
          name: templateType
          required: true
          description: Template type whose available fields are requested (e.g. TICKET).
          schema:
            type: string
          example: TICKET
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of template-field descriptors for this type.
              example:
                meta: {}
                content:
                  - key: title
                    label: Titel
                    type: STRING
                  - key: description
                    label: Beschreibung
                    type: TEXT
                  - key: priority
                    label: Prioritaet
                    type: INTEGER
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/update/{updateTemplateId}/with/{withEntityId}:
    put:
      operationId: put_api_v1_templates_update_updateTemplateId_with_withEntityId
      tags:
        - templates
      summary: Update template by replacing it with another entity
      description: |
        Replaces the persisted template `updateTemplateId` with a fresh snapshot taken from entity `withEntityId`,
        using the body to override the template `name` (optional) and selected `fields`. Useful when a user wants
        to "refresh" a template from a more current source entity.

        The caller must be allowed to update this template (the standard CRUD checks apply).
      parameters:
        - in: path
          name: updateTemplateId
          required: true
          description: Id of the persisted template to update.
          schema:
            type: integer
          example: 42
        - in: path
          name: withEntityId
          required: true
          description: Id of the source entity to refresh the template from.
          schema:
            type: integer
          example: 4711
      requestBody:
        description: JSON body with optional new `name` and selected `fields`.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              name: VPN-Konfiguration (v2)
              fields:
                - key: title
                  include: true
                - key: description
                  include: true
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated object.
              example:
                meta: {}
                content:
                  id: 42
                  name: VPN-Konfiguration (v2)
                  type: TICKET
                  createdByEmployeeId: 17
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/{id}:
    get:
      operationId: get_api_v1_templates_id
      tags:
        - templates
      summary: Get template by id
      description: Returns a single template by its id.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the template.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The requested template.
              example:
                meta: {}
                content:
                  id: 42
                  name: Standard template
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/{templateType}/export/{id}:
    get:
      operationId: get_api_v1_templates_templateType_export_id
      tags:
        - templates
      summary: Export template by type and id
      description: |
        Renders a template of `templateType` from the persisted source entity `id` and prepares the result for
        export (linked entities normalised, internal-only fields stripped). The output is suitable to be fed back
        into `POST /templates/import/{templateType}` on another TANSS instance.

        The caller must be allowed to save / export this template.
      parameters:
        - in: path
          name: templateType
          required: true
          description: Type of the template to export (e.g. TICKET).
          schema:
            type: string
          example: TICKET
        - in: path
          name: id
          required: true
          description: Id of the source entity to render the template from.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Export-ready template JSON.
              example:
                meta: {}
                content:
                  name: VPN-Konfiguration
                  type: TICKET
                  tucId: 00000000-0000-0000-0000-000000000001
                  fields:
                    - key: title
                      value: VPN funktioniert nicht
                  assignments:
                    companies: []
                    companyTypes: []
                    employees: []
                    employeeDepartments: []
                    customerEmployees: []
                    customerEmployeeCategories: []
                    ticketTypesVisibilities: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/templates/{templateType}/{id}:
    post:
      operationId: post_api_v1_templates_templateType_id
      tags:
        - templates
      summary: Create template from existing entity
      description: |
        Snapshots an existing entity (`id`) into a new persisted template of `templateType`, using the body to
        override the template `name` and selected `fields`. When `preview=true`, the resulting template is
        returned without being saved — used by the "preview" button in the template editor.

        The caller must be allowed to save the template for this type.
      parameters:
        - in: path
          name: templateType
          required: true
          description: Type of template to create from the entity (e.g. TICKET).
          schema:
            type: string
          example: TICKET
        - in: path
          name: id
          required: true
          description: Id of the existing entity to snapshot into a template.
          schema:
            type: integer
          example: 42
        - in: query
          name: preview
          required: false
          description: When true, returns the materialised template without persisting it.
          schema:
            type: boolean
            default: false
          example: true
      requestBody:
        description: JSON body with the new template's `name` and selected `fields`.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              name: Standard-Ticket-Vorlage
              fields:
                - key: title
                  include: true
                - key: description
                  include: true
              active: true
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created (or, in preview mode, materialised) object.
              example:
                meta: {}
                content:
                  id: 42
                  name: Standard-Ticket-Vorlage
                  type: TICKET
                  createdByEmployeeId: 17
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/textModules:
    get:
      operationId: get_api_v1_textModules
      tags:
        - textModules
      summary: Get all text modules
      description: |
        Returns every object (text snippet / canned response) visible to the caller. Visibility is
        enforced per row (assignments to types, departments, or specific employees).

        Requires a technician or freelancer — customer logins are blocked; standard permission checks apply.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of records.
              example:
                meta: {}
                content:
                  - id: 42
                    name: Begruessung
                    title: Sehr geehrte Damen und Herren
                    content: |-
                      Sehr geehrte Damen und Herren,

                      vielen Dank fuer Ihre Anfrage.
                    creatorId: 17
                    html: false
                    types:
                      - TICKET_RESPONSE
                  - id: 43
                    name: VPN-Anleitung
                    title: VPN einrichten
                    content: <p>Bitte folgen Sie...</p>
                    creatorId: 17
                    html: true
                    types:
                      - TICKET_RESPONSE
                      - MAIL
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_textModules
      tags:
        - textModules
      summary: Create text module
      description: |
        Creates a new object. The `creatorId` is set server-side from the logged-in user. After insert,
        type / department / employee assignments contained in the body are persisted as well.

        Standard admin permission checks apply.
      requestBody:
        description: JSON request body.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              name: VPN-Anleitung
              title: VPN einrichten
              content: <p>Bitte folgen Sie...</p>
              html: true
              types:
                - TICKET_RESPONSE
                - MAIL
              departments:
                - 3
              employees: []
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created object.
              example:
                meta: {}
                content:
                  id: 43
                  name: VPN-Anleitung
                  title: VPN einrichten
                  content: <p>Bitte folgen Sie...</p>
                  creatorId: 17
                  html: true
                  types:
                    - TICKET_RESPONSE
                    - MAIL
                  departments:
                    - 3
                  employees: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/textModules/properties:
    get:
      operationId: get_api_v1_textModules_properties
      tags:
        - textModules
      summary: Get text module list properties
      description: |
        Returns the list-properties payload (columns, filters, default sort, ...) used by the client to render the
        text-module overview. Visibility-restricted columns are omitted based on the caller's permissions.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List-properties payload for the text-module list.
              example:
                meta: {}
                content:
                  columns:
                    - key: name
                      label: Name
                      sortable: true
                    - key: title
                      label: Betreff
                      sortable: true
                  defaultSort:
                    key: name
                    direction: ASC
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/textModules/type/{type}:
    get:
      operationId: get_api_v1_textModules_type_type
      tags:
        - textModules
      summary: Get text modules of type
      description: |
        Returns text modules assigned to the given object (e.g. TICKET_RESPONSE, MAIL, SMS) and visible
        to the caller. Visibility is enforced per row.

        Requires a technician or freelancer — customer logins are blocked; standard permission checks apply.
      parameters:
        - in: path
          name: type
          required: true
          description: Text module type to list (e.g. TICKET_RESPONSE, MAIL, SMS).
          schema:
            type: string
          example: TICKET_RESPONSE
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of records of the requested type.
              example:
                meta: {}
                content:
                  - id: 42
                    name: Begruessung
                    title: Sehr geehrte Damen und Herren
                    content: |-
                      Sehr geehrte Damen und Herren,

                      vielen Dank fuer Ihre Anfrage.
                    creatorId: 17
                    html: false
                    types:
                      - TICKET_RESPONSE
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/textModules/{id}:
    get:
      operationId: get_api_v1_textModules_id
      tags:
        - textModules
      summary: Get text module by id
      description: Returns a single text module by its id.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the text module.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The requested text module.
              example:
                meta: {}
                content:
                  id: 42
                  name: Standard text module
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/globalPanels:
    get:
      operationId: get_api_v1_ticketBoard_globalPanels
      tags:
        - ticket board
      summary: Get global panels
      description: |
        Returns every ticket board panel with visibility `EVERYBODY` — the panels that are shared across the whole tenant, regardless of who created them or which departments/employees they are scoped to. The caller still needs ticket board access (technician/freelancer with `TICKET_BOARD_ACCESS`, dashboard viewer, or board administrator).
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of global objects.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Offene Tickets
                    projectId: 0
                    employeeId: 27
                    panelType: DEFAULT
                    registerType: TICKET_STATUS
                    visibility: EVERYBODY
                    ticketStatus:
                      - panelId: 1
                        statusId: 1
                  - id: 4
                    name: Eskalationen
                    projectId: 0
                    employeeId: 27
                    panelType: DEFAULT
                    registerType: TICKET_STATUS
                    visibility: EVERYBODY
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/panel/filters:
    put:
      operationId: put_api_v1_ticketBoard_panel_filters
      tags:
        - ticket board
      summary: Update multiple panel filters
      description: |
        Bulk-updates the calling employee's panel-filter rows (one per board panel). The service forces `employeeId` to the session user, recomputes the `rank` ordering of visible filters (the array order yields the new ranks, hidden panels are forced to `rank=0`) and persists every entry. Used to re-sort the panel list and toggle the hidden flag in one go.
      requestBody:
        description: Array of objects.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: object
                type: object
            example:
              - panelId: 1
                includeProjects: true
                includeSubTickets: true
                includeWaitingStates: false
                includeDoneTickets: false
                onlyOwnTickets: true
                onlyOverdueTickets: false
                onlyTicketsWithOwnRoles: false
                hidden: false
                rank: 1
              - panelId: 4
                includeProjects: false
                includeSubTickets: true
                includeWaitingStates: false
                includeDoneTickets: false
                onlyOwnTickets: false
                onlyOverdueTickets: true
                hidden: false
                rank: 2
              - panelId: 7
                hidden: true
                rank: 0
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of records with the recalculated `rank` values.
              example:
                meta: {}
                content:
                  - panelId: 1
                    employeeId: 27
                    includeProjects: true
                    includeSubTickets: true
                    onlyOwnTickets: true
                    hidden: false
                    rank: 1
                  - panelId: 4
                    employeeId: 27
                    includeProjects: false
                    onlyOverdueTickets: true
                    hidden: false
                    rank: 2
                  - panelId: 7
                    employeeId: 27
                    hidden: true
                    rank: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/panel/{panelId}/filters:
    get:
      operationId: get_api_v1_ticketBoard_panel_panelId_filters
      tags:
        - ticket board
      summary: Get panel filters
      description: |
        Returns the calling employee's filter row for a single ticket board panel — the per-user toggles that decide which tickets show up inside that panel (include projects/sub tickets/waiting/done, only own, only overdue, ...) plus the panel's rank/hidden state. Responds 404 if the user has not yet customised this panel.
      parameters:
        - in: path
          name: panelId
          required: true
          description: Id of the ticket board panel whose filter row is returned.
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The object row for (panelId, current user).
              example:
                meta: {}
                content:
                  panelId: 1
                  employeeId: 27
                  includeProjects: true
                  includeSubTickets: true
                  includeWaitingStates: false
                  includeDoneTickets: false
                  onlyOwnTickets: true
                  onlyTicketsFromEmployee: 0
                  onlyOverdueTickets: false
                  onlyTicketsWithOwnRoles: false
                  hidden: false
                  rank: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_ticketBoard_panel_panelId_filters
      tags:
        - ticket board
      summary: Update panel filters
      description: |
        Upserts the calling employee's filter row for a single ticket board panel: if a row already exists for (panelId, current user) it is updated, otherwise a new one is created on the fly. `employeeId` is always overridden with the session user, and hidden panels are forced to `rank=0` before saving.
      parameters:
        - in: path
          name: panelId
          required: true
          description: Id of the ticket board panel whose filter row is upserted.
          schema:
            type: integer
          example: 1
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                panelId:
                  type: integer
                  description: Identifier of the ticket board panel this filter belongs to
                employeeId:
                  type: integer
                  description: Identifier of the employee who owns this panel filter
                includeProjects:
                  type: boolean
                  description: Whether project tickets are included
                includeSubTickets:
                  type: boolean
                  description: Whether sub-tickets are included
                includeWaitingStates:
                  type: boolean
                  description: Whether tickets in waiting states are included
                includeDoneTickets:
                  type: boolean
                  description: Whether completed tickets are included
                onlyOwnTickets:
                  type: boolean
                  description: Whether to show only the current user's own tickets
                onlyTicketsFromEmployee:
                  type: integer
                  description: Restrict to tickets from this employee identifier
                onlyOverdueTickets:
                  type: boolean
                  description: Whether to show only overdue tickets
                onlyTicketsWithOwnRoles:
                  type: boolean
                  description: Whether to show only tickets matching the user's own roles
                hidden:
                  type: boolean
                  description: Whether the panel is hidden
                rank:
                  type: integer
                  description: Sort order position of the panel
            example:
              includeProjects: true
              includeSubTickets: true
              includeWaitingStates: false
              includeDoneTickets: false
              onlyOwnTickets: true
              onlyTicketsFromEmployee: 0
              onlyOverdueTickets: false
              onlyTicketsWithOwnRoles: false
              hidden: false
              rank: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created/updated object row.
              example:
                meta: {}
                content:
                  panelId: 1
                  employeeId: 27
                  includeProjects: true
                  includeSubTickets: true
                  includeWaitingStates: false
                  includeDoneTickets: false
                  onlyOwnTickets: true
                  onlyOverdueTickets: false
                  hidden: false
                  rank: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketBoard/panels:
    get:
      operationId: get_api_v1_ticketBoard_panels
      tags:
        - ticket board
      summary: Get panels administration
      description: |
        Returns the full list of ticket board panels (all employees, all visibilities) for the administration view, with each panel's transient relations (companies, departments, employees, tags, ticket types/status, visibilities) filled. Restricted to administrators: requires `TICKET_BOARD_ACCESS`, `CREATE_GLOBAL_TICKET_BOARD_PANELS` and `TICKET_BOARD_ADMINISTRATION`.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of all object entries with their transient relations populated.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Offene Tickets
                    projectId: 0
                    employeeId: 27
                    panelType: DEFAULT
                    registerType: TICKET_STATUS
                    visibility: EVERYBODY
                    departments:
                      - panelId: 1
                        departmentId: 4
                  - id: 9
                    name: Mein Backlog
                    projectId: 0
                    employeeId: 42
                    panelType: DEFAULT
                    registerType: TICKET_STATUS
                    visibility: ONLY_FOR_MYSELF
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/ticketWorkflows:
    get:
      operationId: get_api_v1_ticketWorkflows
      tags:
        - ticket workflows
      summary: Get ticket workflows
      description: |-
        Returns all configured ticket workflows together with their state graph. A
        workflow drives multi-step processes (e.g. onboarding) attached to tickets.
        Requires the caller to be a technician or freelancer.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: List of configured ticket workflows.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Customer onboarding
                    active: true
                    states:
                      - id: 10
                        name: Initial mail
                        rank: 1
                      - id: 11
                        name: Setup meeting
                        rank: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/absentTechnicians:
    get:
      operationId: get_api_v1_tickets_absentTechnicians
      tags:
        - tickets
      summary: Get absent technician tickets
      description: |-
        Returns open tickets currently assigned to technicians who are marked as absent
        (vacation, sick leave, etc.). Used by dispatchers to identify work that needs to
        be re-assigned while the owner is away. Requires the caller to be a technician
        or freelancer.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: List of tickets assigned to absent technicians.
              example:
                meta: {}
                content:
                  - id: 4711
                    companyId: 100023
                    title: Festplatte defekt
                    statusId: 1
                    typeId: 1
                    assignedToEmployeeId: 5
                    deadlineDate: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/assignments/flags:
    get:
      operationId: get_api_v1_tickets_assignments_flags
      tags:
        - tickets
      summary: Get assignment flags
      description: |-
        Returns the flag icons (warnings, contract status indicators, etc.) shown next
        to an assignment in the ticket header. The caller must have access to the
        `(linkTypeId, linkId)` assignment. **Deprecated** — prefer
        `GET /api/v1/assignments/flags` on the assignment controller.
      parameters:
        - in: query
          name: linkTypeId
          description: Type id of the assignment (which kind of entity is linked).
          example: 1
          required: true
          schema:
            type: integer
        - in: query
          name: linkId
          description: Id of the linked entity within the given link type.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: List of flag icons to render in the ticket header.
              example:
                meta: {}
                content:
                  - icon: warning
                    tooltip: SLA contract expired
                    color: '#d9534f'
                  - icon: lock
                    tooltip: Internal device
                    color: '#5bc0de'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/assignments/{companyId}:
    get:
      operationId: get_api_v1_tickets_assignments_companyId
      tags:
        - tickets
      summary: Get assignements for company
      description: |-
        Returns all assignable entities (devices, contracts, software, licenses, etc.)
        belonging to a company, grouped by type. Used to populate the "Zuordnung" picker
        when assigning a ticket to a concrete asset. Set `branches=true` to also
        include items from branch companies.
      parameters:
        - in: path
          name: companyId
          description: Id of the company whose assignable entities should be returned.
          example: 100023
          required: true
          schema:
            type: integer
        - in: query
          name: branches
          description: When 'true', also include assignable items from branch companies.
          example: 'false'
          required: false
          schema:
            type: string
            default: 'false'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: Map of assignable entity groups (devices, contracts, software, etc.).
              example:
                meta: {}
                content:
                  devices:
                    - linkTypeId: 2
                      linkId: 314
                      name: Workstation-PC-12
                  contracts:
                    - linkTypeId: 7
                      linkId: 88
                      name: Service contract 2026
                  software: []
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/companyTicketsForMerge/{ticketId}:
    get:
      operationId: get_api_v1_tickets_companyTicketsForMerge_ticketId
      tags:
        - tickets
      summary: Get open tickets from company merge
      description: |-
        Returns the list of open tickets at the same company that are eligible to be
        merged with the given ticket. Used by the "Tickets zusammenführen" picker —
        the result is filtered to exclude the source ticket itself, archived tickets,
        and tickets that the caller cannot access.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose company's mergeable tickets should be returned.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Open tickets at the same company that can be merge targets.
              example:
                meta: {}
                content:
                  - id: 4801
                    companyId: 100023
                    title: Drucker-Problem
                    statusId: 1
                    typeId: 1
                    assignedToEmployeeId: 5
                  - id: 4912
                    companyId: 100023
                    title: Outlook startet nicht
                    statusId: 1
                    typeId: 1
                    assignedToEmployeeId: 7
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/companyTicketsForOtherTicket/{ticketId}:
    get:
      operationId: get_api_v1_tickets_companyTicketsForOtherTicket_ticketId
      tags:
        - tickets
      summary: Get open tickets from company
      description: |-
        Returns the open tickets at the same company that can be selected as the target
        when assigning the current ticket as a sub-ticket of another ticket. Excludes
        the current ticket and any ticket the caller cannot access.
      parameters:
        - in: path
          name: ticketId
          description: Id of the current ticket whose company's selectable parent tickets should be returned.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Open company tickets that can act as parent tickets.
              example:
                meta: {}
                content:
                  - id: 4801
                    companyId: 100023
                    title: Drucker-Problem
                    statusId: 1
                    typeId: 1
                    assignedToEmployeeId: 5
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/companyTicketsForProject/{ticketId}:
    get:
      operationId: get_api_v1_tickets_companyTicketsForProject_ticketId
      tags:
        - projects
      summary: Get open tickets from company project
      description: |-
        Returns open project-type tickets at the same company that the current ticket
        can be assigned to as a sub-ticket. Used by the "Ticket einem Projekt zuordnen"
        picker — only project tickets the caller can access are returned.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose company's open project tickets should be returned.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Open project tickets at the same company.
              example:
                meta: {}
                content:
                  - id: 5101
                    companyId: 100023
                    title: Server-Migration 2026
                    statusId: 1
                    typeId: 1
                    project: true
                    assignedToEmployeeId: 5
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/departmentOrder:
    get:
      operationId: get_api_v1_tickets_departmentOrder
      tags:
        - tickets
      summary: Get department order
      description: |-
        Returns the configured department display order used to group tickets in the
        portal views. Each entry contains a department id and its rank — the frontend
        uses this list to sort department headers in ticket lists like `/own`,
        `/general`, etc.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Departments with their configured rank.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Support
                    rank: 1
                  - id: 2
                    name: Vertrieb
                    rank: 2
                  - id: 3
                    name: Backoffice
                    rank: 3
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/flags/{ticketId}:
    get:
      operationId: get_api_v1_tickets_flags_ticketId
      tags:
        - tickets
      summary: Get ticket flags
      description: |-
        Returns the flag icons shown in the ticket header (deadline warnings,
        favourites, repair indicators, etc.). Pass `ticketId=0` to get the icon set for
        a not-yet-persisted ticket. The optional `mode` query argument switches between
        icon variants (e.g. small vs. large). The caller must have access to the
        ticket.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose header flag icons should be returned (use 0 for a not-yet-persisted ticket).
          example: 4711
          required: true
          schema:
            type: integer
        - in: query
          name: mode
          description: Optional icon variant to render (e.g. small vs. large).
          example: small
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Header flag icons for the ticket.
              example:
                meta: {}
                content:
                  - icon: deadline
                    tooltip: Deadline in 2 days
                    color: '#f0ad4e'
                  - icon: favorite
                    tooltip: Marked as favourite
                    color: '#f1c40f'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/lastEntry:
    post:
      operationId: post_api_v1_tickets_lastEntry
      tags:
        - tickets
      summary: Get ticket last entry
      description: |-
        Returns the most recent history entry (latest comment, support, mail, etc.) for
        each ticket id in the request body, keyed by ticket id. Used to show "letzter
        Eintrag" previews in ticket list rows without loading the full history. The
        caller's per-ticket access is verified for every id.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ticketIds
              properties:
                ticketIds:
                  type: array
                  description: List of ticket identifiers to fetch the last entry for
                  items:
                    type: object
            example:
              ticketIds:
                - 4711
                - 4712
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: Map of `ticketId -> last entry`.
              example:
                meta: {}
                content:
                  '4711':
                    type: COMMENT
                    date: 1748256000
                    employeeId: 5
                    preview: Festplatte wurde getauscht
                  '4712':
                    type: MAIL
                    date: 1748259600
                    employeeId: 7
                    preview: 'Re: Outlook startet nicht'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/list/properties:
    put:
      operationId: put_api_v1_tickets_list_properties
      tags:
        - tickets
      summary: Get ticket list properties
      description: |-
        Returns the column / filter metadata for a configurable ticket list — visible
        columns, available filter fields, sort options, etc. — for the given
        configuration request. The frontend calls this when rendering the dynamic
        ticket list header.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: array
                  description: List of configured ticket list column fields
                  items:
                    type: object
                context:
                  type: string
                  description: Context in which the ticket list configuration applies
                  enum:
                    - TICKET_LIST
                    - OWN_TICKETS
                    - CREATED_TICKETS
                    - PROJECTS
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Columns, filters and sort options for the ticket list.
              example:
                meta: {}
                content:
                  columns:
                    - field: id
                      label: Nr.
                      width: 60
                    - field: title
                      label: Titel
                      width: 300
                    - field: assignedToEmployeeId
                      label: Techniker
                      width: 140
                  availableFilters:
                    - field: statusId
                      type: ENUM
                    - field: typeId
                      type: ENUM
                  defaultSort:
                    field: deadlineDate
                    direction: ASC
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/localAdminTickets:
    get:
      operationId: get_api_v1_tickets_localAdminTickets
      tags:
        - tickets
      summary: Get local admin tickets
      description: |-
        Returns tickets created by, or assigned to, "local admin" users at customer
        companies. This list is intended for the customer-portal local admin view, so
        technicians and freelancers are explicitly forbidden — use
        `GET /api/v1/tickets/localAdminOverview` instead from a technician context.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Tickets visible in the customer local-admin view.
              example:
                meta: {}
                content:
                  - id: 4711
                    companyId: 100023
                    title: Festplatte defekt
                    statusId: 1
                    typeId: 1
                    assignedToEmployeeId: 5
                    deadlineDate: 1748256000
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/pinned:
    get:
      operationId: get_api_v1_tickets_pinned
      tags:
        - tickets
      summary: Get ticket pinned by ticket id
      description: |-
        Returns all "pin" records attached to a ticket — references to other entities
        (employees, assignments, devices, etc.) that should be displayed prominently in
        the ticket header. The caller must have access to the ticket.
      parameters:
        - in: query
          name: ticketId
          description: Id of the ticket whose pin records should be returned.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Pin records attached to the ticket.
              example:
                meta: {}
                content:
                  - id: 42
                    ticketId: 4711
                    type: EMPLOYEE
                    linkId: 5
                  - id: 43
                    ticketId: 4711
                    type: ASSIGNMENT
                    linkId: 314
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_tickets_pinned
      tags:
        - tickets
      summary: Create ticket pinned
      description: |-
        Pins an entity (employee, assignment, device, etc.) onto a ticket so it is
        shown in the ticket header. Standard permission checks apply.
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the pinned entry
                ticketId:
                  type: integer
                  description: Identifier of the ticket the entry is pinned to
                type:
                  type: string
                  description: Type of the pinned item
                  enum:
                    - NONE
                    - COMMENT
                    - MAIL
                    - SUPPORT
                    - GIT_COMMIT
                linkId:
                  type: integer
                  description: Identifier of the linked item that is pinned
            example:
              id: 42
              ticketId: 1
              type:
                value: 1
              linkId: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The created pin record.
              example:
                meta: {}
                content:
                  id: 42
                  ticketId: 4711
                  type: EMPLOYEE
                  linkId: 5
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/pinned/{id}:
    delete:
      operationId: delete_api_v1_tickets_pinned_id
      tags:
        - tickets
      summary: Delete ticket pinned
      description: |-
        Removes a single pin record by its primary id (unlike
        `DELETE /api/v1/tickets/{id}/pinned/{type}/{linkId}` which removes by type and
        link). Standard CRUD permissions apply.
      parameters:
        - in: path
          name: id
          description: Primary id of the ticket pin record.
          example: 42
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tickets_pinned_id
      tags:
        - tickets
      summary: Update ticket pinned
      description: |-
        Updates an existing ticket pin (e.g. change the linked entity it points at).
        Standard permission checks apply.
      parameters:
        - in: path
          name: id
          description: Primary id of the ticket pin record.
          example: 42
          required: true
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the pinned entry
                ticketId:
                  type: integer
                  description: Identifier of the ticket the entry is pinned to
                type:
                  type: string
                  description: Type of the pinned item
                  enum:
                    - NONE
                    - COMMENT
                    - MAIL
                    - SUPPORT
                    - GIT_COMMIT
                linkId:
                  type: integer
                  description: Identifier of the linked item that is pinned
            example:
              id: 42
              ticketId: 1
              type:
                value: 1
              linkId: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated pin record.
              example:
                meta: {}
                content:
                  id: 42
                  ticketId: 4711
                  type: EMPLOYEE
                  linkId: 5
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/preferredTechnicians/{linkTypeId}/{linkId}:
    get:
      operationId: get_api_v1_tickets_preferredTechnicians_linkTypeId_linkId
      tags:
        - tickets
      summary: Get prefered technicans
      description: |-
        Returns the technicians flagged as preferred for the given assignment
        `(linkTypeId, linkId)` — these are the technicians the customer or device owner
        wants to receive their tickets, grouped by relationship type. The caller must
        have access to the assignment.
      parameters:
        - in: path
          name: linkTypeId
          description: Type id of the assignment whose preferred technicians should be returned.
          example: 1
          required: true
          schema:
            type: integer
        - in: path
          name: linkId
          description: Id of the linked entity within the given link type.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: Map of group name -> list of preferred technicians.
              example:
                meta: {}
                content:
                  direct:
                    - employeeId: 5
                      name: Max Mustermann
                      preferredReason: Hauptansprechpartner
                  department:
                    - employeeId: 7
                      name: Petra Schmidt
                      departmentId: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/projects/{ticketId}:
    get:
      operationId: get_api_v1_tickets_projects_ticketId
      tags:
        - projects
      summary: Get projects for ticket
      description: |-
        Returns the list of projects (and their phases) the given ticket can be
        assigned to — typically all open projects at the ticket's company. Used to
        populate the "Einem Projekt zuordnen" picker in the ticket UI. The caller must
        have access to the ticket.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose assignable projects are listed / that is being assigned to a project.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Projects with their phases that the ticket can be assigned to.
              example:
                meta: {}
                content:
                  - id: 5101
                    companyId: 100023
                    title: Server-Migration 2026
                    phases:
                      - id: 41
                        name: Planung
                        rank: 1
                      - id: 42
                        name: Migration
                        rank: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tickets_projects_ticketId
      tags:
        - projects
      summary: Assign ticket to project
      description: |-
        Assigns the ticket to a project (and optionally a specific phase), or detaches
        it by passing `projectId=0`. The response includes only the changed identity
        fields (`id`, `projectId`, `phaseId`). The caller must have access to the
        ticket.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose assignable projects are listed / that is being assigned to a project.
          example: 4711
          required: true
          schema:
            type: integer
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              projectId: 5101
              phaseId: 42
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Identity fields of the updated ticket.
              example:
                meta: {}
                content:
                  id: 4711
                  projectId: 5101
                  phaseId: 42
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/status:
    get:
      operationId: get_api_v1_tickets_status
      tags:
        - ticket states
      summary: Get ticket states
      description: |-
        Returns all active ticket states (status values such as "Open", "In progress",
        "Waiting for customer", "Done", …) ordered by their configured rank. Used to
        populate status drop-downs across the ticket UI. Open to any authenticated
        user.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Active ticket states ordered by rank.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Offen
                    rank: 1
                    waitState: false
                    active: true
                  - id: 2
                    name: In Bearbeitung
                    rank: 2
                    waitState: false
                    active: true
                  - id: 3
                    name: Warten auf Kunde
                    rank: 3
                    waitState: true
                    active: true
                  - id: 4
                    name: Erledigt
                    rank: 4
                    waitState: false
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/types:
    get:
      operationId: get_api_v1_tickets_types
      tags:
        - ticket types
      summary: Get ticket types
      description: |-
        Returns only the active ticket types — used to populate the type drop-down
        when creating or editing a ticket. For the full admin list (including
        inactive), use `GET /api/v1/admin/ticketTypes`.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Active ticket types.
              example:
                meta: {}
                content:
                  - id: 1
                    name: Incident
                    useReactionHours: true
                    active: true
                  - id: 2
                    name: Service Request
                    useReactionHours: false
                    active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/types/{typeName}:
    post:
      operationId: post_api_v1_tickets_types_typeName
      tags:
        - ticket types
      summary: Add ticket type
      description: |-
        Convenience endpoint to quickly add a new ticket type from its name only — the
        type is created active with default flags. For full control over the
        properties, use `POST /api/v1/admin/ticketTypes` instead.
      parameters:
        - in: path
          name: typeName
          description: Name of the new ticket type to create.
          example: Beispiel
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The newly created ticket type.
              example:
                meta: {}
                content:
                  id: 4
                  name: Change
                  useReactionHours: false
                  active: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/unwantedTechnicians/{linkTypeId}/{linkId}:
    get:
      operationId: get_api_v1_tickets_unwantedTechnicians_linkTypeId_linkId
      tags:
        - tickets
      summary: Get unwanted technicans
      description: |-
        Returns the technicians explicitly excluded for the given assignment
        `(linkTypeId, linkId)` — the inverse of `/preferredTechnicians`. Used to warn
        when assigning an unwanted technician to a ticket on this asset. The caller
        must have access to the assignment.
      parameters:
        - in: path
          name: linkTypeId
          description: Type id of the assignment whose unwanted technicians should be returned.
          example: 1
          required: true
          schema:
            type: integer
        - in: path
          name: linkId
          description: Id of the linked entity within the given link type.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: Map of group name -> list of unwanted technicians.
              example:
                meta: {}
                content:
                  direct:
                    - employeeId: 8
                      name: Klaus Beispiel
                      unwantedReason: Kundenwunsch
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/waitingStates:
    get:
      operationId: get_api_v1_tickets_waitingStates
      tags:
        - ticket states
      summary: Get waiting states
      description: |-
        Returns the ids of ticket states that are flagged as "waiting" (e.g. "Waiting
        for customer", "Waiting for hardware"). The frontend uses these to colour /
        badge tickets in those states and to drive SLA pause logic.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    description: Ids of ticket states flagged as waiting.
              example:
                meta: {}
                content:
                  - 3
                  - 5
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{id}/contractInfos:
    get:
      operationId: get_api_v1_tickets_id_contractInfos
      tags:
        - tickets
      summary: Get ticket contract infos
      description: |-
        Returns contract information attached to the ticket — applicable SLA, contract
        budget remaining, contract end date, etc. Used by the ticket detail UI to show
        contractual context next to the ticket. The caller must have access to the
        ticket.
      parameters:
        - in: path
          name: id
          description: Id of the ticket whose contract information should be returned.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Contract information block.
              example:
                meta: {}
                content:
                  contractId: 42
                  contractName: Wartungsvertrag Premium
                  endDate: 1767225600
                  budgetRemainingMinutes: 480
                  budgetTotalMinutes: 600
                  slaName: 8h Reaktionszeit
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{id}/favorite:
    put:
      operationId: put_api_v1_tickets_id_favorite
      tags:
        - tickets
      summary: Toggle favorite
      description: |-
        Toggles the "favourite" flag on the ticket for the logged-in user — if the
        ticket was a favourite it is removed, otherwise it is added. The caller must
        have access to the ticket. Favourites are personal to each user.
      parameters:
        - in: path
          name: id
          description: Id of the ticket whose favourite flag should be toggled.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: New favourite state.
              example:
                meta: {}
                content:
                  linkTypeId: 5
                  linkId: 4711
                  isFavorite: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{id}/pdf/mail:
    post:
      operationId: post_api_v1_tickets_id_pdf_mail
      tags:
        - tickets
      summary: Send pdf report via mail
      description: |-
        Generates a support/timesheet PDF report for the given ticket using the supplied
        options (date range, grouping, internal vs. customer view, recipient list, etc.)
        and dispatches it by mail through the legacy PHP handler. Requires basic
        permission on the ticket support PDF aspect plus access to the ticket itself.
      parameters:
        - in: path
          name: id
          description: Id of the ticket the PDF report should be generated for and mailed.
          example: 4711
          required: true
          schema:
            type: integer
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signatureField:
                  type: boolean
                  description: Whether a signature field is included in the generated PDF
                prices:
                  type: boolean
                  description: Whether prices are shown in the generated PDF
                supplementSheet:
                  type: string
                  description: Type of supplement sheet appended to the PDF
                  enum:
                    - DEFAULT
                    - NONE
                    - PAYTYPES
                    - SUPPORTS
                    - SUPPORTS_TICKETS
                    - EMPLOYEES
                    - EMPLOYEES_INT
                    - PAYTYPES_SHORT
                    - SUPPORTS_SHORT
                    - SUPPORTS_TICKETS_SHORT
                    - EMPLOYEES_SHORT
                    - EMPLOYEES_INT_SHORT
                mailReceivers:
                  type: array
                  description: List of mail recipients the generated PDF is sent to
                  items:
                    type: object
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Result of the PHP mail handler (success flag, error if any).
              example:
                meta: {}
                content:
                  success: true
                  messageId: <20260526123000.42@tanss>
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{id}/pinned/{type}/{linkId}:
    delete:
      operationId: delete_api_v1_tickets_id_pinned_type_linkId
      tags:
        - tickets
      summary: Delete ticket pinned by type and link id
      description: |
        Unpins all entries on a ticket that match the given pin type and `linkId`
        (e.g. unpin a specific employee or assignment from the ticket). Returns the
        list of removed pin records.
      parameters:
        - in: path
          name: id
          description: Id of the ticket the pins should be removed from.
          example: 4711
          required: true
          schema:
            type: integer
        - in: path
          name: type
          example: EMPLOYEE
          required: true
          schema:
            type: string
            description: ''
        - in: path
          name: linkId
          description: Id of the linked entity whose matching pins should be removed.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{sourceTicketId}/merge/{destinationTicketId}:
    put:
      operationId: put_api_v1_tickets_sourceTicketId_merge_destinationTicketId
      tags:
        - tickets
      summary: Merge
      description: |-
        Merges the source ticket into the destination ticket — all entities (comments,
        supports, mails, attachments, callbacks, etc.) on the source are moved to the
        destination, and the source is then marked as merged (no longer directly
        accessible). Both ticket ids are permission-checked.
      parameters:
        - in: path
          name: sourceTicketId
          description: Id of the ticket to merge from (will be marked as merged).
          example: 4711
          required: true
          schema:
            type: integer
        - in: path
          name: destinationTicketId
          description: Id of the ticket to merge into (receives the source's entities).
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The destination ticket after the merge.
              example:
                meta: {}
                content:
                  id: 4712
                  companyId: 100023
                  title: Outlook startet nicht
                  statusId: 1
                  typeId: 1
                  assignedToEmployeeId: 7
                  mergedFromTicketIds:
                    - 4711
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/comments/{commentId}:
    delete:
      operationId: delete_api_v1_tickets_ticketId_comments_commentId
      tags:
        - tickets
      summary: Delete comment
      description: |-
        Removes a comment from a ticket. The service-layer `deleteComment` enforces
        that the caller is allowed to delete the specific comment (typically the
        author or an admin) and triggers history bookkeeping.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket the comment belongs to.
          example: 4711
          required: true
          schema:
            type: integer
        - in: path
          name: commentId
          description: Id of the comment to delete.
          example: 88
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_tickets_ticketId_comments_commentId
      tags:
        - tickets
      summary: Update comment
      description: |-
        Edits an existing comment on a ticket. The optional `pinned` flag re-pins or
        un-pins the comment to the ticket. Permission is enforced: only the comment's author or an admin may edit it.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket the comment belongs to.
          example: 4711
          required: true
          schema:
            type: integer
        - in: path
          name: commentId
          description: Id of the comment to update.
          example: 88
          required: true
          schema:
            type: integer
        - in: query
          name: pinned
          description: When true, (re-)pin the comment to the ticket; when false, unpin it.
          example: true
          required: false
          schema:
            type: boolean
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              content: Festplatte wurde am 26.05. getauscht, läuft jetzt.
              internal: false
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The updated comment.
              example:
                meta: {}
                content:
                  id: 9001
                  ticketId: 4711
                  employeeId: 5
                  date: 1748259600
                  content: Festplatte wurde am 26.05. getauscht, läuft jetzt.
                  internal: false
                  pinned: false
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/mailAttachments:
    get:
      operationId: get_api_v1_tickets_ticketId_mailAttachments
      tags:
        - tickets
      summary: Get mail attachments for ticket
      description: |-
        Returns the attachments collected from all mails associated with a ticket,
        grouped by attachment source (documents, images, mail attachments). Used to
        show a consolidated attachment panel on the ticket. The caller must have
        access to the ticket.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose mail attachments should be returned.
          example: 4711
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: Map of attachment group -> list of attachments.
              example:
                meta: {}
                content:
                  documents:
                    - id: 301
                      name: Angebot.pdf
                      size: 153422
                  images:
                    - id: 412
                      name: Screenshot-Fehler.png
                      size: 88123
                  mailAttachments:
                    - id: 555
                      name: Logfile.zip
                      mailId: 9002
                      size: 1024500
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/mails:
    post:
      operationId: post_api_v1_tickets_ticketId_mails
      tags:
        - tickets
      summary: Send mail
      description: |-
        Composes and sends an outbound mail from the ticket (to customer, to assignee,
        to free-text recipients) and stores it in the ticket history. With
        `pinned=true` the resulting mail entry is pinned to the ticket. Throws 500 on
        SMTP failure.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket the mail is sent from.
          example: 4711
          required: true
          schema:
            type: integer
        - in: query
          name: pinned
          description: When true, pin the resulting mail entry to the ticket.
          example: true
          required: false
          schema:
            type: boolean
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  type: string
                  description: Primary recipient email address
                cc:
                  type: string
                  description: Carbon copy recipient email addresses
                bcc:
                  type: string
                  description: Blind carbon copy recipient email addresses
                title:
                  type: string
                  description: Subject of the email
                text:
                  type: string
                  description: Body text of the email
                internal:
                  type: boolean
                  description: Whether the mail is treated as an internal message
                html:
                  type: boolean
                  description: Whether the mail body is HTML formatted
                type:
                  type: string
                  description: Type of the mail action
                  enum:
                    - NORMAL
                    - REPLY
                    - SEND_AGAIN
                    - FORWARD
                    - SEMI_AUTOMATE
                statusId:
                  type: integer
                  description: Ticket status to set when sending the mail
                costCenterId:
                  type: integer
                  description: Identifier of the cost center for the mail
                startTime:
                  type: integer
                  format: int64
                  description: Start time as a Unix timestamp in seconds
                sendAgain:
                  type: boolean
                  description: Whether the mail is being sent again
            example:
              to:
                - kunde@beispiel.de
              cc: []
              bcc: []
              internal: false
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Empty — confirmation is in `meta.text`.
              example:
                meta: {}
                content: null
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/mails/{mailId}:
    get:
      operationId: get_api_v1_tickets_ticketId_mails_mailId
      tags:
        - tickets
      summary: Get mail for ticket
      description: |-
        Returns the metadata and rendered content of a single mail attached to the
        ticket (HTML/plain body, headers, attachments, etc.). The caller must have
        access to the ticket.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket the mail belongs to.
          example: 4711
          required: true
          schema:
            type: integer
        - in: path
          name: mailId
          description: Id of the mail to return.
          example: 1024
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The mail record.
              example:
                meta: {}
                content:
                  id: 9002
                  ticketId: 4711
                  from: kunde@beispiel.de
                  to:
                    - support@huckit.de
                  subject: 'Re: Festplatte defekt'
                  date: 1748259600
                  bodyText: Vielen Dank, der Tausch hat geholfen.
                  attachments:
                    - id: 555
                      name: Logfile.zip
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/mails/{mailId}/attachment:
    put:
      operationId: put_api_v1_tickets_ticketId_mails_mailId_attachment
      tags:
        - tickets
      summary: Get mail attachment
      description: |-
        Downloads a single attachment from a mail attached to a ticket. The body
        describes which attachment to fetch (filename / content-id). The caller must
        have access to both the ticket and the mail.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket the mail belongs to.
          example: 4711
          required: true
          schema:
            type: integer
        - in: path
          name: mailId
          description: Id of the mail whose attachment should be downloaded.
          example: 1024
          required: true
          schema:
            type: integer
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - mailId
                - fileName
              properties:
                mailId:
                  type: integer
                  description: Identifier of the mail this attachment belongs to.
                fileName:
                  type: string
                  description: Original file name of the attachment.
                storedFilename:
                  type: string
                  description: Name under which the attachment is stored internally.
                extension:
                  type: string
                  description: File extension of the attachment.
                cid:
                  type: string
                  description: Content identifier used to reference the attachment inline in the mail body.
                folder:
                  type: string
                  description: Storage folder where the attachment file resides.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Attachment content metadata (raw bytes via separate transport).
              example:
                meta: {}
                content:
                  name: Logfile.zip
                  mimeType: application/zip
                  size: 1024500
                  downloadUrl: /api/v1/files/download/abc123
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/pdf:
    get:
      operationId: get_api_v1_tickets_ticketId_pdf
      tags:
        - tickets
      summary: Get ticket detail pdf
      description: |
        Generates and streams a PDF rendering of the ticket detail page. With
        `internal=true` the PDF includes internal-only fields and comments (technician
        view); with `internal=false` the customer view is produced. The response
        `Content-Type` is determined by the `Accept` header (binary PDF or JSON
        wrapper). The caller must have access to the ticket.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket to render as a detail PDF.
          example: 4711
          required: true
          schema:
            type: integer
        - in: query
          name: internal
          description: When true, include internal-only fields and comments (technician view); when false, produce the customer view.
          example: false
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: string
                    format: binary
                    description: 'PDF bytes (when `Accept: application/pdf`) or a JSON wrapper carrying the file content.'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/properties:
    get:
      operationId: get_api_v1_tickets_ticketId_properties
      tags:
        - tickets
      summary: Get ticket properties
      description: |-
        Returns the form descriptor for displaying / editing a ticket: ticket data,
        field-level permissions, validation rules, and a fresh content hash. This is
        the initial-load endpoint for the ticket form; subsequent re-renders triggered
        by field changes go through `POST .../properties`. Returns 404 (or a merged
        redirect) if the ticket no longer exists. The caller must have access to the
        ticket.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose form descriptor should be returned.
          example: 4711
          required: true
          schema:
            type: integer
        - in: query
          name: viewChecks
          description: When true, also evaluate view-level visibility checks for the fields.
          example: false
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Ticket form descriptor (ticket + properties + permissions + hash).
              example:
                meta: {}
                content:
                  ticket:
                    id: 4711
                    companyId: 100023
                    title: Festplatte defekt
                    statusId: 1
                    typeId: 1
                    assignedToEmployeeId: 5
                    hash: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                  properties:
                    fields:
                      title:
                        editable: true
                        required: true
                      content:
                        editable: true
                        required: false
                    editable: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_tickets_ticketId_properties
      tags:
        - tickets
      summary: Get changed ticket properties
      description: |-
        Re-renders the ticket form when a field value changes (or when displaying a
        not-yet-persisted ticket with `ticketId=0`). The body carries the current
        in-flight ticket; `property` tells the server which field triggered the
        refresh so it can compute dependent fields, defaults, and validation messages.
        With `ticketId=0`, access is checked against the *merged* ticket data.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket being edited (use 0 for a not-yet-persisted ticket).
          example: 4711
          required: true
          schema:
            type: integer
        - in: query
          name: property
          description: Name of the field that triggered the re-render, so dependent fields can be recomputed.
          example: statusId
          required: false
          schema:
            type: string
            default: ''
        - in: query
          name: viewChecks
          description: When true, also evaluate view-level visibility checks for the fields.
          example: false
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              properties:
                id:
                  type: integer
                  description: Unique identifier of the ticket
                companyId:
                  type: integer
                  description: Identifier of the company the ticket belongs to
                title:
                  type: string
                  description: Ticket subject line
                content:
                  type: string
                  description: Main description text of the ticket
                statusId:
                  type: integer
                  description: Identifier of the current ticket status
                typeId:
                  type: integer
                  description: Identifier of the ticket type
                priority:
                  type: integer
                  description: Priority level of the ticket
                assignedToEmployeeId:
                  type: integer
                  description: Identifier of the employee the ticket is assigned to
                assignedToDepartmentId:
                  type: integer
                  description: Identifier of the department the ticket is assigned to
                dueDate:
                  type: integer
                  format: int64
                  description: Due date as a Unix timestamp in seconds
                deadlineDate:
                  type: integer
                  format: int64
                  description: Deadline as a Unix timestamp in seconds
                contractId:
                  type: integer
                  description: Identifier of the linked maintenance contract
            example:
              id: 42
              companyId: 1
              title: Example title
              content: Example content
              assignedToEmployeeId: 1
              assignedToDepartmentId: 1
              statusId: 1
              deadlineDate: 1748256000
              typeId: 1
              priority: 2
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Re-rendered ticket form descriptor.
              example:
                meta: {}
                content:
                  ticket:
                    id: 4711
                    companyId: 100023
                    title: Festplatte defekt
                    statusId: 2
                    typeId: 1
                    assignedToEmployeeId: 5
                  properties:
                    fields:
                      statusId:
                        editable: true
                        options:
                          - id: 1
                            name: Offen
                          - id: 2
                            name: In Bearbeitung
                    editable: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/serviceCap/request/{employeeId}/{newAmount}:
    get:
      operationId: get_api_v1_tickets_ticketId_serviceCap_request_employeeId_newAmount
      tags:
        - tickets
      summary: Request new service cap
      description: |-
        Sends a mail to the given employee requesting approval to raise the service
        cap (budget ceiling) on the ticket to `newAmount`. The mail contains an
        approval link; the resulting request record is also persisted. The caller must
        have access to the ticket.
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose service cap should be raised.
          example: 4711
          required: true
          schema:
            type: integer
        - in: path
          name: employeeId
          description: Id of the employee asked to approve the new service cap.
          example: 5
          required: true
          schema:
            type: integer
        - in: path
          name: newAmount
          description: Requested new service cap (budget ceiling) amount.
          example: 12.5
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Service-cap request record.
              example:
                meta: {}
                content:
                  id: 17
                  ticketId: 4711
                  employeeId: 5
                  newAmount: 12.5
                  status: PENDING
                  mailSent: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tickets/{ticketId}/statistics:
    get:
      operationId: get_api_v1_tickets_ticketId_statistics
      tags:
        - tickets
      summary: Get statistics
      description: |-
        Returns statistical aggregates for a single ticket — total/billable/unbillable
        times, support counts, optionally grouped per employee/day/week via
        `groupingType`. The caller must have access to the ticket and pass the statistics permission gate (which
        can be restricted for customer-portal users).
      parameters:
        - in: path
          name: ticketId
          description: Id of the ticket whose statistics should be returned.
          example: 4711
          required: true
          schema:
            type: integer
        - in: query
          name: groupingType
          example: EMPLOYEE
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Aggregated time and support statistics.
              example:
                meta: {}
                content:
                  ticketId: 4711
                  totalMinutes: 240
                  billableMinutes: 180
                  unbillableMinutes: 60
                  supportCount: 4
                  byEmployee:
                    - employeeId: 5
                      minutes: 180
                    - employeeId: 7
                      minutes: 60
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timeline:
    put:
      operationId: put_api_v1_timeline
      tags:
        - planning
      summary: Get timeline
      description: |
        Returns the technician timeline used by the capacity-planning view: per-employee, per-day buckets showing absences, scheduled supports and free capacity in minutes for the requested timeframe. Only technicians or freelancers may call it; other roles receive `403`.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entity:
                  type: string
                  description: The entity type whose timeline is requested.
                  enum:
                    - EMPLOYEE
                    - CAR
                ids:
                  type: array
                  description: Identifiers of the entities to include in the timeline.
                  items:
                    type: object
                timeframe:
                  type: object
                  description: Time range (from/to) to load timeline data for.
                fetchTypes:
                  type: array
                  description: The kinds of timeline entries to fetch (supports, tickets, phone calls, and similar).
                  items:
                    type: object
                planningTypes:
                  type: array
                  description: Planning types to include in the timeline.
                  items:
                    type: object
                customTypeIds:
                  type: array
                  description: Identifiers of custom entry types to include.
                  items:
                    type: object
                showInternalCalls:
                  type: boolean
                  description: Whether internal phone calls should be shown.
                showRealDuration:
                  type: boolean
                  description: Whether the real duration of support entries should be shown.
                showFrontendValues:
                  type: boolean
                  description: Whether frontend-oriented values should be used in the response.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Container with per-employee timeline buckets (capacity vs. scheduled minutes).
              example:
                meta: {}
                content:
                  infos:
                    - employeeId: 5
                      week: 2025-W22
                      capacityMinutes: 2400
                      scheduledMinutes: 1800
                      days:
                        - date: 1748256000
                          capacityMinutes: 480
                          scheduledMinutes: 360
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timeline/outlookSync:
    get:
      operationId: get_api_v1_timeline_outlookSync
      tags:
        - planning
      summary: Trigger Outlook sync for timeline
      description: |
        Synchronises the calling technician's supports/appointments with their Outlook calendar. If both `from` and `to` (unix timestamps in seconds) are supplied, only that window is synced; otherwise the service defaults to a single timeframe of one (week, starting from today). Returns the sync result object; a null result is reported as an error.
      parameters:
        - in: query
          name: from
          required: false
          description: Start of the sync window as a unix timestamp in seconds.
          example: 1748256000
          schema:
            type: integer
        - in: query
          name: to
          required: false
          description: End of the sync window as a unix timestamp in seconds.
          example: 1748256000
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Outlook sync result with counts of created, updated and removed calendar entries.
              example:
                meta: {}
                content:
                  employeeId: 5
                  created: 3
                  updated: 7
                  deleted: 1
                  from: 1748256000
                  to: 1748860800
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timers/allTechnicians:
    get:
      operationId: get_api_v1_timers_allTechnicians
      tags:
        - timers
      summary: Get all technician timers
      description: |
        Returns the currently running stopwatch timers of every technician in the system, so a supervisor or dispatcher can see who is currently tracking time on which task. Requires the caller to be a technician/freelancer and to hold the `VIEW_TIMERS_OF_ALL_TECHNICIANS` permission; otherwise a `403` is returned. Unlike supports (which are written after the work is finished), timers are short-running and represent live tracking.
      responses:
        '200':
          description: List of running/paused timers across all technicians.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Timer'
              example:
                meta: {}
                content:
                  - id: 42
                    employeeId: 5
                    title: Server-Migration Kunde XY
                    duration: 1800
                  - id: 43
                    employeeId: 7
                    title: Telefonsupport ACME GmbH
                    duration: 600
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/changeRequests:
    get:
      operationId: get_api_v1_timestamps_changeRequests
      tags:
        - timestamp
      summary: List open change requests
      description: |-
        Returns all open timestamp change requests that the caller is permitted to see, grouped per employee and day,
        with their statistics and day-closing values attached (the running balance is intentionally omitted because the
        requests are not yet applied). Use this as the inbox for supervisors who approve or reject pending timestamp
        corrections.
      responses:
        '200':
          description: List of timestamp infos representing open change requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampInfo-With-Changes-Requested'
              example:
                meta: {}
                content:
                  - employeeId: 5
                    date: '2025-05-26'
                    changesRequested:
                      - id: 87
                        employeeId: 5
                        date: 1748256000
                        state: 'ON'
                        type: WORK
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/changeRequests/{employeeId}/{dayTimestamp}:
    delete:
      operationId: delete_api_v1_timestamps_changeRequests_employeeId_dayTimestamp
      tags:
        - timestamp
      summary: Delete change requests
      description: |
        Rejects/clears all open change requests for the given employee on the given day. A change request is what an
        employee submits when they cannot edit their own timestamps directly and instead ask a supervisor to apply the
        corrections. Calling this endpoint discards those pending requests so the day is no longer flagged for review.
      parameters:
        - in: path
          name: employeeId
          required: true
          description: Id of the employee whose change requests are cleared
          example: 5
          schema:
            type: integer
        - in: path
          name: dayTimestamp
          required: true
          description: Unix timestamp identifying the day whose change requests are cleared
          example: 1748256000
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/employees:
    get:
      operationId: get_api_v1_timestamps_employees
      tags:
        - timestamp
      summary: List employees visible for timestamp statistics
      description: |
        Returns the set of employees whose timestamps the caller is allowed to look at — i.e. the caller themself plus
        any colleagues covered by `VIEW_FOREIGN_TIMESTAMPS` (all employees, or only the own department, depending on the
        permission level). Used to populate employee pickers in the Stempeluhr statistics views. The response is filtered
        down to a small employee shape (id, name, initials).
      responses:
        '200':
          description: List of employees visible to the caller.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 5
                    name: Erika Mustermann
                    initials: EM
                  - id: 7
                    name: Max Beispiel
                    initials: MB
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/initialBalances:
    get:
      operationId: get_api_v1_timestamps_initialBalances
      tags:
        - timestamp
      summary: List initial balances of all employees
      description: |-
        Returns the seed time-balance entry (a synthetic day-closing) for every employee. This is the value used when
        a customer migrates from another time-tracking system and wants to carry an existing plus/minus balance into
        TANSS. Requires the dedicated initial-balance configuration permission in addition to general timestamp access.
      responses:
        '200':
          description: List of initial balance day-closings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampDayClosing'
              example:
                meta: {}
                content:
                  - employeeId: 5
                    balance: -60
                  - employeeId: 7
                    balance: 120
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/manualBooking:
    post:
      operationId: post_api_v1_timestamps_manualBooking
      tags:
        - timestamp
      summary: Create manual booking
      description: |-
        Creates a manual balance correction for an employee — a positive or negative minute value applied to a specific
        day together with a reason. Used by supervisors to compensate overtime, pay out balance or fix edge cases that
        cannot be captured via real punches. The booking shows up alongside regular timestamps in the day statistics.
      requestBody:
        description: Manual booking to create (the request payload).
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
            example:
              employeeId: 5
              date: 1748256000
              balanceCorrection: 60
              reason: Überstundenausgleich
      responses:
        '201':
          description: Manual booking created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: The persisted manual booking.
              example:
                meta: {}
                content:
                  id: 12
                  employeeId: 5
                  date: 1748256000
                  balanceCorrection: 60
                  reason: Überstundenausgleich
                  creationDate: 1748256000
                  createdByEmployeeId: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_timestamps_manualBooking
      tags:
        - timestamp
      summary: List manual bookings
      description: |
        Returns a filtered, paginated list of manual balance corrections. Uses PUT (not GET) because the filter shape
        is rich enough to require a JSON body — the request carries pagination, sort and field filters in a
        configuration. Requires admin-level timestamp permissions because manual bookings
        affect other employees' balances.
      requestBody:
        description: Filter / pagination configuration for the manual bookings list.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                employeeId:
                  type: integer
                  description: Identifier of the employee for whom the manual timestamp booking is created.
                timeframe:
                  type: object
                  description: Time range (from/to) of the manual booking.
                frontendValues:
                  type: boolean
                  description: Whether frontend-oriented values should be used for the booking.
      responses:
        '200':
          description: Matching manual bookings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - id: 12
                    employeeId: 5
                    date: 1748256000
                    balanceCorrection: 60
                    reason: Überstundenausgleich
                    creationDate: 1748256000
                    createdByEmployeeId: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/manualBooking/{id}:
    delete:
      operationId: delete_api_v1_timestamps_manualBooking_id
      tags:
        - timestamp
      summary: Delete manual booking
      description: |
        Removes a manual balance correction (a Stempeluhr "manuelle Buchung") by id. These bookings are typically used by
        supervisors to add or subtract minutes from an employee's time balance for reasons that are not covered by a real
        punch — e.g. overtime payout, balance adjustments. Deletion immediately reverts the correction from the balance.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the manual booking to delete
          example: 42
          schema:
            type: integer
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/timestamps/statistics/export:
    get:
      operationId: get_api_v1_timestamps_statistics_export
      tags:
        - timestamp
      summary: Export timestamp statistics as CSV
      description: |
        Returns the same per-day timestamp/statistics aggregation as `GET /statistics`, but rendered as a CSV file ready
        to be downloaded — typically used to hand work-time reports to payroll. The `Accept: text/csv` header controls
        whether the file is streamed directly (`text/csv`) or wrapped in the standard meta/content envelope. Period and
        employee list use the same query parameters as the regular statistics endpoint.
      parameters:
        - in: query
          name: from
          required: false
          description: timestamp of start of period; if omitted the beginning of the current day is used
          example: 1748256000
          schema:
            type: integer
            default: 0
        - in: query
          name: till
          required: false
          description: timestamp of end of period; if omitted the end of the current day is used
          example: 1748256000
          schema:
            type: integer
            default: 0
        - in: query
          name: employeeIds
          required: false
          description: comma-separated ids of the employees whose statistics are exported
          example: 1099,2034
          schema:
            type: string
            default: ''
      responses:
        '200':
          description: CSV export (or the JSON envelope when the client does not request `text/csv`).
          content:
            text/csv:
              schema:
                type: string
              example: |
                employeeId;day;workSeconds;balance
                5;2025-05-26;28800;0
                5;2025-05-27;27000;-1800
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
              example:
                meta: {}
                content:
                  - employeeId: 5
                    day: '2025-05-26'
                    workSeconds: 28800
                    balance: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/tmpFileUploads/{id}:
    get:
      operationId: get_api_v1_tmpFileUploads_id
      tags:
        - search
      summary: Get tmp file upload by id
      description: |
        Returns a one-shot download link for a temporary file that the caller previously uploaded. The link
        embeds a signed `TMP_FILE_UPLOAD` token.

        Access is restricted to the original uploader — the row's `userId` must equal the calling user; other users
        get `403`. Despite the operation id, this endpoint lives under `/tmpFileUploads/{id}`.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the temporary file upload to fetch a download link for.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Signed file link payload.
              example:
                meta: {}
                content:
                  url: /api/v1/files/tmpFileUpload/42?token=abc123
                  fileName: beispiel.pdf
                  mimeType: application/pdf
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/assignment:
    get:
      operationId: get_api_v1_util_assignment
      tags:
        - administration
      summary: Get assignment name
      description: |
        Resolves the human-readable name of an assignment (e.g. company, ticket, contract) identified by `linkTypeId` plus `linkId`. Access to the referenced entity is checked before the name is returned; a missing assignment yields a 404.
      parameters:
        - in: query
          name: linkTypeId
          required: true
          description: Link type of the assignment to resolve (e.g. company, ticket, contract).
          schema:
            type: integer
          example: 1
        - in: query
          name: linkId
          required: true
          description: Id of the linked entity whose name should be resolved.
          schema:
            type: integer
          example: 4711
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: string
                    example: Mustermann GmbH
              example:
                meta: {}
                content: Mustermann GmbH
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/files/{tag}:
    get:
      operationId: get_api_v1_util_files_tag
      tags:
        - administration
      summary: Get file via tag
      description: |
        Streams a previously prepared file (ticket document, screenshot, temporary upload, mail attachment, or files-and-links media) identified by a one-time `tag`. The file pass is validated against its `validTill` and deleted automatically once expired; the response body is the binary file, not a JSON envelope.
      parameters:
        - in: path
          name: tag
          required: true
          description: One-time file pass tag identifying the prepared file to stream.
          schema:
            type: string
          example: a1b2c3d4e5f6
      responses:
        '200':
          description: Binary file stream with `Content-Disposition` set to the original filename.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              example: <binary file content>
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/graph/invalidateAccessTokenCache:
    get:
      operationId: get_api_v1_util_graph_invalidateAccessTokenCache
      tags:
        - search & maintenance
      summary: Invalidate Microsoft Graph access token cache
      description: |
        Forces TANSS to discard every cached Microsoft Graph access token, so subsequent mail or calendar calls re-authenticate. The response carries a short status string reporting how many tokens were removed; intended for admins debugging Graph connectivity.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: string
                    example: 3 token(s) removed
              example:
                meta: {}
                content: 3 token(s) removed
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/languages:
    post:
      operationId: post_api_v1_util_languages
      tags:
        - administration
      summary: Resolve language strings
      description: |
        Resolves a batch of language keys: the body lists translation areas as top-level keys, each mapping to an object of key names whose values are placeholders. The response mirrors the structure but replaces every value with the localised string for the caller's currently active language.
      requestBody:
        description: 'Map of `<area>: { <key>: <ignored>, ... }` describing which language strings to resolve.'
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              all:
                services: ''
                month: ''
                months: ''
              holiday:
                NEW_YEAR: ''
                GOOD_FRIDAY: ''
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    example:
                      all:
                        services: Leistungen
                        month: Monat
                        months: Monate
                      holiday:
                        NEW_YEAR: Neujahr
                        GOOD_FRIDAY: Karfreitag
              example:
                meta: {}
                content:
                  all:
                    services: Leistungen
                    month: Monat
                    months: Monate
                  holiday:
                    NEW_YEAR: Neujahr
                    GOOD_FRIDAY: Karfreitag
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_util_languages
      tags:
        - administration
      summary: Set user language
      description: |
        Persists the requested UI language code for the authenticated user. Subsequent language string lookups for the same user use this value. The response carries a simple boolean success flag.
      parameters:
        - in: query
          name: language
          required: false
          description: UI language code to persist for the authenticated user.
          schema:
            type: string
            default: ''
          example: de
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: boolean
                    example: true
              example:
                meta: {}
                content: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/mailpicker/{companyId}:
    get:
      operationId: get_api_v1_util_mailpicker_companyId
      tags:
        - administration - export & ui-helpers
      summary: Get mail picker addresses without ticket
      description: |
        Variant of the mail picker lookup that operates only on a company id (no ticket context). Returns employees and companies with their mail addresses, filtered down to `mails`, `name`, and `centralType` so the recipient picker stays compact.
      parameters:
        - in: path
          name: companyId
          required: true
          description: Id of the company whose mail addresses should be collected.
          schema:
            type: integer
          example: 1000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      employees:
                        type: array
                        items:
                          type: object
                      companies:
                        type: array
                        items:
                          type: object
              example:
                meta: {}
                content:
                  employees:
                    - id: 42
                      name: Max Mustermann
                      mails:
                        - max@example.com
                  companies:
                    - id: 1000
                      name: Mustermann GmbH
                      centralType: MAIN
                      mails:
                        - info@example.com
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/mailpicker/{companyId}/{ticketId}:
    get:
      operationId: get_api_v1_util_mailpicker_companyId_ticketId
      tags:
        - administration - export & ui-helpers
      summary: Get mail picker addresses (with ticket)
      description: |
        Collects every mail address reachable from the given company plus the people that previously corresponded on the ticket; used to populate the recipient picker in the ticket mail dialog. Employees come back filtered to `mails` and `name`, companies additionally with `centralType`; the response meta is enriched with the matching mail client setup.
      parameters:
        - in: path
          name: companyId
          required: true
          description: Id of the company whose mail addresses should be collected.
          schema:
            type: integer
          example: 1000
        - in: path
          name: ticketId
          required: true
          description: Id of the ticket whose previous correspondents should be included.
          schema:
            type: integer
          example: 4711
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      employees:
                        type: array
                        items:
                          type: object
                      companies:
                        type: array
                        items:
                          type: object
              example:
                meta: {}
                content:
                  employees:
                    - id: 42
                      name: Max Mustermann
                      mails:
                        - max@example.com
                  companies:
                    - id: 1000
                      name: Mustermann GmbH
                      centralType: MAIN
                      mails:
                        - info@example.com
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/pref:
    post:
      operationId: post_api_v1_util_pref
      tags:
        - preferences
      summary: Set integer preference
      description: |
        Persists a single integer preference value, identified by the triple `sectionId / assignmentId / preferenceId`. An access check based on the section is performed before the row is stored; existing entries with the same key are updated.
      requestBody:
        description: An object identifying the preference key and the integer value.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sectionId
                - assignmentId
                - preferenceId
              properties:
                sectionId:
                  type: integer
                  description: Identifier of the preference section this setting belongs to.
                assignmentId:
                  type: integer
                  description: Identifier of the assignment scope (e.g. user or group) the setting applies to.
                preferenceId:
                  type: integer
                  description: Identifier of the individual preference key.
                value:
                  type: integer
                  description: Numeric value stored for this preference.
            example:
              sectionId: 1
              assignmentId: 42
              preferenceId: 100
              value: 1
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      sectionId:
                        type: integer
                        example: 1
                      assignmentId:
                        type: integer
                        example: 42
                      preferenceId:
                        type: integer
                        example: 100
                      value:
                        type: integer
                        example: 1
              example:
                meta: {}
                content:
                  sectionId: 1
                  assignmentId: 42
                  preferenceId: 100
                  value: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_util_pref
      tags:
        - preferences
      summary: Read integer preferences (batch)
      description: |
        Resolves a batch of integer preferences. The body is a nested map `<sectionId>: { <assignmentId>: { <preferenceId>: <ignored> } }`; the response mirrors that shape with the stored values, returning `null` for entries the caller cannot read.
      requestBody:
        description: Nested map describing which preference keys to read.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              '1':
                '42':
                  '100': 0
                  '101': 0
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  '1':
                    '42':
                      '100': 1
                      '101': 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/reimportSolr:
    get:
      operationId: get_api_v1_util_reimportSolr
      tags:
        - search & maintenance
      summary: Reimport Solr search index
      description: |
        Triggers a full reimport of every search collection into Solr by calling the loader service's `init`. This is a slow operation; the controller answers with 201 once the import has been scheduled. Requires a technician/freelancer with both `MANAGE_PERMISSIONS` and `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/resetSolr:
    delete:
      operationId: delete_api_v1_util_resetSolr
      tags:
        - search & maintenance
      summary: Reset Solr search index
      description: |
        Drops every TANSS-managed collection from Solr so the index can be rebuilt with `reimportSolr`. Requires a technician/freelancer with both `MANAGE_PERMISSIONS` and `ONLINE_SYSTEM_CONFIGURATION`; intended for recovering from a corrupted index.
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/spref:
    post:
      operationId: post_api_v1_util_spref
      tags:
        - preferences
      summary: Set string preference
      description: |
        Persists a single string preference value, identified by the triple `sectionId / assignmentId / preferenceId`. An access check based on the section is performed before the row is stored; existing entries with the same key are updated.
      requestBody:
        description: An object identifying the preference key and the string value.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sectionId
                - assignmentId
                - preferenceId
              properties:
                sectionId:
                  type: integer
                  description: Identifier of the preference section this setting belongs to.
                assignmentId:
                  type: integer
                  description: Identifier of the assignment scope (e.g. user or group) the setting applies to.
                preferenceId:
                  type: integer
                  description: Identifier of the individual preference key.
                value:
                  type: string
                  description: Text value stored for this preference.
            example:
              sectionId: 1
              assignmentId: 42
              preferenceId: 200
              value: dark
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      sectionId:
                        type: integer
                        example: 1
                      assignmentId:
                        type: integer
                        example: 42
                      preferenceId:
                        type: integer
                        example: 200
                      value:
                        type: string
                        example: dark
              example:
                meta: {}
                content:
                  sectionId: 1
                  assignmentId: 42
                  preferenceId: 200
                  value: dark
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_util_spref
      tags:
        - preferences
      summary: Read string preferences (batch)
      description: |
        Resolves a batch of string preferences. The body is a nested map `<sectionId>: { <assignmentId>: { <preferenceId>: <ignored> } }`; the response mirrors that shape with the stored values, returning `null` for entries the caller cannot read.
      requestBody:
        description: Nested map describing which string preference keys to read.
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              '1':
                '42':
                  '200': ''
                  '201': ''
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content:
                  '1':
                    '42':
                      '200': dark
                      '201': de
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/testSolr:
    get:
      operationId: get_api_v1_util_testSolr
      tags:
        - search & maintenance
      summary: Test Solr availability
      description: |
        Pings the configured Solr instance to verify it is reachable and answering. Used by the admin UI to surface a green/red status. Requires a technician/freelancer with both `MANAGE_PERMISSIONS` and `ONLINE_SYSTEM_CONFIGURATION`.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: boolean
                    example: true
              example:
                meta: {}
                content: true
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/textmodule/{id}:
    delete:
      operationId: delete_api_v1_util_textmodule_id
      tags:
        - text templates
      summary: Delete text module
      description: |
        Removes the text module (e.g. mail or ticket signature snippet) with the given `id`. The service runs `checkDelete` first, which gates on ownership and the relevant per-text-module-type permission.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the text module to delete.
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/textmodules/{type}:
    get:
      operationId: get_api_v1_util_textmodules_type
      tags:
        - text templates
      summary: Get text modules by type
      description: |
        Returns every text module the caller may see for the given module type (mail, ticket, etc.). The service applies its `checkAccess` filter on entry; the response meta is enriched with list/single properties used by the admin UI.
      parameters:
        - in: path
          name: type
          required: true
          description: Text module type to list (e.g. mail or ticket signatures).
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Standardsignatur
                        text:
                          type: string
                          example: Mit freundlichen Grüßen
                        type:
                          type: integer
                          example: 1
              example:
                meta: {}
                content:
                  - id: 1
                    name: Standardsignatur
                    text: Mit freundlichen Grüßen
                    type: 1
                  - id: 2
                    name: Abwesenheit
                    text: Ich bin bis zum 01.06. nicht erreichbar.
                    type: 1
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/textvariables/{type}:
    get:
      operationId: get_api_v1_util_textvariables_type
      tags:
        - text templates
      summary: Get text variables by type
      description: |
        Returns every text variable (placeholder token) defined for the given text module type — e.g. `{ticketNumber}`, `{customer.name}`. The text module type is resolved from the path int; an unknown id returns 400. Service-level access check applies before the variables are loaded.
      parameters:
        - in: path
          name: type
          required: true
          description: Text module type whose available text variables should be returned.
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: '{ticketNumber}'
                        description:
                          type: string
                          example: Ticket-Nummer
              example:
                meta: {}
                content:
                  - name: '{ticketNumber}'
                    description: Ticket-Nummer
                  - name: '{customer.name}'
                    description: Name des Kunden
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/util/ws:
    get:
      operationId: get_api_v1_util_ws
      tags:
        - search & maintenance
      summary: Get web socket session ids
      description: |
        Returns the WebSocket session ids of the currently authenticated user. When `all=true` and the caller holds `ONLINE_SYSTEM_CONFIGURATION`, the response contains every connected session in the system — useful for admins debugging push delivery.
      parameters:
        - in: query
          name: all
          required: false
          description: When true, return every connected session (requires ONLINE_SYSTEM_CONFIGURATION) instead of only the caller's.
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: string
                    example:
                      - session-7c1f9b2a
                      - session-8d3e0c1b
              example:
                meta: {}
                content:
                  - session-7c1f9b2a
                  - session-8d3e0c1b
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_util_ws
      tags:
        - search & maintenance
      summary: Broadcast push test
      description: |
        Broadcasts a `TEST` message over the WebSocket handler. Used by admins to verify that push delivery to the caller is working; the response contains how many sessions received the test.
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      recipients:
                        type: integer
                        example: 2
                      delivered:
                        type: integer
                        example: 2
              example:
                meta: {}
                content:
                  recipients: 2
                  delivered: 2
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests/list/export/{type}:
    post:
      operationId: post_api_v1_vacationRequests_list_export_type
      tags:
        - vacationRequests
      summary: Get vacation requests export
      description: Exports the matching vacation requests in the requested format.
      parameters:
        - in: path
          name: type
          required: true
          description: Export format/type of the vacation request list
          example: PDF
          schema:
            type: string
            description: ''
        - in: query
          name: sortBy
          required: false
          description: Field the exported list is sorted by
          example: DATE
          schema:
            type: string
            description: ''
            default: DATE
        - in: query
          name: sortOrder
          required: false
          description: Sort direction of the exported list
          example: ASC
          schema:
            type: string
            description: ''
            default: ASC
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                year:
                  type: integer
                  description: Year to list vacation requests for
                month:
                  type: integer
                  description: Month to restrict the listing to; 0 means the whole year
                employeeIds:
                  type: array
                  description: Identifiers of employees to include
                  items:
                    type: object
                departmentIds:
                  type: array
                  description: Identifiers of departments to include
                  items:
                    type: object
                planningTypes:
                  type: array
                  description: Planning types to filter the requests by
                  items:
                    type: object
                planningAdditionalIds:
                  type: array
                  description: Additional absence sub-type identifiers to filter by
                  items:
                    type: object
                customTypeIds:
                  type: array
                  description: Custom absence type identifiers to filter by
                  items:
                    type: object
                excludeVacationRequestIds:
                  type: array
                  description: Identifiers of vacation requests to exclude from the result
                  items:
                    type: object
                statesOnly:
                  type: array
                  description: Restrict the result to requests in these approval states
                  items:
                    type: object
                checkPermissions:
                  type: boolean
                  description: Whether permission checks are applied when listing
                addFrontendValues:
                  type: boolean
                  description: Whether to include display flags such as editable, deletable and acceptable
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests/planningAdditionalTypes/{id}:
    delete:
      operationId: delete_api_v1_vacationRequests_planningAdditionalTypes_id
      tags:
        - vacationRequests - balance & config
      summary: Delete entity
      description: Deletes the planning additional-type with the given id.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the planning additional type
          example: '17'
          schema:
            type: string
      responses:
        '204':
          description: Operation succeeded (no content).
        '403':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: get_api_v1_vacationRequests_planningAdditionalTypes_id
      tags:
        - vacationRequests - balance & config
      summary: Get entity
      description: Returns the planning additional-type with the given id.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the planning additional type
          example: '17'
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_vacationRequests_planningAdditionalTypes_id
      tags:
        - vacationRequests - balance & config
      summary: Edit entity
      description: Updates the planning additional-type with the given id.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the planning additional type
          example: '17'
          schema:
            type: string
      requestBody:
        description: JSON body. JSON request body — see the schema for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body.
              required:
                - name
              properties:
                id:
                  type: integer
                  description: Unique identifier of the planning additional type
                name:
                  type: string
                  description: Display name of the additional type
                charged:
                  type: boolean
                  description: Whether time booked to this type is billable
                type:
                  type: string
                  description: Sub-category of the additional type
                  enum:
                    - ABSENCE
                    - CUSTOM
                backgroundColor:
                  type: string
                  description: Background color used to display this type in the planning view
                fontColor:
                  type: string
                  description: Font color used to display this type in the planning view
                active:
                  type: boolean
                  description: Whether the additional type is currently active
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests/properties:
    post:
      operationId: post_api_v1_vacationRequests_properties
      tags:
        - vacationRequests
      summary: Get vacation requests properties
      description: Returns the properties used by the vacation-request UI for the supplied query.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Unique identifier of the vacation request
                planningType:
                  type: string
                  description: Type of planning entry this request represents
                  enum:
                    - NONE
                    - SUPPORT
                    - APPOINTMENT_PROPOSAL
                    - APPOINTMENT_FIX
                    - VACATION
                    - ILLNESS
                    - ABSENCE
                    - STAND_BY
                    - APPOINTMENT_PRIVATE
                    - OVERTIME
                    - CUSTOM
                status:
                  type: string
                  description: Approval status of the request
                  enum:
                    - NEW
                    - REQUESTED
                    - APPROVED
                    - DECLINED
                startDate:
                  type: integer
                  format: int64
                  description: Start of the requested absence as a Unix timestamp
                endDate:
                  type: integer
                  format: int64
                  description: End of the requested absence as a Unix timestamp
                requesterId:
                  type: integer
                  description: Identifier of the employee who filed the request
                requestReason:
                  type: string
                  description: Reason text provided by the requester
                requestDate:
                  type: integer
                  format: int64
                  description: When the request was submitted, as a Unix timestamp
                supervisorId:
                  type: integer
                  description: Identifier of the supervisor handling the request
                supervisorReason:
                  type: string
                  description: Reason or comment provided by the supervisor
                planningAdditionalId:
                  type: integer
                  description: Additional absence sub-type identifier, used only for absence entries
                processId:
                  type: integer
                  description: Identifier of the approval process the request runs through
                processStepId:
                  type: integer
                  description: Identifier of the current approval process step
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vacationRequests/{id}/pdf:
    get:
      operationId: get_api_v1_vacationRequests_id_pdf
      tags:
        - vacationRequests
      summary: Get vacation requests pdf
      description: Returns the given vacation request, including its individual days, rendered as a PDF document.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the vacation request
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: Response payload.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/vouchers/{id}:
    get:
      operationId: get_api_v1_vouchers_id
      tags:
        - company
      summary: Get voucher
      description: |
        Returns a single object (invoice/voucher created from billed supports) by its id. Standard access checks apply — vouchers are an internal billing artefact, so customer users do not reach this endpoint; technicians or freelancers need access to the voucher's company.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the voucher.
          example: 42
          schema:
            type: integer
      responses:
        '200':
          description: Resource(s) returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    description: The requested object.
              example:
                meta: {}
                content:
                  id: 9001
                  number: VS-2024-0042
                  companyId: 100023
                  contractId: 0
                  export: NONE
                  totalAmount: 1250
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_vouchers_id
      tags:
        - company
      summary: Reset voucher export state
      description: |
        Resets the voucher's export state to `NONE`, allowing it to be re-exported (e.g. re-sent to an accounting system). The voucher itself is not regenerated. Same access constraints as the GET — a technician with access to the voucher's company.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the voucher.
          example: 42
          schema:
            type: integer
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
              example:
                meta: {}
                content: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/workflowContracts/configs/{contractType}:
    get:
      operationId: get_api_v1_workflowContracts_configs_contractType
      tags:
        - workflow contracts
      summary: Get configs of type
      description: |
        Returns all workflow contract configuration containers (templates) for the given contract type, e.g. all templates that can be used to start a `MANAGED_SERVICES` workflow. Each container groups its raw key/value config entries plus a derived `active` flag (driven by the `INACTIVE` config item) and the resolved template name. Restricted to technicians/freelancers.
      parameters:
        - in: path
          name: contractType
          required: true
          description: Workflow contract type to fetch configs for (e.g. MANAGED_SERVICES).
          example: MANAGED_SERVICES
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: List of objects (one per matching template).
              example:
                meta: {}
                content:
                  - configId: 12
                    name: Managed Services Standard
                    type: MANAGED_SERVICES
                    active: true
                    config:
                      NAME: Managed Services Standard
                      CONTRACT_WORKFLOW_TYPE: '1'
                      INACTIVE: '0'
                  - configId: 17
                    name: Managed Services Premium
                    type: MANAGED_SERVICES
                    active: false
                    config:
                      NAME: Managed Services Premium
                      CONTRACT_WORKFLOW_TYPE: '1'
                      INACTIVE: '1'
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/workflowContracts/startWorkflow:
    post:
      operationId: post_api_v1_workflowContracts_startWorkflow
      tags:
        - workflow contracts
      summary: Start workflow
      description: |
        Kicks off a contract workflow for the given company using a previously configured workflow template (`configId`). The server validates that the caller has company access plus the `START_CONTRACT_WORKFLOW` permission, that the template is active, and that company/employee references are set, then hands the request to the legacy PHP handler which performs the actual workflow start (sending invites, creating contract records, etc.). Restricted to technicians/freelancers.
      requestBody:
        description: JSON request body — see the example for the field shape.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                configId:
                  type: integer
                  description: Identifier of the workflow configuration to start
                companyId:
                  type: integer
                  description: Identifier of the company the workflow is started for
                employeeId:
                  type: integer
                  description: Identifier of the employee the workflow is started for
            example:
              configId: 12
              companyId: 134
              employeeId: 27
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    description: An object carrying the PHP handler's reply for the started workflow.
              example:
                meta: {}
                content:
                  success: true
                  workflowContractId: 87
                  message: Workflow started
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/workingHours/client:
    get:
      operationId: get_api_v1_workingHours_client
      tags:
        - working hours
      summary: Get client working hours
      description: |
        Returns every customer-side working-time model with its weekday entries plus counters of related companies and contracts. Open to technicians/freelancers; the counters are computed by joining contract and company-pref tables.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Standard
                        relatedCompaniesCount:
                          type: integer
                          example: 12
                        relatedContractsCount:
                          type: integer
                          example: 4
                        days:
                          type: object
                          example:
                            MONDAY:
                              beginHour: 8
                              beginMinute: 0
                              endHour: 17
                              endMinute: 0
              example:
                meta: {}
                content:
                  - id: 1
                    name: Standard
                    relatedCompaniesCount: 12
                    relatedContractsCount: 4
                    days:
                      MONDAY:
                        beginHour: 8
                        beginMinute: 0
                        endHour: 17
                        endMinute: 0
                      TUESDAY:
                        beginHour: 8
                        beginMinute: 0
                        endHour: 17
                        endMinute: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: post_api_v1_workingHours_client
      tags:
        - working hours
      summary: Create client working hours
      description: |
        Creates a new customer-side working-time model from the supplied container (id plus a map of weekday entries). Requires `MANAGE_WORKING_HOURS_OF_CUSTOMERS`; the new model can then be assigned to companies, contracts, or SLAs.
      requestBody:
        description: An object.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Unique identifier of the working hours model
                name:
                  type: string
                  description: Display name of the working hours model
                days:
                  type: object
                  description: Working hours per weekday, keyed by day of the week
                relatedCompaniesCount:
                  type: integer
                  description: Number of companies using this working hours model
                relatedContractsCount:
                  type: integer
                  description: Number of contracts using this working hours model
            example:
              id: 0
              name: Standard
              days:
                MONDAY:
                  beginHour: 8
                  beginMinute: 0
                  endHour: 17
                  endMinute: 0
                TUESDAY:
                  beginHour: 8
                  beginMinute: 0
                  endHour: 17
                  endMinute: 0
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: Standard
                      days:
                        type: object
              example:
                meta: {}
                content:
                  id: 1
                  name: Standard
                  days:
                    MONDAY:
                      beginHour: 8
                      beginMinute: 0
                      endHour: 17
                      endMinute: 0
        '403':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: put_api_v1_workingHours_client
      tags:
        - working hours
      summary: Update client working hours
      description: |
        Replaces the weekday entries of an existing customer working-time model identified by `id` inside the body. Requires `MANAGE_WORKING_HOURS_OF_CUSTOMERS`; no payload is returned, just a 202 status.
      requestBody:
        description: An object.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Unique identifier of the working hours model
                name:
                  type: string
                  description: Display name of the working hours model
                days:
                  type: object
                  description: Working hours per weekday, keyed by day of the week
                relatedCompaniesCount:
                  type: integer
                  description: Number of companies using this working hours model
                relatedContractsCount:
                  type: integer
                  description: Number of contracts using this working hours model
            example:
              id: 1
              name: Standard
              days:
                MONDAY:
                  beginHour: 9
                  beginMinute: 0
                  endHour: 18
                  endMinute: 0
      responses:
        '202':
          description: Resource updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
              example:
                meta: {}
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/workingHours/client/{id}:
    delete:
      operationId: delete_api_v1_workingHours_client_id
      tags:
        - working hours
      summary: Delete client working hours
      description: |
        Removes the customer-side working-time model with the given `id`, including all weekday entries inside its container. Requires the caller to be a technician/freelancer with `MANAGE_WORKING_HOURS_OF_CUSTOMERS`; entities still referencing the model are surfaced by the related `assignments` endpoint.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the client working-time model to delete.
          schema:
            type: integer
          example: 42
      responses:
        '204':
          description: Resource deleted.
        '403':
          $ref: '#/components/responses/ErrorResponse'
  /api/v1/workingHours/client/{id}/assignments:
    get:
      operationId: get_api_v1_workingHours_client_id_assignments
      tags:
        - working hours
      summary: Get working hours assignments
      description: |
        Lists every entity (companies, contracts, SLAs) that references the working-time model with the given `id`. Used in the admin UI to warn before a model is renamed or deleted.
      parameters:
        - in: path
          name: id
          required: true
          description: Id of the client working-time model whose assignments should be listed.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/TnsMetaMessage'
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        linkTypeId:
                          type: integer
                          example: 2
                        linkId:
                          type: integer
                          example: 1000
                        name:
                          type: string
                          example: Mustermann GmbH
              example:
                meta: {}
                content:
                  - linkTypeId: 2
                    linkId: 1000
                    name: Mustermann GmbH
                  - linkTypeId: 6
                    linkId: 42
                    name: Wartungsvertrag Standard
        '403':
          $ref: '#/components/responses/ErrorResponse'
components:
  securitySchemes:
    ApiTokenAuth:
      type: apiKey
      in: header
      name: apiToken
      description: |
        **User session token.** JWT obtained from `POST /api/v1/login`. The value already includes
        the literal `Bearer ` prefix — send it verbatim in the `apiToken` header. This is the token
        a logged-in employee or customer uses for the normal `/api/v1/...` endpoints.
    ErpToken:
      type: apiKey
      in: header
      name: apiToken
      description: |
        **ERP integration token.** Created in TANSS for an external API role of `ERP`, `CENTRON`,
        or `SYSTEMHAUS_ONE`. Required for the `/api/erp/v1/...` and `/api/systemhaus_one/v1/...`
        endpoints. Sent in the `apiToken` header (with the `Bearer ` prefix). A normal user login
        token will NOT work for these routes.
    PhoneToken:
      type: apiKey
      in: header
      name: apiToken
      description: |
        **Telephony (PHONE) integration token.** Created in TANSS for the external API role `PHONE`.
        Required for the `/api/calls/v1/...` call-import endpoints. Sent in the `apiToken` header
        (with the `Bearer ` prefix). A normal user login token will NOT work for these routes.
    RemoteSupportToken:
      type: apiKey
      in: header
      name: apiToken
      description: |
        **Remote-support integration token.** Created in TANSS for the external API role
        `REMOTE_SUPPORT`. Required for the `/api/remoteSupports/v1/...` endpoints. Sent in the
        `apiToken` header (with the `Bearer ` prefix). A normal user login token will NOT work here.
    MonitoringToken:
      type: apiKey
      in: header
      name: apiToken
      description: |
        **Monitoring integration token.** Created in TANSS for the external API role `MONITORING`
        (generic monitoring) or `SERVEREYE` (Server-Eye). Required for the `/api/monitoring/v1/...`
        and `/api/servereye/v1/...` endpoints. Sent in the `apiToken` header (with the `Bearer `
        prefix). A normal user login token will NOT work for these routes.
    TimestampToken:
      type: apiKey
      in: header
      name: apiToken
      description: |
        **Timestamp terminal token.** Created in TANSS for the external API role `TIMESTAMP`.
        Required for the `/api/timestamps/v1/...` time-clock endpoint. Sent in the `apiToken`
        header (with the `Bearer ` prefix). This is distinct from the user-context timestamp
        routes under `/api/v1/timestamps`, which use the normal user token.
    DeviceManagementToken:
      type: apiKey
      in: header
      name: apiToken
      description: |
        **Device-management integration token.** Created in TANSS for the external API role
        `DEVICE_MANAGEMENT`. Required for the `/api/deviceManagement/v1/...` endpoints. Sent in
        the `apiToken` header (with the `Bearer ` prefix). A normal user login token will NOT work.
  schemas:
    TnsLoginCredentials:
      description: json representing the login credentials
      type: object
      properties:
        username:
          type: string
          description: username / login name
          example: sb
        password:
          type: string
          description: passwort for this user
          example: secret password
        token:
          type: string
          description: if a two-factor-auth is used, give the token here
          example: ''
    TnsMetaProperties:
      type: object
      properties:
        fields:
          type: object
          example:
            someFieldIndex: {}
        extras:
          type: object
          example:
            someExtraIndex:
              value: someExtraValue
          additionalProperties:
            type: object
        editable:
          type: boolean
        message:
          type: string
    TnsMetaMessage:
      type: object
      properties:
        linkedEntities:
          example:
            employees:
              '2':
                name: some employee name
          type: object
        properties:
          $ref: '#/components/schemas/TnsMetaProperties'
        listProperties:
          type: object
    TnsTicketClearanceMode:
      type: string
      description: describes "how" the supports of a ticket may be cleared. Here, the default value of the OSK may be "overwritten"
      enum:
        - DEFAULT
        - DONT_CLEAR_SUPPORTS
        - MAY_CLEAR_SUPPORTS
    Ticket-Standard:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        companyId:
          type: integer
          description: |
            Company id of the ticket.
            Name is stored in the "linked entities" - "companies".
            Can only be set if the user has access to the company
          x-linked-entities: companies
          x-can-set: user needs permission for the given company
        remitterId:
          type: integer
          description: |
            If the ticket has a remitter, the id goes here.
            Name is stored in the "linked entities" - "employees"
          x-linked-entities: employees
        title:
          type: string
          description: The title / subject of the ticket
        content:
          type: string
          description: The content / description of the ticket
        extTicketId:
          type: string
          description: External ticket id (optional)
        creationDate:
          type: integer
          format: timestamp
          description: creation date of tickets as unix timestamp
          readOnly: true
        assignedToEmployeeId:
          type: integer
          description: |
            id of employee which ticket is assigned to.
            Name is stored in "linked entities" - "employees"
          x-linked-entities: employees
        assignedToDepartmentId:
          type: integer
          description: |
            id of department which ticket is assigned to.
            Name is stored in "linked entities" - "departments"
          x-linked-entities: departments
          x-can-set: technician needs the right to assign a department for tickets
          x-permission-id: 365
        assignmentName:
          type: string
          description: If ticket is assigned to a device (or employee), here the name is stored
          readOnly: true
        statusId:
          type: integer
          description: |
            id of the ticket state.
            Name is give in "linked entities" - "ticketStates"
          x-linked-entities: ticketStates
        typeId:
          type: integer
          description: |
            id of the ticket type.
            Name is give in "linked entities" - "ticketTypes"
          x-linked-entities: ticketStates
        linkTypeId:
          type: integer
          description: if ticket is assigned to device / employee, linktype is given here
        linkId:
          type: integer
          description: if ticket is assigned to device / employee, the id of the entity is given here
        deadlineDate:
          type: integer
          format: timestamp
          description: If ticket has a deadline, the date is given here
          x-can-set: technician needs the right to set the deadline date
          x-permission-id: 216
        project:
          type: boolean
          description: if ticket is actually a project, this value is true
        projectId:
          type: integer
          description: |
            if ticket is a sub-ticket of a project, the id of the project goes here.
            Name of the project is in the "linked entities" - "tickets"
          x-linked-entities: tickets
          x-can-set: can be set if the employee has access to create sub-tickets for the project
        createdEmployeeId:
          type: integer
          description: id of the employee who has created this ticket
          readOnly: true
        repair:
          type: boolean
          description: if true, this ticket is a "repair ticket"
        dueDate:
          type: integer
          format: timestamp
          description: if ticket has a due date, the timestamp is given here
          x-can-set: can be set if technician/freelancer and right to set the duedate. customers can set this with the right "customer can set due date"
          x-permission-ids:
            - 197
            - 360
        attention:
          type: string
          enum:
            - 'NO'
            - 'YES'
            - RESUBMISSION
            - MAIL
          description: Determines the "attention" flag state of a ticket
        orderById:
          type: integer
          description: |
            gives infos about how the remitter gave the order.
            Infos are stored in the "linked entities" - "orderBys"
          x-linked-entities: orderBys
        installationFee:
          type: string
          enum:
            - 'NO'
            - 'YES'
            - NO_PROJECT_INSTALLATION_FEE
          description: If the ticket has an installation fee, this value is true
        installationFeeDriveMode:
          type: string
          enum:
            - NONE
            - DRIVE_INCLUDED
            - DRIVE_EXCLUDED
          description: |
            Sets the installation fee drive mode.
            If it is set to NONE then the system config parameter "leistung.ip.fahrzeit_berechnen" will be used.
            If the company from the ticket has an installation fee drive mode set then that will be used instead of the system config parameter.
        installationFeeAmount:
          type: number
          format: double
          description: Amount for the installation fee
        separateBilling:
          type: boolean
          description: If true, the ticket shall be billed separately
        serviceCapAmount:
          type: number
          format: double
          description: if the ticket has a service cap, here the amount is given
          x-can-set: need right to autorize a new service cap
          x-permission-id: 215
        relationshipLinkTypeId:
          type: integer
          description: linkTypeId of the relationship (if ticket has a relation)
        relationshipLinkId:
          type: integer
          description: linkId of the relationship (if ticket has a relation)
        resubmissionDate:
          type: integer
          format: timestamp
          description: if the ticket as a resubmission date set, this is given here
        estimatedMinutes:
          type: integer
          description: Number of estimated minutes which is planned for the ticket
        estimatedMinutesImage:
          type: string
          description: This is used to display the correct image for the "estimated minutes" icon in the ticket lists
          readOnly: true
        localTicketAdminFlag:
          type: string
          enum:
            - NONE
            - LOCAL_ADMIN
            - TECHNICIAN
          description: |
            Determines wether the ticket is assigned to a local ticket admin or not
            - NONE: "normal" ticket
            - LOCAL_ADMIN: ticket is assigned to a local ticket admin
            - TECHNICIAN: local ticket admin has forwarded the ticket to a technician
        localTicketAdminEmployeeId:
          type: integer
          description: if the ticket is assigned to a local ticket admin, this represents the employee (local ticket admin) who is assigned for this ticket
        phaseId:
          type: integer
          description: |
            if the ticket is assignet to a project phase.
            The name of the phase is stored in the "linked entities" - "phases"
          x-linked-entities: phases
        resubmissionText:
          type: string
          description: If a resubmission text is set, this text is returned here
        orderNumber:
          type: string
          description: Sets the order number
        reminder:
          type: integer
          format: timestamp
          description: If the ticket has a reminder set, the timestamp is returned here
          x-can-set: technicians need the right to "change reminders"
          x-permission-id: 198
        clearanceMode:
          $ref: '#/components/schemas/TnsTicketClearanceMode'
    TnsChat-Vue:
      type: object
      properties:
        id:
          type: integer
        unreadMessages:
          type: integer
          description: number of unread messages
    TnsPlanningType:
      type: string
      description: The planning type defines if a support is actually a support, appointment (or some other type)
      enum:
        - SUPPORT
        - APPOINTMENT_PROPOSAL
        - APPOINTMENT_FIX
        - VACATION
        - ILLNESS
        - ABSENCE
        - STAND_BY
        - APPOINTMENT_PRIVATE
        - OVERTIME
        - CUSTOM
    TnsSupportLocation:
      type: string
      description: Defines, where a support takes place
      enum:
        - OFFICE
        - CUSTOMER
        - REMOTE
    TnsSupportFuture:
      type: object
      properties:
        id:
          type: integer
        date:
          type: integer
          format: timestamp
          description: date of the support
        planningType:
          $ref: '#/components/schemas/TnsPlanningType'
        employeeId:
          type: integer
        location:
          $ref: '#/components/schemas/TnsSupportLocation'
        duration:
          type: integer
        durationApproach:
          type: integer
        durationDeparture:
          type: integer
        text:
          type: string
    Ticket-List:
      description: model used to render tickets in lists
      allOf:
        - $ref: '#/components/schemas/Ticket-Standard'
        - type: object
          properties:
            modifiedBy:
              type: integer
              description: id of the employee who last modified this ticket
              readOnly: true
            modifiedTime:
              type: integer
              format: timestamp
              description: timestamp, when the ticket was last modified
              readOnly: true
            modifiedText:
              type: string
              description: infos about the last change for this ticket
              readOnly: true
            numberOfDocuments:
              type: integer
              description: number of documents for this ticket
              readOnly: true
            chats:
              description: list of chat ids for this ticket
              readOnly: true
              type: array
              items:
                $ref: '#/components/schemas/TnsChat-Vue'
            nextSupport:
              $ref: '#/components/schemas/TnsSupportFuture'
            remitterDepartmentName:
              type: string
              description: If the remitter is assigned to a department, returns the name of the department
              readOnly: true
            remitterDepartmentId:
              type: integer
              description: If the remitter is assigned to a department, returns the id of the department
              readOnly: true
            internalContent:
              type: string
              description: returns the internal content if the user has right to
            modified:
              type: integer
              description: timestamp of last modification
    TnsErrorCode:
      type: string
      description: |
        Stable, machine-readable error code returned in the error's `text` field. Use this (not the
        human-readable `localizedText`) for programmatic error handling. The full list below is
        generated from the server's `*ExceptionMessages` enums.
      enum:
        - ACCOUNTING_TYPE_MUST_BE_GIVEN
        - ACCOUNTING_TYPE_WITH_ID_ALREADY_EXISTS
        - ACTION_TYPE_CAN_NOT_BE_NULL
        - ACTIVATING_UNFINISHED_WIZARD
        - ADJUST_RANK_INVALID
        - AD_HOC_CANT_MULTIPLE_ASSIGNMENTS
        - ALREADY_DEFINED
        - ALREADY_MERGED
        - ALREADY_SET_TIME_CONDITION
        - APPOINTMENT_CONFIRMATION_NO_RECEIVERS
        - APPOINTMENT_CONFIRMATION_REMITTER_HAS_NO_MAIL_ADDRESS
        - APPOINTMENT_CONFIRMATION_WITHOUT_REMITTER
        - APPROVAL_PROCESS_ITEMS_MAY_ONLY_HAVE_ONE_EVENT_OF_TYPE_APPROVAL_PROCESS
        - APPROVAL_PROCESS_ITEMS_MUST_HAVE_ONE_EVENT_OF_TYPE_APPROVAL_PROCESS
        - ASSET_DUPLICATE_FIELD
        - ASSET_FIELD_CANNOT_BE_NULL
        - ASSET_FIELD_CREATE_OR_UPDATE_FAILED
        - ASSET_FIELD_DEFAULT_REMAP_FAILED
        - ASSET_FIELD_DELETE_FAILED
        - ASSET_FIELD_ID_UNDETERMINED_CUSTOM
        - ASSET_FIELD_ID_UNDETERMINED_FIELDS
        - ASSET_FIELD_LOAD_FAILED
        - ASSET_FIELD_PROCESSING_FAILED
        - ASSET_FIELD_REQUIRED
        - ASSET_FIELD_REQUIRED_WITH_NAME
        - ASSET_FIELD_TYPE_UNDETERMINED_CUSTOM
        - ASSET_FIELD_TYPE_UNDETERMINED_FIELDS
        - ASSET_FIELD_VALUE_INVALID
        - ASSET_LINK_HANDLING_FAILED
        - ASSET_MULTISELECT_OPTIONS_UPDATE_FAILED
        - ASSET_MULTISELECT_UPDATE_FAILED
        - ASSET_SEARCH_INDEX_UPDATE_FAILED
        - ASSET_TYPE_NOT_ACTIVE
        - ASSET_TYPE_NOT_FOUND
        - ASSIGNMENT_NOT_EXIST
        - ASSIGNMENT_NOT_FOUND
        - ASSIGNMENT_NOT_WITHIN_COMPANY
        - AT_LEAST_ONE_FILTER_CIRTERIA
        - AT_LEAST_ONE_LINKID_MUST_BE_GIVEN
        - AT_LEAST_ONE_SUPPORT_IS_MISSING
        - AUTHENTICATION_FAILED
        - AZURE_MISSING_CLIENT_ID
        - AZURE_MISSING_CLIENT_SECRET
        - AZURE_MISSING_REFRESH_TOKEN
        - A_DAY_MUST_BE_SPECIFIED
        - A_DESCRIPTION_MUST_BE_SPECIFIED
        - A_MONTH_MUST_BE_SPECIFIED
        - BACKGROUNDCOLOR_MUST_HAVE_7_CHARS
        - BASE64_ERROR
        - BEGIN_A_WIZARD_BEFORE_TRYING_TO_CONTINUE
        - BOOK_CHECK_NO_BOOKED_SUPPORTS
        - BOOK_CHECK_NO_PERMISSIONS
        - BOOK_CHECK_ONLY_INTERNAL_SUPPORTS
        - BREAK_IS_OUTSIDE_OF_SUPPORT
        - CALCULATED_SUPPORT_NOT_FOUND
        - CALLBACK_NOT_FOUND_OR_NO_ACCESS
        - CANNOT_ACCESS_TICKET_SYSTEM
        - CANNOT_CHANGE_BOTH_POSITION_VALUES
        - CANNOT_CREATE_ENTITY_FROM_TEMPLATE
        - CANNOT_CREATE_ID
        - CANNOT_CREATE_TEMPLATE_FROM_ENTITY
        - CANNOT_DELETE_CONFIG_WITH_LINKED_PROMPTS
        - CANNOT_DELETE_ENTITY_LINKED_ENTITIES
        - CANNOT_DELETE_FILES
        - CANNOT_READ_CONTENT_OF_FILE
        - CANNOT_SAVE
        - CANNOT_SAVE_FILE
        - CANNOT_SEND_MAILS_TO_GIVEN_ADDRESSES
        - CANNOT_SEND_MAIL_TO
        - CANT_ACCESS_INACTIVE_EMPLOYEES
        - CANT_ACCESS_THIS_EMPLOYEES
        - CANT_ADD_CHECKLISTS_TO_PROJECTS
        - CANT_APPEND_SUPPORT_TO_THIS_ID
        - CANT_ASSIGN_GROUPTAG_TO_TICKET
        - CANT_BOOK_PREPAID_SUPPORTS_DIRECTLY
        - CANT_CHANGE_ACTIVE_BECAUSE_ASSIGNED_TO_CONTRACTS
        - CANT_CHANGE_CLOSED_TICKETS
        - CANT_CHANGE_COMPANY_BECAUSE_ASSIGNED_TO_CONTRACTS
        - CANT_CHANGE_DAY_OF_TIMESTAMP
        - CANT_CHANGE_INSTALLATION_FEE_BECAUSE_OF_PREPAID_SUPPORTS
        - CANT_CHANGE_TO_STATUS_NEW
        - CANT_CHECK_ITEM_TWICE
        - CANT_CLOSE_TICKET
        - CANT_CONVERT_ITEM_BECAUSE_HAS_MORE_THAN_ONE_SEMIAUTOMATIC_EVENT
        - CANT_COVERT_ADHOC_CHECKLISTS
        - CANT_COVERT_TO_ADHOC_CHECKLIST
        - CANT_COVERT_TO_CHECKLIST_BECAUSE_TEMPLATE_IS_IN_USE_IN_OTHER_CHECKLISTS
        - CANT_COVERT_TO_TEMPLATE_BECAUSE_ATTACHED_TO_TICKETS
        - CANT_COVERT_TO_TEMPLATE_BECAUSE_CHECKLISTS_ARE_INCLUDED
        - CANT_COVERT_TO_TEMPLATE_BECAUSE_HAS_SERVICE_CATALOG_SELECTION
        - CANT_CREATE_ADHOC_CHECKLISTS
        - CANT_CREATE_APPOINTMENTS_FOR_OTHER_USERS
        - CANT_CREATE_APPOINTMENT_FOR_CLOSED_TICKET
        - CANT_CREATE_CHECKLISTS
        - CANT_CREATE_FILE_PASS
        - CANT_CREATE_FREELANCER__LICENSE_EXCEEDING
        - CANT_CREATE_NEW_VERSION_BECAUSE_CHECKLIST_HAS_A_SUCCESSOR
        - CANT_CREATE_PRIVATE_APPOINTMENTS_FOR_THIS_USER
        - CANT_CREATE_STANDBY
        - CANT_CREATE_SUPPORT_FOR_INACTIVE_COMPANY
        - CANT_CREATE_SUPPORT_FOR_OTHER_USERS
        - CANT_CREATE_SUPPORT_WITHOUT_EMPLOYEE
        - CANT_CREATE_TECHNICIAN__LICENSE_EXCEEDING
        - CANT_DELETE_ENTITY
        - CANT_DELETE_OWN_ABSENCES
        - CANT_DELETE_PRIVATE_APPOINTMENT
        - CANT_DELETE_SUPPORT
        - CANT_DELETE_TAG__ASSIGNMENTS
        - CANT_DELETE_THIS_ABSENCE
        - CANT_EDIT_CHECKLISTS
        - CANT_EDIT_LOCKED_TICKET
        - CANT_EDIT_OFFER
        - CANT_EDIT_SUPPORT
        - CANT_EDIT_THIS_ADHOC_CHECKLIST
        - CANT_EDIT_TICKET
        - CANT_EDIT_TIMESTAMP
        - CANT_EDIT_TIMESTAMP_OF_USER
        - CANT_FIND_ACCESS_TOKEN
        - CANT_INCLUDE_CHECKLISTS_IN_TEMPLATES
        - CANT_INCLUDE_SAME_CHECKLIST_TWICE
        - CANT_INVITE_OTHERS
        - CANT_LOAD_QR_CONFIG
        - CANT_MERGE_BECAUSE_OF_SERVICE_CAP
        - CANT_MODIFY_DOCUMENT
        - CANT_MODIFY_JSON_FIELD
        - CANT_MODIFY_SCREENSHOT
        - CANT_MODIFY_TIMESTAMPS_FROM_OTHER_EMPLOYEES
        - CANT_MODIFY_TIMESTAMP_DAYCLOSING_EXISTS
        - CANT_MOVE_UPLOADED_FILE
        - CANT_MOVE_UPLOADED_SIGNATURE
        - CANT_REMOVE_NOT_CHARGED_BECAUSE_TYPE_IS_NOT_CHARGED
        - CANT_REPLY_TO_MAIL
        - CANT_SERIALIZE_TO_JSON
        - CANT_SET_DATE_MANUALLY
        - CANT_SET_HEADQUERTER_BECAUSE_COMPANY_ALREADY_HAS_BRANCHES
        - CANT_SET_INTERNAL_AND_BOOKED_AT_SAME_TIME
        - CANT_SET_OWN_USER_INACTIVE
        - CANT_UNBOOK_ALREADY_BOOKED_CONTRACT_SUPPORT_WITH_VOUCHER
        - CANT_UNCHECK_ITEM_TWICE
        - CANT_VIEW_PROJECT_STATISTICS
        - CANT_VIEW_ROLES
        - CANT_VIEW_STATISTICS
        - CAN_CONVERT_TO_INSTALLATION_FEE_BECAUSE_OF_FULLSERVICE_SUPPORTS
        - CAN_ONLY_ACCESS_MONITORING_TICKETS
        - CAN_ONLY_EDIT_OWN_TIMESTAMPS
        - CAN_ONLY_VIEW_OWN_TICKETS
        - CARD_UPDATE_FAILED
        - CATEGORY_DOESNT_EXIST
        - CATEGORY_NOT_FOUND
        - CHANGES_WERE_DISCARDED
        - CHAT_ALREADY_OPEN
        - CHAT_ID_UNKNOWN
        - CHAT_MESSAGE_MUST_CONTAINT_CONTENT
        - CHAT_MESSAGE_MUST_CONTAIN_CHAT_ID
        - CHAT_MUST_CONTAINT_DESCRIPTION
        - CHAT_MUST_CONTAINT_ONE_MESSAGE
        - CHAT_MUST_CONTAINT_ONE_PARTICIPANT
        - CHAT_NOT_FOUND
        - CHAT_PARTICIPANT_MUST_CONTAINT_DEPARTMENT_OR_EMPLOYEE
        - CHECKBOX_FIELD_REQUIRED_BUT_FALSE
        - CHECKLIST_ID_NOT_GIVEN
        - CHECKLIST_IS_IN_USE
        - CHECKLIST_ITEM_NOT_FOUND
        - CHECKLIST_NOT_FOUND
        - CHECKLIST_OR_OLDER_VERSION_ALREADY_ATTACHED_TO_TICKET
        - CLASS_CANT_BE_NULL
        - CLEAR_ALREADY_CLEARED
        - CLEAR_ALREADY_UNCLEARED
        - CLEAR_BOOK_CHECK_NO_CONSULTATIONS
        - CLEAR_BOOK_CHECK_ONLY_SUPPORTS
        - CLEAR_BOOK_CHECK_ONLY_TECHNICIANS
        - CLEAR_CANT_BECAUSE_TICKET_IS_OPEN
        - CLEAR_CHECK_NO_PERMISSIONS
        - COMPANY_ID_MUST_BE_GIVEN
        - COMPANY_IS_INACTIVE
        - COMPANY_IS_MISSING
        - COMPANY_MUST_BE_GIVEN
        - COMPANY_NAME_MUST_BE_GIVEN
        - COMPANY_WITH_SAME_NAME_AND_ADDRESS_EXISTS
        - COMPONENT_AT_LEAST_ONE_FILTER
        - COMPONENT_CANT_ACCESS_COMPANY_OF_PC
        - COMPONENT_CANT_ACCESS_COMPANY_OF_PERIPHERY
        - COMPONENT_CANT_BE_ASSIGNED_TO_PC_AND_PERIPHERY
        - COMPONENT_MUST_HAVE_A_COMPONENT_TYPE_SET
        - COMPONENT_PC_DOESNT_EXIST
        - COMPONENT_PERIPHERY_DOESNT_EXIST
        - CONFIGURATION_MUST_CONTRAIN_AT_LEAST_ONE_PDF_FIELD
        - CONFIG_ID_MUST_BE_GIVEN
        - CONFIG_IS_INACTIVE
        - CONNECTION_FAILED
        - CONTEXT_MUST_BE_GIVEN
        - CONTRACT_LANDING_PAGE_AUTHORIZED_SIGNATORY_MISSING_EMAIL
        - CONTRACT_LANDING_PAGE_AUTHORIZED_SIGNATORY_MISSING_NAME
        - CONTRACT_LANDING_PAGE_MISSING_AUTHORIZATORS
        - CONTRACT_LANDING_PAGE_MISSING_CONTRACT
        - CONTRACT_MUST_BE_PREPAID
        - CONTRACT_NOT_ALLOWED_FOR_SEPARATE_BILLED_TICKET
        - CONTRACT_NOT_VALID
        - CONTRACT_WORKFLOW_LANDING_PAGE_TOKEN_EXPIRED
        - COST_CENTER_REQUIRED
        - COULD_NOT_DECODE_STRING
        - COULD_NOT_ENQUEUE_EVENT_FOR_EVENT_BUS
        - CREATE_A_LOOP_ERROR
        - CREATE_SUPPORT_FIELD_ONLY_ALLOWED_IN_TEMPLATE
        - CREATE_SUPPORT_FIELD_REQUIRES_PROFILE
        - CURRENCY_INVALID_CURRENCY_TYPE
        - CURRENCY_TYPE_REQUIRED
        - CURRENT_USER_NOT_EXISTS
        - CUSTOM_TYPE_INVALID
        - CUSTOM_TYPE_MUST_BE_SET
        - CUSTOM_TYPE_TIMEFRAME_MUST_BE_SET
        - DATA_NOT_FOUND
        - DATE_CANT_BE_BEFORE_START
        - DATE_CONFIG_CONFLICTING_CONSTRAINTS
        - DATE_CONFLICTING_CONSTRAINTS
        - DATE_MUST_BE_GIVEN_WHILE_CONVERTING_A_RECURRING_APPOINTMENT
        - DATE_MUST_BE_OLDER_THAN_NOW
        - DATE_MUST_BE_YOUNGER_THAN_NOW
        - DATE_TOO_FAR_IN_FUTURE
        - DATE_TOO_FAR_IN_PAST
        - DAYCLOSING_ALREADY_EXISTS
        - DAYCLOSING_DOESNT_EXIST
        - DAY_HAS_NEGATIVE_DURATION
        - DEPARTMENT_MUST_BE_GIVEN
        - DESCRIPTION_CONTAINS_ONLY_NUMBERS
        - DEVICE_MUST_HAVE_A_COMPANY_SET
        - DUE_CHANGE_REASON_REQUIRED
        - DUE_DATE_MUST_NOT_BE_LATER_THAN_DEADLINE
        - DUPLICATED_EMPLOYEE
        - DUPLICATED_FILES
        - DUPLICATE_CALL_ID
        - DUPLICATE_NAME
        - DUPLICATE_TANSS_X_SUPPORT_FOUND
        - EDITOR_DOCUMENT_LOCKED_BY_OTHER
        - EMLOYEE_ID_MUST_BE_SET
        - EMPLOYEES_ARE_NULL
        - EMPLOYEE_HAS_NO_COMPANY_ACCESS
        - EMPLOYEE_HAS_NO_EMAIL_ADDRESS
        - EMPLOYEE_IDS_ARE_NULL
        - EMPLOYEE_ID_IS_NOT_A_NUMBER
        - EMPLOYEE_ID_MUST_BE_GIVEN
        - EMPLOYEE_MUST_CONTAIN_AT_LEAST_ONE_COMPANY_ASSIGNMENT
        - EMPLOYEE_NOT_FOUND
        - EMPLOYEE_OR_DEPARTMENT_MUST_BE_GIVEN
        - EMPTY_CARD_DATA
        - EMPTY_FILE
        - EMPTY_JSON_VALUE
        - EMPTY_LINK
        - ENTITY_CANT_BE_SET_INACTIVE_ASSIGNED_TO_CONTRACT
        - ENTITY_COUNT_CONFIG_MISSING_COUNT_TYPE
        - ENTITY_NOT_FOUND
        - ENUM_TYPE_DONT_EXIST
        - ERP_SERVICE_CALL_EXCEPTION
        - ERROR_CALLING_PHP_TASK
        - ERROR_CONNECTING_TO_REMOTE_MAINTENANCE_DB
        - ERROR_CONNECTING_TO_SERVEREYE_API
        - ERROR_CONVERTING_EML_TO_EMAIL
        - ERROR_CONVERTING_JSON
        - ERROR_CONVERTING_MSG_TO_EMAIL
        - ERROR_COPYING_FILE_IN_DOCUMENT_PATH
        - ERROR_COPYING_RULE
        - ERROR_CREATING_APNS_CLIENT
        - ERROR_CREATING_MASS_TICKET
        - ERROR_CREATING_MASS_TICKET_HIT
        - ERROR_CREATING_STORE
        - ERROR_DECODING_TOKEN
        - ERROR_DELETING_DATA
        - ERROR_ENCODING_PHONE_NUMBER
        - ERROR_FETCHING_ACCESS_TOKEN
        - ERROR_GETTING_DAY_FOR_OVERTIME_REQUEST
        - ERROR_GET_REQUEST
        - ERROR_IN_CHILD_CLASS
        - ERROR_MOVING_TO_FOLDER
        - ERROR_ON_API_CALL
        - ERROR_ON_APPOINTMENT_CREATION
        - ERROR_PARSING_OBJECT_TO_JSON
        - ERROR_POST_REQUEST
        - ERROR_QUERYING_DATA
        - ERROR_SENDING_PUSH_MESSAGE
        - ERROR_UPLOADING_DATA
        - ERROR_VALIDATING_INCOMING_TOKEN
        - ERROR_VALIDATING_TOKEN
        - ERROR_WHILE_CALLING_TANSS_AI
        - ERROR_WHILE_CLOSING
        - ERROR_WHILE_CONNECTING
        - ERROR_WHILE_CONNECTION_TO_LICENSE_API
        - ERROR_WHILE_CONVERTING_JSON
        - ERROR_WHILE_FETCH_MAILS
        - ERROR_WHILE_READING_MAIL
        - ERROR_WHILE_RETRIEVING_INBOX
        - ERROR_WHILE_RETRIEVING_REGISTRATION_TOKEN
        - ERROR_WRITING_DATASOURCE
        - EVENT_CLASS_NEEDS_TO_BE_REGISTERED
        - EVENT_CONTAINER_MUST_BE_AT_BEGIN_OF_CHECKLIST
        - EXT_PROGRAM_NOT_LICENSED
        - FAILING_MINIMUM_PAUSE
        - FIELD_CANT_BE_UNDER
        - FIELD_NOT_FOUND
        - FIELD_TYPE_CANNOT_BE_CHANGED
        - FIELD_VALUE_MISSING_OR_WRONG
        - FILES_LINKS_NOT_ACTIVATED
        - FILES_LINKS_ONLY_FOR_TECHNICIANS
        - FILE_NOT_FOUND_OR_WRITEABLE_OR_READABLE
        - FILE_SIZE_TOO_BIG
        - FILE_WRONG_MIME_TYPE
        - FIRST_TIMESTAMP_MUST_BE_ON
        - FONTCOLOR_MUST_HAVE_7_CHARS
        - FORBIDDEN_MISSING_PERMISSIONS
        - FORBIDDEN_NO_COMPANY_ACCESS
        - FORBIDDEN_NO_CONTRACT_ACCESS
        - FORBIDDEN_NO_DEPARTMENT_ACCESS
        - FORBIDDEN_NO_ENTITY_ACCESS
        - FORBIDDEN_TO_CHANGE_FIELD_OF_CLASS
        - FORBIDDEN_TO_MODIFY
        - FULLSERVICE_CONTRACTS_CANT_HAVE_INSTALLATION_FEE_SUPPORTS
        - FULLSERVICE_CONTRACTS_CANT_HAVE_INSTALLATION_FEE_TICKETS
        - GENERAL_EXCEPTION
        - GENERAL_LOG_CANT_VIEW_SPECIAL_ID
        - GIVEN_ARGUMENTS_NOT_VALID
        - HOLIDAY_ALREADY_EXISTS
        - ICAL_CONFIG_PASSWORD_REQUIRED
        - ICAL_GENERAL_ERROR
        - ICAL_WRONG_CONFIG_ID
        - ICAL_WRONG_TECHNICIAN_SELECTION
        - ID_MUST_BE_0
        - ID_MUST_BE_GIVEN
        - ID_MUST_BE_POSITIVE
        - IMPORT_MATCHING_ALREADY_EXISTS
        - IMPORT_MATCHING_MUST_CONTAIN_ID
        - INACTIVE_USER_LOGIN
        - INCLUDED_CHECKLIST_NOT_A_TEMPLATE
        - INCLUDED_CHECKLIST_NOT_FOUND
        - INFINITE_RECURRING_EVENTS_MUST_HAVE_END_DATE
        - INTERNAL_ERROR
        - INTERNAL_SUPPORT_CANT_BE_CLEARED
        - INVALID_AVAILABILITY_TYPE
        - INVALID_CATEGORIES_FOR_SERVICE_CATALOG_SELECTION
        - INVALID_CHECKLIST_ID
        - INVALID_CHECKLIST_ITEM_OR_MULTISELECT
        - INVALID_CHECKLIST_SELECTED_FOR_CATEGORIES
        - INVALID_CLOUD_TOKEN
        - INVALID_COST_CENTER
        - INVALID_CREATOR
        - INVALID_DEFINITION_ID
        - INVALID_DEFINITION_TYPE
        - INVALID_EML
        - INVALID_MAIL_PLACEHOLDER
        - INVALID_PARAMETER_VALUE
        - INVALID_PROJECT_ACCESS
        - INVALID_PROJECT_GIVEN
        - INVALID_RECURRENCE_RULE_GIVEN
        - INVALID_REQUEST_ERROR
        - INVALID_SIGNATURE
        - INVALID_TIMESTAMP_INFO_VALUES
        - INVALID_USER_SETTINGS
        - INVALID_VARS_STRUCTURE
        - INVALID_VAR_VALUES_ENTERED
        - IPMAC_HAS_INVALID_ASSIGNMENT_TYPE
        - ISNT_RUNNING
        - ITEM_REQUIRES_AT_LEAST_ONE_OPTION
        - ITEM_WAS_ALREADY_PARSED
        - JSON_IS_NULL
        - JSON_KEY_WRONG_MISSING
        - JSON_VALUE_WRONG_MISSING
        - KNOWLEDGE_BASE_NOT_ACTIVATED
        - KNOWLEDGE_BASE_ONLY_FOR_TECHNICIANS
        - LANDING_PAGE_MISSING_TOKEN
        - LAST_CUSTOMER_NR_SYSTEM_VALUE_MISSING
        - LAST_TIMESTAMP_MUST_BE_OFF
        - LDAP_AUTH_FAILED
        - LDAP_MISSING_PASSWORD
        - LDAP_MISSING_USERNAME
        - LICENSE_API_BODY_IS_NULL
        - LICENSE_API_DEACTIVATED
        - LICENSE_API_JSON_DESERIALIZE_ERROR
        - LICENSE_API_MESSAGE_IS_MISSING
        - LICENSE_API_NOT_SUCCESFUL
        - LICENSE_API_TANSS_AI_TOKEN_IS_MISSING
        - LICENSE_DECODE_ERROR_1
        - LICENSE_DECODE_ERROR_2
        - LICENSE_DECODE_ERROR_3
        - LICENSE_DECODE_ERROR_4
        - LICENSE_DECODE_ERROR_5
        - LICENSE_DECODE_ERROR_6
        - LICENSE_DECODE_ERROR_EXPIRED
        - LINKED_ACCOUNTING_TYPE_DOESNT_EXIST
        - LINKED_OBJECT_DOESNT_EXIST_OR_NOT_ALLOWED
        - LINKED_TECHNICIAN_WITHOUT_COMPANY_ACCESS
        - LINK_REFERENCED_BY_FIELD
        - LINK_TYPE_DOES_NOT_EXIST
        - LLM_CONFIG_NOT_CONFIRMED
        - LLM_CONFIG_NOT_FOUND
        - LOADING_DRIVER_FROM_DSN_FAILED
        - LOGGING_CATEGORY_DOESNT_EXIST
        - LOGIN_ERROR_DASHBOARD_USER_NOT_WITHIN_OWN_COMPANY
        - LOGIN_ERROR_INVALID_USERNAME_OR_PASSWORD
        - LOGIN_ERROR_MUST_GIVE_USERNAME
        - LOGIN_ERROR_MUST_SET_LOGIN_TOKEN
        - LOGIN_ERROR_NO_USER_FOR_DASHBOARD
        - LOGIN_ERROR_TOKEN_LOGIN_NEEDS_TANSS_PASSWORD
        - LOGIN_ERROR_TOO_MANY_FAILED_LOGINS
        - LOGIN_ERROR_TOO_MANY_USER_FOR_DASHBOARD
        - LOGIN_ERROR_WRONG_LOGIN_TOKEN_CODE
        - LOGIN_NAME_IS_ALREADY_IN_USE
        - LOGIN_NAME_IS_TOO_LONG
        - LOG_PATH_NOT_FOUND
        - LOOP_IN_WIZARD_GRAPH
        - MAIL_ID_IS_ZERO
        - MAIL_SEND_ERROR
        - MASS_TICKET_MISSING_PARAMETERS
        - MAY_NOT_ASSIGN_TEMPLATE_CHECKLISTS
        - MERGE_EXCEPTION
        - MINUTES_APPROVED_MUST_BE_SET
        - MINUTES_APPROVED_MUST_NOT_BE_GREATER_THAN_MINUTES_REQUESTED
        - MISSING_CHECKLIST_FOR_ITEM
        - MISSING_CHECKLIST_ITEM_OR_MULTISELECT
        - MISSING_CHECKLIST_PERMISSIONS
        - MISSING_CLIENT_ID
        - MISSING_CLIENT_SECRET
        - MISSING_COMPANY_ACCESS
        - MISSING_DOCUMENT_DIRECTORY
        - MISSING_FIELD_VALUE
        - MISSING_FOLDER_ID
        - MISSING_GET_PARAMETER
        - MISSING_IMPORT_MATCHINGS
        - MISSING_MODULE
        - MISSING_NAME_FOR_MASS_TICKET
        - MISSING_OWN_URL
        - MISSING_PARAMETER_INHERTITANCE
        - MISSING_PARAMETER_STATE
        - MISSING_PERMISSION_FOR_ASSIGNMENT
        - MISSING_PORTAL_ID
        - MISSING_QUERY_PARAMETERS
        - MISSING_SSO_PARAMETERS
        - MISSING_TENANT_ID
        - MISSING_TIME_RULE_ID
        - MISSING_TITLE
        - MODEL_IS_NOT_SUPPORTED
        - MODULE_NOT_LICENSED
        - MONITORING_GROUP_NAME_MUST_BE_SET
        - MORE_THAN_ONE_MASS_TICKET_FOR_THIS_PROJECT_EXISTS
        - MULTIPLE_IP_ADDRESS_FIELDS_NOT_ALLOWED
        - MULTISELECT_CONFIG_BOTH_OPTIONS_AND_LINK
        - MULTISELECT_CONFIG_LINK_NOT_FOUND
        - MULTISELECT_CONFIG_NO_OPTIONS_OR_LINK
        - MULTISELECT_DEFAULT_OPTION_NOT_IN_NEW_OPTIONS
        - MULTISELECT_INVALID_SELECTION_INDEX
        - MULTISELECT_LINK_TO_STATIC_IMMUTABLE
        - MULTISELECT_ONLY_ONE_BUT_MULTIPLE_VALUES
        - MULTISELECT_REPLACEMENT_INDEX_INVALID
        - MULTISELECT_REPLACEMENT_INDEX_OUT_OF_BOUNDS
        - MULTISELECT_REQUIRED_NO_REPLACE_FOR_EXISTING
        - MULTISELECT_REQUIRED_NO_REPLACE_OR_DEFAULT
        - MULTISELECT_SYSTEM_ENTRY_CANNOT_BE_DELETED
        - MUST_BE_CREATOR
        - MUST_BE_TECHNICIAN_OR_FREELANCER_TO_UPLOAD_FILES
        - MUST_CHECK_AT_LEAST_ONE_DRIVE_DURATION_OR_KM_TO_BE_CHARGED
        - MUST_NOT_USE_GENERAL_ASSIGNMENT
        - MUST_SELECT_ZONE
        - MUST_SPECIFY_EMPLOYEE_OR_DEPARTMENT
        - MUST_SPECIFY_MONTH_AND_OR_YEAR
        - MUST_WRITE_ONE_MESSAGE_TO_CLOSE_CHAT
        - NEED_ACCESS_TO_OSK
        - NEW_STATE_MUST_BE_APPROVED_OR_DECLINED
        - NOTHING_FOR_CHILD_CLASS_ERROR
        - NOT_ALLOWED_TO_CREATE_JWTS
        - NOT_ALL_FILES_HAVE_THE_SAME_TICKET
        - NOT_ALL_OBJECTS_EXIST
        - NOT_ALL_REQUIRED_JSON_DATA_SENT
        - NOT_ALL_VARS_INCLUDED
        - NOT_ENOUGH_RIGHTS
        - NOT_IMPLEMENTED
        - NO_ACCESS_FOR_EMPLOYEES_SALES_TARGET
        - NO_ACCESS_FOR_OWN_DEPARTMENT_SALES_TARGET
        - NO_ACCESS_FOR_OWN_SALES_TARGET
        - NO_ACCESS_FOR_THIS_DEPARTMENT_SALES_TARGET
        - NO_ACCESS_PREF_VALUE
        - NO_ACCESS_TO_ALL_DEPARTMENTS
        - NO_ACCESS_TO_DEPARTMENT
        - NO_ACCESS_TO_EMPLOYEE
        - NO_ACCESS_TO_PRIVATE_APPOINTMENTS_OF_THIS_USER
        - NO_ACCESS_TO_THIS_TEXTMODULE
        - NO_ACCESS_TO_TYPE
        - NO_ACCOUNT_TYPE_WITH_ID
        - NO_ALLOWED_ROUTE_FOR_DASHBOARD_TOKEN
        - NO_API_KEY_ENTERED
        - NO_API_KEY_FOR_COMPANY
        - NO_API_KEY_FOR_REQUEST
        - NO_APPOINTMENT_LINK_FOR_SUPPORT
        - NO_BACKEND_URL_GIVEN
        - NO_BUCKET_API_KEY
        - NO_CATEGORIES_FOR_SERVICE_CATALOG_SELECTION
        - NO_CHECKLIST_ASSIGNMENT_EXISTS
        - NO_COMPANY_FOUND
        - NO_COMPONENT_WITH_ID
        - NO_CONFIG_VALUE_WITH_KEY
        - NO_CONTINUE
        - NO_DATE_FOUND_FOR_PROJECT
        - NO_DEVICE_FOUND
        - NO_DEVICE_WITH_ID
        - NO_DOCUMENTS_FOUND
        - NO_DOCUMENT_PATH
        - NO_DURATION_ENTERED
        - NO_EMPLOYEES_GIVEN
        - NO_EMPLOYEE_FOUND
        - NO_EXISTING_CARDS_FOUND
        - NO_EXISTING_WIDGETS_FOUND
        - NO_EXT_PROGRAM_FOUND
        - NO_FILES_UPLOADED
        - NO_ITEM_WITH_ID
        - NO_LOGIN_TOKEN_FOUND
        - NO_MULTI_TEXT_MULTI_ASSIGNMENT_ALLOWED
        - NO_PCS_FOUND_WITH_ID
        - NO_PERMISSIONS_TO_SET_GEOCODES_FOR_THIS_ASSIGNMENT
        - NO_PERMISSION_BASED_ON_ENTITY_ACCESS
        - NO_PERMISSION_FOR_DEPARTMENT
        - NO_PERMISSION_FOR_EVENT_SYSTEM_INTEGRATION
        - NO_PERMISSION_FOR_THIS_LOG_ENTITY
        - NO_PERMISSION_FOR_TICKET_TYPE
        - NO_PERMISSION_TO_ACCEPT_OR_DECLINE_VACATION_REQUEST
        - NO_PERMISSION_TO_ADD_CHECKLIST
        - NO_PERMISSION_TO_ASSIGN_TAG
        - NO_PERMISSION_TO_CHANGE_DEADLINE
        - NO_PERMISSION_TO_EDIT_TECHNICIANS
        - NO_PERMISSION_TO_REMOVE_CHECKLIST
        - NO_PHASES_IN_PROJECT
        - NO_PHONE_NUMBERS_FOR_COMPANY
        - NO_POP_SETTINGS_FOUND
        - NO_PREFERRED_TECHNICIAN
        - NO_PROJECT_FOUND
        - NO_RECEIVERS
        - NO_RESPONSE_AVAILABLE
        - NO_ROOM_ASSIGNED_TO_SUPPORT
        - NO_SCREENSHOTS_FOUND
        - NO_SETTINGS_FOR_USER_ENTERED
        - NO_STARFACE_HOST_GIVEN
        - NO_STRATEGY_FOUND_FOR_LINKTYPE
        - NO_SUCH_PARENT
        - NO_SUPPORT_FOUND
        - NO_SYSTEM_VALUE_WITH_KEY
        - NO_SYS_TASK_FOUND_FOR_TYPE
        - NO_TICKETS_IN_PROJECT_FOUND
        - NO_TICKET_FOUND
        - NO_TICKET_WITH_ID
        - NO_TODO_FOUND
        - NO_URL_FOUND
        - NO_WIZARD_ACCESS
        - NUMBER_CONFIG_MIN_GREATER_THAN_MAX
        - NUMBER_MUST_BE_GIVEN
        - NUMBER_VALUE_ABOVE_MAX
        - NUMBER_VALUE_BELOW_MIN
        - OBJECT_CANT_BE_NULL
        - OBJECT_HASNT_ID
        - OBJECT_IN_USE
        - OBJECT_NOT_FOUND
        - OBJECT_WITH_ID_CANT_FOUND
        - OFFER_MUST_HAVE_TILL_DATE
        - OFFER_WAS_CONFIRMED
        - OLD_STATE_MUST_BE_REQUESTED
        - ONLY_ACCEPT_CLOSE_REQUEST_FROM_OWN_CHATS
        - ONLY_CONTRACT_OR_SEPARATE_BILLING_TICKET_SUPPORTS_ALLOWED
        - ONLY_CONTRACT_SUPPORTS_ALLOWED
        - ONLY_CREATOR_CAN_UPDATE_TEMPLATE
        - ONLY_HALF_DAYS_ALLOWED
        - ONLY_ONE_EVENT_CONTAINER_ALLOWED_PER_CHECKLIST
        - ONLY_ONE_SEMI_AUTOMATIC_EVENT_ALLOWED_PER_FIELD
        - ONLY_ON_TICKET
        - ONLY_TECHNICIANS_CAN_SET_FREELANCER_STATUS
        - OPEN_APPOINTMENTS_EXIST
        - OPEN_APPOINTMENTS_EXISTS
        - OPEN_CHECKLISTS_EXIST
        - OPEN_CONSULTATIONS_EXISTS
        - OUTLOOKS_COULD_NOT_BE_LOADED
        - OVERTIME_ADDITIONAL_CHARGE_VALIDATION
        - OVERTIME_BALANCE_EXCEEDED
        - OVERTIME_REQUESTS_ALREADY_EXISTS_FOR_SUPPORT
        - OVERTIME_REQUEST_MUST_HAVE_AT_LEAST_ONE_SUPPORT_ENTRY
        - OVERVIEW_NEEDS_EMPLOYEE_IDS
        - OVERVIEW_NEEDS_TIMEFRAME
        - OWN_URL_MUST_BE_CONFIGURED
        - OWN_URL_MUST_BE_DEFINED
        - PARAMETER_ID_CANNOT_BE_NULL
        - PARAMETER_ID_HAS_TO_BE_NULL
        - PARAMETER_ID_IS_INVALID
        - PARAMETER_NOT_NULL
        - PARAMETER_TOO_LONG
        - PARENT_VISIBILITY_CONSTRAINT
        - PARSE_DATE_ERROR
        - PARTICIPANT_ALREADY_EXISTS
        - PASSWORD_IS_TOO_LONG
        - PATH_IS_NULL_FOR_UPLOAD_FILE
        - PATH_NOT_RIGHT
        - PAUSE_CONFIG_FROM_MINUTES_ALREADY_EXISTS
        - PAYOUT_MUST_BE_APPROVED
        - PENDING_IMPORT_WAS_ALREADY_IMPORTED
        - PERIPHERY_ALREADY_ASSIGNED_TO_THIS_DEVICE
        - PERIPHERY_MUST_HAVE_A_PERIPHERY_TYPE_SET
        - PERIPHERY_TYPE_EMPTY
        - PERIPHERY_TYPE_WITH_NAME_ALREADY_EXISTS
        - PERSONAL_CUSTOMER_MUST_CONTAIN_EMPLOYEE
        - PHONECALL_NOT_FOUND_OR_NO_ACCESS
        - PLANNINGTYPE_CURRENTLY_NOT_ALLOWED
        - PORTAL_DOESNT_BELONG_TO_YOU
        - PORTAL_DOESNT_EXIST
        - PREFERRED_TECHNICIAN_DOESNT_EXIST
        - PREFERRED_TECHNICIAN_INACTIVE
        - PREFERRED_TECHNICIAN_NO_TECHICIAN_ANOYMORE
        - PREPAID_OBJECT_MISSING
        - PREVIOUS_ID_DOES_NOT_EXIST
        - PROJECT_ID_MUST_BE_GIVEN
        - PROJECT_NOT_FOUND_OR_NO_ACCESS
        - PROMPT_NOT_FOUND
        - PUSH_MESSAGE_ALREADY_SENT
        - PUSH_MESSAGE_NOT_FOUND
        - PUSH_WAS_REJECTED_BY_APNS
        - RADIUS_AUTHENTICATION_ERROR
        - RADIUS_CONNECTION_ERROR
        - RANK_HAVE_TO_BE_IN_RANGE
        - RATE_LIMIT_EXCEEDED
        - RECEIVER_DOESNT_EXIST
        - RECEIVER_DOESNT_HAVE_AN_EMAIL
        - RECEIVER_MUST_BE_SET
        - RECURRENCE_MASTER_CANT_BE_FOUND
        - RECURRENCE_MASTER_DOESNT_MATCH_RULE_ID
        - RECURRENCE_RULE_MUST_HAVE_START_DATE
        - RECURRENCE_RULE_NOT_ALLOWED_FOR_PLANNING_TYPE
        - RECURRENCE_RULE_NOT_FOUND
        - RECURRENCE_SEQUENCE_NOT_FOUND
        - RELATIONSHIP_MUST_CONTAIN_COMPANY_ID
        - RELATIONSHIP_NOT_VALID_FOR_COMPANY
        - RELATIONSHIP_TARGET_ASSIGNMENT_DOESNT_EXIST
        - REMITTER_HAS_NO_COMPANY_ACCESS
        - REMITTER_IS_A_MANDATORY_FIELD
        - REMITTER_IS_MISSING
        - REMOTE_MAINTENANCE_NOT_FOUND_OR_NO_ACCESS
        - REMOTE_SUPPORT_API_MUST_HAVE_TYPE
        - REPARENTING_WOULD_CREATE_CYCLE
        - REQUESTED_ITEM_DOESNT_EXIST
        - REQUESTER_HAS_NO_PERMISSIONS_FOR_PLANNING_TYPE
        - REQUEST_AT_THE_SAME_TIME
        - REQUEST_MISMATCHING_IDS
        - REQUEST_WAS_ALREADY_MARKED_AS_PAID_OUT
        - REQUIRED_PERMISSIONS_NEEDED
        - ROLE_ASSIGNMENT_NOT_FOUND
        - ROLE_PICKER_ACTION_NOT_PERMITTED
        - RRULE_GIVEN_BUT_MORE_THAN_ONE_DAY
        - RRULE_MUST_HAVE_AN_EXPIRY
        - RULE_DOESNT_EXIST
        - RULE_ID_MUST_BE_GIVEN
        - RULE_IS_INVALID
        - RULE_MUST_AT_LEAST_CONTAIN_ONE_CONDITION
        - RUNTIME_EXCEPTION
        - SELECTED_ID_IS_NOT_INSTANCE_OF_INTEGER
        - SELECTION_IS_MISSING
        - SEMI_AUTOMATIC_EVENT_INPUT_NEEDED
        - SEMI_AUTOMATIC_EVENT_INPUT_NOT_POSSIBLE
        - SENTRY_ALREADY_ACTIVATED
        - SENTRY_ALREADY_DEACTIVATED
        - SENT_JSON_WAS_WRONG
        - SEQUENCE_NOT_FOUND_IN_RULE_CALCULATIONS
        - SERVER_ERROR
        - SERVICE_CAP_INSTALLATION_FEE_EXISTS
        - SERVICE_CAP_MISSING_EMAIL
        - SERVICE_CAP_MISSING_VALUES
        - SERVICE_CAP_NO_PERMISSION
        - SERVICE_CAP_OWN_URL_MISSING
        - SERVICE_CAP_WOULD_BE_EXCEEDED
        - SERVICE_CATALOG_SELECTION_NOT_ALLOWED_IN_TEMPLATE
        - SERVICE_PROFIL_IS_MISSING
        - SERVICE_UNAVAILABLE
        - SIGNATURE_DOESNT_EXIST_IN_DATABASE
        - SIGNATURE_MUST_BE_A_JPG_FILE
        - SIGNATURE_MUST_BE_GIVEN
        - SOFTWARELICENSE_ASSIGNED_TO_CONTRACT
        - SOMETHING_WENT_WRONG_IN_OUTLOOK_SYNC
        - SOMETHING_WENT_WRONG_WHILE_CREATING_CONTINUE_STRATEGY
        - SPLIT_ERROR_MUST_HAVE_FIRST_AND_LAST_DAY
        - SSL_ERROR_WHILE_CONNECTING
        - SSO_ID_UNKNOWN
        - SSO_TOKEN_ERROR
        - SSO_USER_ERROR
        - STARFACE_HOST_SCHEMA_INVALID
        - STARFACE_HOST_URL_INVALID
        - STARFACE_LOGIN_ERROR
        - STARFACE_SUBSCRIBE_ERROR
        - STARTING_CARD_ID_INVALID_IN_WIZARD
        - STARTING_CARD_ID_NOT_SET_IN_WIZARD
        - STATE_CHANGE_OF_VACATION_REQUEST_NOT_POSSIBLE
        - STRATEGY_NOT_FOUND
        - STREAMING_NOT_SUPPORTED_FOR_THIS_LLM
        - SUPPORTS_COULD_NOT_BE_LOADED
        - SUPPORTS_MUST_BE_GIVEN_WHEN_APPROVING_OR_DECLINING_OVERTIME
        - SUPPORT_BEYOND_END_OF_LICENSE
        - SUPPORT_CANT_BE_ADDED_TO_TICKET
        - SUPPORT_CANT_BE_ASSIGNED_DIRECTLY_TO_A_PROJECT
        - SUPPORT_CANT_BE_CLEARED
        - SUPPORT_DOESNT_FIT_IN_PREPAID_QUOTA
        - SUPPORT_HAS_CHANGED
        - SUPPORT_ID_MUST_BE_GIVEN
        - SUPPORT_MISSING_ASSIGNMENT
        - SUPPORT_MUST_HAVE_A_TYPE
        - SUPPORT_NOT_FITS_IN_EXCEPTION
        - SUPPORT_PERSISTING_ABORTED_BY_USER
        - SUPPORT_TYPE_NOT_PRESENT
        - SUPPORT_VALIDATION_ERROR_NO_ACCESS
        - SUPPORT_VALIDATION_ERROR_WRONG_VALUE
        - SUPPORT_WAS_MODIFIED
        - TAG_NOT_FOUND
        - TAG_NOT_VALID_FOR_THIS_LINKTYPE
        - TANSS_AI_CONFIG_ALREADY_EXIST
        - TANSS_AI_CONFIG_IS_MISSING_OR_INCORRECT
        - TANSS_AI_ERROR_WHILE_COLLECTING_STREAM_DATA
        - TANSS_AI_SERVER_NOT_REACHABLE
        - TANSS_AI_SUMMARY_IS_ALREADY_IN_PROGRESS
        - TANSS_AI_TOO_MANY_PARALLEL_REQUESTS_FOR_TICKET_SUMMARIES
        - TANSS_DIRECTORY_MISSING_IN_APPLICATION_PROPERTIES
        - TANSS_PORTAL_ERROR
        - TANSS_PORTAL_REGISTRATION_REQUIRED
        - TANSS_PORTAL_UNREACHABLE
        - TANSS_PROXY_FORWARD_TO_ERROR
        - TANSS_PROXY_IDLE_TIMEOUT
        - TANSS_PROXY_JSON_PARSE_ERROR
        - TANSS_PROXY_JSON_SERIALIZATION_ERROR
        - TANSS_PROXY_MODEL_IS_DEPRECATED
        - TANSS_PROXY_MODEL_IS_NOT_SUPPORTED
        - TANSS_PROXY_NO_SERVER
        - TANSS_PROXY_SUMMARY_TICKET_IS_TOO_BIG
        - TANSS_PROXY_TOKEN_EXPIRED
        - TANSS_PROXY_TOKEN_INVALID
        - TANSS_PROXY_TOKEN_MISSING
        - TARGET_TYPE_NOT_VALID_FOR_THIS_SOURCE_TYPE
        - TASK_ASSIGNMENT_NOT_VALID
        - TASK_HAS_NO_ASSIGNMENTS
        - TASK_MUST_GIVE_ASSIGNMENTS
        - TASK_NOT_FOUND_OR_NO_ACCESS
        - TECHNICIAN_CANT_BE_FREELANCER
        - TELEPHONESYSTEMS_CANNOT_CONNECT_TO_DATABASE
        - TELEPHONESYSTEMS_CANNOT_CONNECT_TO_SERVER
        - TELEPHONESYSTEMS_CANNOT_LOAD_DRIVER_CLASS
        - TELEPHONESYSTEMS_IMPORTER_SAVE_TO_DATABASE_ERROR
        - TELEPHONESYSTEMS_PATH_NOT_EXISTING
        - TELEPHONESYSTEMS_RESPONSE_STATUS
        - TEMPLATE_DOESNT_EXIST
        - TEMPLATE_IS_INCLUDED_IN_CHECKLISTS_THAT_ARE_ASSIGNED_TO_TICKETS
        - TEMPLATE_MUST_BE_FROM_ANOTHER_SYSTEM
        - TEMPLATE_MUST_HAVE_A_NAME
        - TEMPLATE_MUST_HAVE_A_SUPPORT_OBJECT
        - TEST
        - TEXT_BELOW_MIN_LENGTH
        - TEXT_CHANGE_MUST_BE_ACCEPTED
        - TEXT_CHAR_IN_BLOCKED_CHARS
        - TEXT_CHAR_NOT_IN_ALLOWED_CHARS
        - TEXT_CONFIG_CONFLICTING_FLAGS
        - TEXT_CONFIG_MIN_GREATER_THAN_MAX
        - TEXT_CONFLICTING_NORMALIZATION_FLAGS
        - TEXT_EXCEEDS_MAX_LENGTH
        - TEXT_FIELD_REQUIRED_BUT_EMPTY
        - TEXT_VALUE_DOES_NOT_MATCH_REGEX
        - TEXT_VALUE_NOT_ALPHANUMERIC
        - TEXT_VALUE_NOT_VALID_EMAIL
        - TEXT_VALUE_NOT_VALID_URL
        - THERE_IS_AN_ERROR_WHILE_LOADING_WIZARD
        - THERE_IS_AN_ERROR_WITH_THIS_WIZARD
        - THE_VALUE_MUST_BE
        - TICKET_CANT_BE_REMOVED_BECAUSE_THIS_IS_THE_LAST_SUPPORT
        - TICKET_HAS_DATA_CONFLICTS
        - TICKET_IS_A_MANDATORY_FIELD
        - TICKET_IS_NOT_A_PROJECT
        - TICKET_LANDING_PAGE_INVALID_MULTISELECT_ID
        - TICKET_LANDING_PAGE_MISSING_WORKFLOW
        - TICKET_LANDING_PAGE_MULTISELECT_COULD_NOT_BE_TRIGGERED
        - TICKET_LANDING_PAGE_MULTISELECT_ID_NOT_FOUND
        - TICKET_LANDING_PAGE_TOKEN_EXPIRED
        - TICKET_LANDING_PAGE_TOKEN_NOT_VALID
        - TICKET_MUST_CONTAIN_ONE_SUPPORT_ENTRY
        - TICKET_NOT_EXISTS
        - TICKET_NOT_FOUND_OR_NO_ACCESS
        - TICKET_STATE_IMAGE_ALREADY_EXISTS
        - TICKET_STATE_IMAGE_IN_USE
        - TICKET_STATE_IMAGE_NOT_FOUND
        - TICKET_STATE_IMAGE_WRONG_DIMENSIONS
        - TICKET_STATE_IMAGE_WRONG_EXTENSION
        - TICKET_STATE_IS_FIXED
        - TILL_DATE_MUST_BE_IN_PAST
        - TIMER_NOTE_HAS_BEEN_CHANGED
        - TIMER_NOT_FOUND_OR_NO_ACCESS
        - TIMESTAMPS_NOT_COMPLETED
        - TIMESTAMP_NOT_FOUND_IN_RULE_CALCULATIONS
        - TIMESTAMP_OUT_OF_BOUNDS
        - TOKEN_COULD_NOT_BE_DELETED
        - TOKEN_ERROR
        - TOKEN_HAS_EXPIRED
        - TOKEN_IS_FOR_OTHER_REMOTE_SUPPORT_API
        - TOKEN_IS_NULL
        - TOO_MANY_ERRORS_WHILE_MOVING_TO_SUB_FOLDERS
        - TOO_MANY_OVERTIME_MINUTES_REQUESTED_FOR_PAYOUT
        - TOO_MANY_OVERTIME_MINUTES_REQUESTED_FOR_SUPPORT
        - TOO_MANY_REQUESTS
        - TRANSFORMING_CONTINUE_STRATEGY_FAILED
        - TRYING_TO_PERSIST_WITHOUT_EXISTING_PARENT
        - TYPE_DOESNT_EXIST
        - TYPE_GREATER_1000
        - TYPE_MUST_BE_GIVEN
        - UNKNOWN_ERROR
        - UPLOADED_FILES_ARE_NULL
        - UPLOADED_FILES_TOO_BIG
        - USER_MUST_BE_LOGGED_IN
        - USE_OF_UNDEFINED_CARD_CONTINUE_TYPE
        - VACATION_CONFIGURATION_MUST_HAVE_A_YEAR_SET
        - VACATION_REQUEST_MUST_HAVE_AT_LEAST_ONE_DAY
        - VALUE_NOT_ALLOWED
        - WEBHOOK_CALL_ERROR
        - WORKFLOW_ALREADY_DONE
        - WORKFLOW_EVENT_MISSING_ITEM
        - WORKFLOW_ITEM_MISSING_OPTIONS
        - WORKFLOW_MISSING_EVENT
        - WORKFLOW_MISSING_TICKET
        - WORKFLOW_RESTART_IS_NOT_ALLOWED
        - WRONG_ENUM_VALUE
        - WRONG_GOOGLE_AUTH_CODE
        - WRONG_ID
        - WRONG_RADIUS_AUTH
        - WRONG_RELATION_STATUS_ID
        - WRONG_TILL_DATE_PARAMETERS
        - WRONG_TIMESTAMP_ORDER
        - WRONG_TYPE
        - YOU_ARE_NOT_THE_CHECKLIST_CREATOR
        - YUBIKEY_VALIDATE_FAILED
        - YUBIKEY_VERIFY_FAILED
        - YUBIKEY_WRONG_AUTH_CODE
        - YUBIKEY_WRONG_RESPONSE
    TnsException:
      type: object
      description: describes an error that occurs in TANSS
      properties:
        text:
          allOf:
            - $ref: '#/components/schemas/TnsErrorCode'
          description: |
            Stable error code (see object). For example `CANT_CHECK_ITEM_TWICE`.
            Use this (not `localizedText`) for programmatic error handling.
          example: CANT_CHECK_ITEM_TWICE
        localizedText:
          type: string
          description: localized error message (currently only in english)
        thrownExceptionMessage:
          type: string
          description: detailled message of a general java exception
        type:
          type: string
          description: name of the TANSS exception
    TicketConfiguration:
      type: object
      description: query paremeters for fetching a custom ticket list
      properties:
        staff:
          type: array
          items:
            type: integer
          description: fetch only tickets assigned to these employees
        notAssignedToEmployees:
          type: array
          items:
            type: integer
          description: don't fetch tickets assigned to these employees
        companies:
          type: array
          items:
            type: integer
          description: fetch only ticket from these companies
        departments:
          type: array
          items:
            type: integer
          description: fetch only ticket assigned to these departments
        isRepair:
          type: boolean
          description: if set, will only fetch repair (or no repair) tickets
        remitterId:
          type: integer
          description: if set, will only fetch tickets of this remitter id
        ids:
          type: array
          items:
            type: integer
          description: fetch only ticket with these ids
        projectId:
          type: integer
          description: fetches only tickets of this project
        phaseId:
          type: integer
          description: fetches only tickets of a given phase id
        includeDoneTickets:
          type: boolean
          description: by deafult, only "open" tickets will be fetched. if "done" tickets shall be fetched as well, this has to be given here
        types:
          type: array
          items:
            type: integer
          description: fetch only ticket with these type ids
        states:
          type: array
          items:
            type: integer
          description: fetch only ticket with these state ids
        itemsPerPage:
          type: integer
          description: Number of tickets that shall be fetched (pagination)
        page:
          type: integer
          description: Page number (pagination)
        modifiedWithinTimeframe:
          type: object
          description: fetch only ticket which were modified in given timeframe
          properties:
            from:
              type: integer
              format: timestamp
              description: Unix timestamp of the "from" date
              example: 1568239200
            to:
              type: integer
              format: timestamp
              description: Unix timestamp of the "to" date
              example: 1568325599
    Ticket-Complete:
      description: ticket model with all fields
      allOf:
        - $ref: '#/components/schemas/Ticket-Standard'
    TnsTagAssignment-TagOnly:
      type: object
      description: represents a tag assignment to a persisted object
      properties:
        id:
          type: integer
          description: id of the tag
          example: 1
    Ticket-Save:
      description: ticket model to be saved
      allOf:
        - $ref: '#/components/schemas/Ticket-Complete'
        - type: object
          properties:
            subTickets:
              type: array
              description: |
                when persisting a project, you can also send a list of sub-tickets here (optional).

                The tickets will immediately be assigned as sub-tickets to the created project.
              items:
                $ref: '#/components/schemas/Ticket-Complete'
            tags:
              type: array
              description: |
                when persisting a ticket, you can also send a list of tag assignments which will be assigned to the ticket
              items:
                $ref: '#/components/schemas/TnsTagAssignment-TagOnly'
    TnsPosting:
      type: object
      properties:
        id:
          type: integer
          description: id of the posting
        date:
          type: integer
          format: timestamp
          description: date when the posting was created (is filled automatically with the current date by the API when creating items)
        employeeId:
          type: integer
          description: id of the author of this posting (is filled automatically with the current logged in user by the API when creating items)
        title:
          type: string
          description: the title of the posting
        content:
          type: string
          description: actual content / text
        internal:
          type: boolean
          description: wether the posting is internal or not
    TnsComment:
      description: Defines a ticket comment
      allOf:
        - $ref: '#/components/schemas/TnsPosting'
        - type: object
          properties:
            commentOfId:
              type: integer
              description: the id of the ticket is given here
    TnsSupport-Small:
      type: object
      properties:
        id:
          type: integer
          description: id of this support
        ticketId:
          type: integer
          description: id of the connected ticket
        date:
          type: integer
          format: timestamp
          description: beginning of the support
        duration:
          type: integer
          description: duration of the service (in minutes)
        location:
          $ref: '#/components/schemas/TnsSupportLocation'
        linkTypeId:
          type: integer
          description: link type of the assignment
        linkId:
          type: integer
          description: id of the assignment
        typeId:
          type: integer
          description: id of the support type
        text:
          type: string
          description: description / text for this support entry
        durationNotCharged:
          type: integer
          description: duration which is not charged (in minutes)
        employeeId:
          type: integer
          description: id of the employee who has done this support
        planningType:
          $ref: '#/components/schemas/TnsPlanningType'
        costCenterId:
          type: integer
          description: id of the cost center
        reasonNotChargedText:
          type: string
          description: if support was not chatged, the reason / text goes here
        reasonNotChargedId:
          type: integer
          description: id of the "not charged reason" (if support was completely not charged)
        reasonPartialNotChargedId:
          type: integer
          description: id of the "not charged reason" (if support was partially not charged)
    TnsSupportClearanceStatus:
      type: string
      description: determines if a support was already "cleared" for billing
      enum:
        - NONE
        - CLEARED
    TnsSupportDriveType:
      type: string
      description: defines which drive type is used
      enum:
        - KM
        - ZONE
    TnsInstallationFeeDriveMode:
      type: string
      description: defines if the drive shall be included in the instalaltion fee
      enum:
        - DRIVE_INCLUDED
        - DRIVE_EXCLUDED
    TnsSupportIconType:
      type: string
      description: determines the icon used to display this support
      enum:
        - STANDARD
        - REMOTE
        - NOT_CHARGED
        - ERP
        - INSTALLATION_FEE
        - FULLSERVICE
        - CONTRACT
        - PREPAID
    TnsSupport:
      description: describes a support entry (same for appointment)
      allOf:
        - $ref: '#/components/schemas/TnsSupport-Small'
        - type: object
          properties:
            orderedViaId:
              type: integer
              description: id of the method, the remitter hat given the order (optional)
            percent:
              type: number
              description: percent that shall be applied
            softwareLicenseId:
              type: integer
              description: if a pc is used as an assignment, a license can be given as well (optional)
            accountingTypeId:
              type: integer
              description: id of the accountingtype used for this support (i.e. "Techniker")
            booked:
              type: boolean
              description: wether the support was already booked
            clearanceStatus:
              $ref: '#/components/schemas/TnsSupportClearanceStatus'
            companyId:
              type: integer
              description: id of the company for this support
            contractId:
              type: integer
              description: id of the contract, used for this support
            taskId:
              type: integer
              description: if support is assigned to a task, use it here
            createdEmployeeId:
              type: integer
              description: id of the employee who has created this support
            departmentId:
              type: integer
              description: if used, id of the department which is assigned to this support
            durationApproach:
              type: integer
              description: duration (in minutes) of the approach (drive)
            driveType:
              $ref: '#/components/schemas/TnsSupportDriveType'
            driveCharged:
              type: boolean
              description: determines if the drive shall be charged or not
            durationApproachCharged:
              type: boolean
              description: false if the duration approach is not charged (should be true by default)
            kmApproach:
              type: integer
              description: km of the approach (drive)
            kmApproachCharged:
              type: boolean
              description: false if the km approach is not charged (should be true by default)
            durationDeparture:
              type: integer
              description: duration (in minutes) of the departure (drive)
            durationDepartureCharged:
              type: boolean
              description: false if the duration departure is not charged (should be true by default)
            kmDeparture:
              type: integer
              description: km of the departure (drive)
            kmDepartureCharged:
              type: boolean
              description: false if the km departure is not charged (should be true by default)
            zoneId:
              type: integer
              description: id of the zone (if zone is used)
            carId:
              type: integer
              description: id of the car (if car is used)
            startBreak:
              type: integer
              format: tiemstamp
              description: timestamp when the pause starts (0 if no pause is given)
            durationBreak:
              type: integer
              description: duration of the pause (in minutes)
            erpNumber:
              type: string
              description: if the support has an erp number entered
            extern:
              type: boolean
              description: if this support was created by a customer login, this value is "true"
            externalTicketId:
              type: string
              description: if the support has an external ticket number entered, this number is given here
            hourlyRate:
              type: number
              format: double
              description: the hourly rate for this support (or the rate per working unit)
            installationFee:
              type: boolean
              description: wether the support will be billed as an "installation fee" with a fixed price
            installationFeeAmount:
              type: number
              format: double
              description: if the support will be billed as an "installation fee", the amount is given here
            installationFeeTypeId:
              type: integer
              description: if the support will be billed as an "installation fee", the id of the installation fee type is given here
            installationFeeDriveMode:
              $ref: '#/components/schemas/TnsInstallationFeeDriveMode'
            internal:
              type: boolean
              description: if this support is marked as "internal" (customers won't see those)
            outlook:
              type: boolean
              description: true, if this support is a TANSS2Ex appointment
            outlookTitle:
              type: string
              description: title for outlook appointments
            outlookLocation:
              type: string
              description: location for outlook appointments
            teamsUrl:
              type: string
              description: if the synced appointment has a teams url, you can specify it here
            supportIconType:
              $ref: '#/components/schemas/TnsSupportIconType'
            textIntern:
              type: string
              description: internal remarks for this support (customers won't see this)
            voucherId:
              type: integer
              description: if the support was already booked and assigned to a voucher, the voucher id is given here
            importType:
              $ref: '#/components/schemas/TnsPlanningType'
            separateBilling:
              type: boolean
              description: true, if this support shall be billed separately
            relationshipLinkTypeId:
              type: integer
              description: if a relationship shall be used, give here the link type of the relationship
            relationshipLinkId:
              type: integer
              description: if a relationship shall be used, give here the link id of the relationship
            serviceLocationId:
              type: integer
              description: if a service location is used, give here the company of the service location
              example: 42
    TnsMailStatus:
      type: string
      description: Status of the mail sending
      enum:
        - UNSENT
        - SENT
        - ERROR
        - RECEIVED
    TnsMailReceiverMethod:
      type: string
      description: Method of the mail receiver (TO / CC / BCC)
      enum:
        - TO
        - CC
        - BCC
    TnsMailReceiver:
      type: object
      description: describes a mail receiver
      properties:
        emailAddress:
          type: string
          description: e-Mail address of the receiver
        name:
          type: string
          description: name of the receiver
        status:
          $ref: '#/components/schemas/TnsMailStatus'
        sentDate:
          type: integer
          format: timestamp
          description: date, when the mail was sent
        method:
          $ref: '#/components/schemas/TnsMailReceiverMethod'
    TnsMail:
      type: object
      description: describes a mail object
      properties:
        id:
          type: integer
          description: id of the mail
        senderId:
          type: integer
          description: id of the mail sender (if a tanss employee could be matches)
        senderName:
          type: string
          description: name of the sender
        senderEmail:
          type: string
          description: e-Mail of the sender
        subject:
          type: string
          description: subject of the mail
        bodyHtml:
          type: string
          description: html body
        bodyPlain:
          type: string
          description: plain body
        plainTextOnly:
          type: boolean
          description: true, if mail was sent "only plain"
        inbound:
          type: boolean
          description: true, if the mail was incoming
        internal:
          type: boolean
          description: true, if the mail is "internal" only
        receivers:
          type: array
          items:
            $ref: '#/components/schemas/TnsMailReceiver'
    Ticket-History:
      type: object
      description: object containing the ticket history
      properties:
        comments:
          description: contains all comments of this ticket
          type: array
          items:
            $ref: '#/components/schemas/TnsComment'
        supports:
          description: contains all supports of this ticket
          type: array
          items:
            $ref: '#/components/schemas/TnsSupport'
        mails:
          description: contains all mails of this ticket
          type: array
          items:
            $ref: '#/components/schemas/TnsMail'
    TnsTicketFile:
      type: object
      description: a document attached to a ticket
      properties:
        id:
          type: integer
          description: id of the document
        ticketId:
          type: integer
          description: id of the assigned ticket
        fileName:
          type: string
          description: original filename of the document
        mimeType:
          type: string
          description: mime type (if given)
        employeeId:
          type: integer
          description: id of the employee who uploaded this document
        date:
          type: integer
          format: timestamp
          description: date when the document was uploaded
        internal:
          type: boolean
          description: true if the document is internal (customers won't see it)
        description:
          type: string
          description: (optional) description of the document
    TnsFilePassResponse:
      type: object
      description: |
        Response for downloading a temporarily created file, which can be downloaded just with a token.

        A file can only be downloaded once, then the token is deleted.
      properties:
        key:
          type: string
          description: key/token of the file
          example: 162D90B4927ACE53E84EE2DA70091E36ECDA29AB
        url:
          type: string
          description: direct url for downloading this file
          example: /api/v1/util/files/162D90B4927ACE53E84EE2DA70091E36ECDA29AB
    TnsTicketImage:
      type: object
      description: an image attached to a ticket
      properties:
        id:
          type: integer
          description: id of the image
        ticketId:
          type: integer
          description: id of the assigned ticket
        fileName:
          type: string
          description: original filename of the image
        employeeId:
          type: integer
          description: id of the employee who uploaded this image
        date:
          type: integer
          format: timestamp
          description: date when the image was uploaded
        internal:
          type: boolean
          description: true if the image is internal (customers won't see it)
        description:
          type: string
          description: (optional) description of the image
        image:
          type: string
          description: base64 encoded string, representing the image data
          example: iVBORw0KGgoAAAANSUhEUgAAAGQAAABLCAYAAACGGCK3AABFmklEQVR42q19BZRlZ5VuJXR1dfl1d3erW+7urdVd7W7p7qTjSkIIhMngg64AM4MMEiAJcRgGFg8JM8AgQR6ugzs8dBj2+759zu2VoTNvMfOotc66fs+5W779bfn/aqqPLcnk6m4pDMxLqjgg
        type:
          type: string
          description: type / extension of the image (i.e. png, jpg)
          example: png
    TnsDataFileEnum:
      description: info representing the upload state
      type: string
      enum:
        - OK
        - TOO_BIG
        - ERROR
        - EMPTY
    TnsDataFile:
      type: object
      description: |
        An object describing an upload file result
      properties:
        name:
          type: string
          description: filename of the uploaded file
          example: example.pdf
        size:
          type: integer
          description: filesize of the uploaded file
          example: 103424234
        mimeType:
          type: string
          description: MIME type of the uploaded file
          example: application/pdf
        status:
          $ref: '#/components/schemas/TnsDataFileEnum'
    TnsTimeframe:
      description: Describes a timeframe (from / to)
      properties:
        from:
          type: integer
          format: timestamp
          description: Unix timestamp of the "from" date
          example: 1568239200
        to:
          type: integer
          format: timestamp
          description: Unix timestamp of the "to" date
          example: 1568325599
    TnsPhoneCallDirection:
      type: string
      description: Defines the "direction" of a phone call
      enum:
        - INTERNAL
        - INCOMING
        - OUTGOING
      example: OUTGOING
    TnsPhoneCallConfiguration:
      type: object
      description: This object is used to get phone calls based on this filter settings
      properties:
        timeframe:
          $ref: '#/components/schemas/TnsTimeframe'
        showTrysAsWell:
          type: boolean
          description: if true, will show "tries" as well, meaning phone calls which didn't have an established connection
        numberFilters:
          type: array
          description: one or more telephone number filters to be applied to the list
          items:
            type: string
          example:
            - 06154/6006-0
            - 06154/123456789-0
        employeeId:
          type: integer
          description: only shows phone calls of a certain employee
          example: 2
        companyId:
          type: integer
          description: only shows phone calls of this company
          example: 100000
        numberInfos:
          type: boolean
          description: if true, then the fields "fromPhoneNrInfos" and "toPhoneNrInfos" will be determined for the calls
        directions:
          type: array
          description: fetches for example only incoming or outgoing calls
          items:
            $ref: '#/components/schemas/TnsPhoneCallDirection'
    TnsPhoneNumberFoundType:
      type: string
      description: Determines how a phone number could be matched
      enum:
        - NONE
        - TOO_SHORT
        - COMPANY
        - EMPLOYEE
        - EMPLOYEE_INACIVE
      example: EMPLOYEE
    TnsPhoneNumberFoundItem:
      type: object
      description: Determines a source of a phone number which could be retrieved from a company or an employee
      properties:
        type:
          $ref: '#/components/schemas/TnsPhoneNumberFoundType'
        id:
          type: integer
          description: id of the company or employee which was found (based on the "type")
          example: 2
        name:
          type: string
          description: a string containing the name of the company or employee
          example: Buchberger, Sven
        active:
          type: boolean
          description: describes if the company or employee is still active
        charsLeftOut:
          type: integer
          description: |
            Describes how many chars were left out while doing the search.
            This could have been the case when searching for companies. In this case, some chars will be left out so that
            number extensions can be searched as well. Example:
            * A company has the phone number 06154/6006-0
            * You search for a number 06154/6006-123
            * The system will try to replace the last 3 chars of the company, so that the number could be found as well,
              because 06154/6006-123 is an extension to 06154/6006-0
        companyId:
          type: integer
          description: When searching for employees, the "main" company id of the employee will be returned as well
          example: 100000
    TnsPhoneNumberIdentifyInfos:
      type: object
      description: This object contains methods of how a phone number could be assigned to a company or employee
      properties:
        foundType:
          $ref: '#/components/schemas/TnsPhoneNumberFoundType'
        items:
          description: all possible matches
          type: array
          items:
            $ref: '#/components/schemas/TnsPhoneNumberFoundItem'
        result:
          $ref: '#/components/schemas/TnsPhoneNumberFoundItem'
    TnsPhoneParticipant:
      type: object
      description: defines a phone participant (technician)
      properties:
        phoneCallId:
          type: integer
          description: Id of the phone call
          example: 1
        idString:
          type: string
          description: |
            Identifier string the phone system uses to represent the participant (=technician). This is used to assign
            a phone call to an employee.
          example: '920'
        employeeId:
          type: integer
          description: |
            Id of the employee, the call is assigned to. The "idString" can be assigned to certain employees.
            If this could be "translated", the actual id will be given here. If storing calls into the database and the
            TANSS employee id is not known, then only the "idString" should be given, and upon creating the call, the system
            will try to "translate" the "idString" into an employee id
          example: 2
    TnsPhoneCall:
      type: object
      description: This object represents a phone call
      properties:
        id:
          type: integer
          description: id of the phone call (in the TANSS database)
          example: 1
        callId:
          type: string
          description: (Optional) Describes the external id of the phone call, which is used by the remote phone system
        telephoneSystemId:
          type: integer
          description: (Optional) If more than one remote phone systems is used, represents the "number" of the phone system
        date:
          type: integer
          format: timestamp
          description: Unix timestamp representing the begin of the phone call
          example: 1514761199
        fromPhoneNumber:
          type: string
          description: Phone number of the caller (= "from" number)
          example: 06154/6006-0
        fromPhoneNrInfos:
          $ref: '#/components/schemas/TnsPhoneNumberIdentifyInfos'
        toPhoneNumber:
          type: string
          description: Phone number of the called (= "to" number)
          example: 06154/123456789-0
        toPhoneNrInfos:
          $ref: '#/components/schemas/TnsPhoneNumberIdentifyInfos'
        direction:
          $ref: '#/components/schemas/TnsPhoneCallDirection'
        connectionEstablished:
          type: boolean
          description: True if a connection was established, otherwise will count as a "try"
        durationTotal:
          type: integer
          description: Total duration of the call (plus ring time) in seconds
          example: 234
        durationCall:
          type: integer
          description: Duration of the call (only time of actual connection) in seconds
          example: 228
        group:
          type: string
          description: (Optional) A group can be assigned to the call (as a string). This is an optional feature.
        phoneParticipants:
          type: array
          items:
            $ref: '#/components/schemas/TnsPhoneParticipant'
    TnsPhoneCall-Identify:
      type: object
      description: Minimal phone call object containing only from/to phone numbers
      properties:
        fromPhoneNumber:
          type: string
          description: Phone number of the caller (= "from" number)
          example: 06154/6006-0
        toPhoneNumber:
          type: string
          description: Phone number of the called (= "to" number)
          example: 06154/123456789-0
    TnsPhoneEmployee:
      type: object
      description: Refers to an assignment between an identifier string (TnsPhoneParticipant.idString) and a TANSS employee id
      properties:
        employeeId:
          type: integer
          description: id of the TANSS employee
          example: 2
        username:
          type: string
          description: identifier string of the TANSS employee
          example: User720
    TnsRemoteMaintenanceConfiguration:
      type: object
      description: This object is used to get remote supports based on filter settings
      properties:
        timeframe:
          $ref: '#/components/schemas/TnsTimeframe'
        employeeId:
          type: integer
          description: only shows remote supports of a certain employee
        companyId:
          type: integer
          description: only shows remote supports of this company
        typeId:
          type: integer
          description: If set, only shows remote supports of this type
        text:
          type: string
          description: text filter for remote supports
    TnsRemoteMaintenance:
      type: object
      description: This object represents a remote support
      properties:
        id:
          type: integer
        remoteMaintenanceId:
          type: string
          description: |
            "Identifier" used by the remote systems to identify this remote support
          example: 643F4G1H1-423HT12-123HGDTRB
        typeId:
          type: integer
          description: |
            "Id" of the external remote support system, which is defined in the TANSS administration ("Externe Fernwartungs-Anbindungen verwalten").
            This field can't be set, as the Api token was created for a specific "type" and this value is fix.
          example: 1001
        userId:
          type: string
          description: |
            "Identifier string" of the technician who has done this remote support. This can be used to "translate" the identifier of the technician
            to a TANSS employee id
          example: Buchberger, Sven
        userName:
          type: string
          description: name of the technician who has done this remote support, this is mainly used for displaying issues
          example: Buchberger, Sven (Softwareentwicklung)
        employeeId:
          type: integer
          description: |
            Id of the technician who has done this remote support (TANSS employee id). This can be omitted if the id is not known
            or the "userId" can be "translated"
        deviceId:
          type: string
          description: |
            "Identifier string" or unique name of the device the remote support was executed for. This can be used via a "translation table" to
            get the company and/or assignment.
          example: DC-2003-01
        deviceName:
          type: string
          description: Simply the name of the device the remote support was executed for. This is mainly used for displying issues.
          example: DC-2003-01 Domänencontroller
        companyId:
          type: integer
          description: id of the company for this remote support
        linkTypeId:
          type: integer
          description: LinkTypeId of the assignment (if known)
        linkId:
          type: integer
          description: LinkId of the assignment (if known)
        startTime:
          type: integer
          format: timestamp
          description: Unix timestamp of the begin for this remote support
          example: 1568289600
        endTime:
          type: integer
          format: timestamp
          description: Unix timestamp of the end for this remote support
          example: 1568291520
        comment:
          type: string
          description: (optional) comment of the remote support
          example: |
            Test-Fernwartung, durchgeführt von Sven mit dem DomänenController.
            Div. Konfigurationen überprüft, Updates installiert.
            Alles OK.
    TnsRemoteMaintenanceDeviceAssignment:
      type: object
      description: |
        Object containing the "translation" of a deviceId based on a remote support "type" to a TANSS company. Optionally,
        a linkTypeId / linkId (assignment) can be given as well, so the system knows exactly to which device the deviceId refers.
      properties:
        deviceId:
          type: string
          description: DeviceId which is transferred in a remote support object
          example: DC-2003-01
        companyId:
          type: integer
          description: Company which this deviceId refers to
          example: 10413
        linkTypeId:
          type: integer
          description: LinkTypeId of the assignment which this deviceId refers to
          example: 1
        linkId:
          type: integer
          description: LinkId of the assignment which this deviceId refers to
          example: 1004
    TnsRemoteMaintenanceDeviceAssignmentId:
      type: object
      description: |
        Identifies a "translation" of a deviceId based on a remote support "type" to a TANSS company.
      properties:
        deviceId:
          type: string
          description: DeviceId which is transferred in a remote support object
          example: DC-2003-01
    TnsRemoteMaintenanceEmployeeAssignment:
      type: object
      description: |
        Object containing the "translation" of a userId based on a remote support "type" to a TANSS employee / technician.
      properties:
        userId:
          type: string
          description: UserId which is transferred in a remote support object
          example: Buchberger, Sven
        employeeId:
          type: integer
          description: Employee id of the TANSS user
          example: 2
    TnsRemoteMaintenanceEmployeeAssignmentId:
      type: object
      description: |
        Identifies a "translation" of a userId based on a remote support "type" to a TANSS employee / technician.
      properties:
        userId:
          type: string
          description: UserId which is transferred in a remote support object
          example: Buchberger, Sven
    TnsMonitoringGroupNameMatching:
      type: object
      description: This object represents a "translation" between a monitoring group name and a specific company (or device)
      properties:
        groupName:
          type: string
          description: |
            name of the monitoring group.
            * You can use wildcards with a "\*" char, i.e. "Server XY -\*" uses all groups starting with "Server XY -"
          example: Server XY - Festplattensensor
        companyId:
          type: integer
          description: id of the company for this monitoring group
          example: 13323
        linkTypeId:
          type: integer
          description: LinkTypeId of the assignment (if known)
          example: 1
        linkId:
          type: integer
          description: LinkId of the assignment (if known)
          example: 1413
    TnsMonitoringGroupNameMatchingId:
      type: object
      description: This object represents a group id for a group assignment
      properties:
        groupName:
          type: string
          description: |
            name of the monitoring group.
          example: Server XY - Festplattensensor
    TnsEmployeeListType:
      type: string
      description: informtation about the "type" of the employee (this info is not always given)
      enum:
        - EMPLOYEE
        - CONTACT_PERSON
        - FREELANCER
        - FREELANCER_CONTACT_PERSON
        - TECHNICIAN
    Employee-Short:
      type: object
      properties:
        id:
          type: integer
          example: 3360
        name:
          type: string
          example: Max Mustermann
        listType:
          $ref: '#/components/schemas/TnsEmployeeListType'
    TnsCompanyType:
      type: object
      description: defines a company type
      properties:
        id:
          type: integer
          description: id of the company type
          example: 41
        name:
          type: string
          description: name of the company type
          example: Region Süd
        categoryId:
          type: integer
          description: id of the category for this type
          example: 2
        categoryName:
          type: string
          description: name of the category for this type
          example: Regionale Gliederung
        icon:
          type: string
          description: if this company type has an icon, here the name is given
          example: region-sued.jpg
        hidden:
          type: boolean
          description: if true, the company type is hidden
    Company-Detail:
      type: object
      properties:
        id:
          type: integer
          description: id of the company
        displayId:
          type: integer
          description: This is the "displayed id" (=Kundennummer) of the company. The id must be unique, a customer nr. could be used multiple times
          example: 100234
        name:
          type: string
          description: name of the company
          example: HUCK IT GmbH
        matchcode:
          type: string
          description: matchcode (used for searching)
          example: HUCK IT GmbH (Zentrale)
        street:
          type: string
          description: street
          example: Am Schatzborn 1
        postcode:
          type: string
          description: postal code
          example: '64380'
        city:
          type: string
          description: city
          example: Roßdorf
        country:
          type: string
          description: country
          example: Deutschland
        note:
          type: string
          description: a note for this company
        headquarterId:
          type: integer
          description: if this company is a subsidiary, then here the id of the "central" / "headquerter" company is given
        email:
          type: string
          description: e-Mail
          example: support@tanss.de
        website:
          type: string
          description: website
          example: https://www.huckit.de
        supportInfo:
          type: string
          description: a support info (internal remark) can be used here
        lockout:
          type: boolean
          description: if true, this company is locked
          example: false
        lockoutReason:
          type: string
          description: if company is locked, a reason can be given here
        inactive:
          type: boolean
          description: If true, the company is inactive
          example: false
        telephone:
          type: string
          description: phone number
          example: 06154/6006-0
        telefax:
          type: string
          description: telefax number
          example: 06154/6006-20
        types:
          type: array
          items:
            $ref: '#/components/schemas/TnsCompanyType'
    Department-Short:
      type: object
      description: Represents a department
      properties:
        id:
          type: integer
        name:
          type: string
          example: Softwareentwicklung
    TnsChecklist-Small:
      description: describes a checklist
      type: object
      properties:
        id:
          type: integer
          description: id of the checklist
        name:
          type: string
          description: name of the checklist
          example: Windows Installation
        description:
          type: string
          description: describes the checklist, i.e. a short info
          example: Beschreibt die Installation von Windows
    TnsChecklistType:
      type: string
      description: defines the type of a checklist
      enum:
        - CHECKLIST
        - TEMPLATE
        - ADHOC
    TnsChecklist:
      description: describes a checklist
      allOf:
        - $ref: '#/components/schemas/TnsChecklist-Small'
        - type: object
          properties:
            id:
              type: integer
              description: id of the checklist
            name:
              type: string
              description: name of the checklist
              example: Windows Installation
            description:
              type: string
              description: describes the checklist, i.e. a short info
              example: Beschreibt die Installation von Windows
            type:
              $ref: '#/components/schemas/TnsChecklistType'
            creatorId:
              type: integer
              description: id of the employee who created this checklist
            predecessorId:
              type: integer
              description: id of the the previous version of the checklist
            active:
              type: boolean
              description: is checklist active?
    TnsChecklistAssignment:
      description: infos regarding as assignment between a checklist and i.e. a ticket
      type: object
      properties:
        rank:
          type: integer
          description: rank (position) of the checklist
        completedByEmployeeId:
          type: integer
          description: if checklist was completed by a process, id of the employee who has completed the checklist is given here
        completedOnDate:
          type: integer
          format: timestamp
          description: if checklist was completed by a process, defines the date (timestamp)
        completedReason:
          type: string
          description: if checklist was completed by a process, a reason (text) could be given in the process event
    TnsChecklist-With-Assignment-Infos:
      description: model used to render tickets in lists
      allOf:
        - $ref: '#/components/schemas/TnsChecklist'
        - type: object
          properties:
            assignmentInfos:
              $ref: '#/components/schemas/TnsChecklistAssignment'
    TimestampState:
      type: string
      description: Determines the state for the timestamp (i.e. on, off)
      enum:
        - 'ON'
        - 'OFF'
        - PAUSE_START
        - PAUSE_END
    TimestampType:
      type: string
      description: Determines the type for the timestamp (i.e. work)
      enum:
        - WORK
        - INHOUSE
        - ERRAND
        - VACATION
        - ILLNESS
        - ABSENCE_PAID
        - ABSENCE_UNPAID
        - OVERTIME
        - DOCUMENTED_SUPPORT
    Timestamp:
      type: object
      properties:
        id:
          type: integer
        employeeId:
          type: integer
          description: id of the employee
        date:
          type: integer
          description: date
          format: timestamp
        state:
          $ref: '#/components/schemas/TimestampState'
        type:
          $ref: '#/components/schemas/TimestampType'
      description: ....
    WeekDay:
      type: string
      description: Enum representing a weekday
      enum:
        - MONDAY
        - TUESDAY
        - WEDNESDAY
        - THRUSDAY
        - FRIDAY
        - SATURDAY
        - SUNDAY
    TimestampPeriodState:
      description: A state representing the Timstamp period
      type: string
      enum:
        - ONGOING
        - COMPLETE
        - PAUSED
    TimestampPeriod:
      description: Describes a timestamp period which begins with an ON (or PAUSE_END) and ends with a OFF (or PAUSE_START) state
      type: object
      properties:
        begin:
          description: begin of period
          type: integer
          format: timestamp
        end:
          description: end of period
          type: integer
          format: timestamp
        seconds:
          description: duration of period (in seconds)
          type: integer
        state:
          $ref: '#/components/schemas/TimestampPeriodState'
    TimestampInfo:
      description: |
        Object containing informations about timestamps grouped by employee and days:
        * a list of timestamp objects
        * infos about the single "periods" of timestamps
        * the working time model of the employee for the given day
      type: object
      properties:
        employeeId:
          type: integer
          description: id of the employee
        date:
          type: string
          format: date
          description: day in the format YYYY-mm-dd
        weekDay:
          $ref: '#/components/schemas/WeekDay'
        workingTimeModelId:
          type: integer
          description: id of the working time model. Infos are stored in the "list properties" - "workingTimeModels" - (ID) - "extras" - "model"
        timestamps:
          description: A list of all timestamps of the given day
          type: array
          items:
            $ref: '#/components/schemas/Timestamp'
        types:
          description: a list of timestamp periods, grouped by the timestamp type. The key is the TimestampType, the value is a list of TimestampPeriods
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TimestampPeriod'
          example:
            WORK:
              begin: 1564489645
              end: 1564497940
              seconds: 8295
              state: PAUSED
    TimestampInfo-With-Changes-Requested:
      description: |
        Object containing informations about timestamps grouped by employee and days:
        * a list of timestamp objects
        * infos about the single "periods" of timestamps
        * the working time model of the employee for the given day
        * requested changes
      allOf:
        - $ref: '#/components/schemas/TimestampInfo'
        - type: object
          properties:
            changesRequested:
              description: if any change requests are present for this user / day, they are given here
              type: array
              items:
                $ref: '#/components/schemas/Timestamp'
    TimestampHistoryType:
      description: |
        describes the "type" of a history entry
      type: string
      enum:
        - CREATED
        - UPDATED
        - DELETED
    TimestampHistory:
      description: Describes a change in a timestamp object
      type: object
      properties:
        id:
          description: id of the history log entry
          type: integer
        timestampId:
          description: id of the timestamp which this history entry is for
          type: integer
        date:
          description: timestamp when the change occured
          type: integer
          format: timestamp
        changeByUserId:
          description: id of the user which did this change
          type: integer
        fromState:
          $ref: '#/components/schemas/TimestampState'
        fromType:
          $ref: '#/components/schemas/TimestampType'
        fromDate:
          type: integer
          format: timestamp
        toState:
          $ref: '#/components/schemas/TimestampState'
        toType:
          $ref: '#/components/schemas/TimestampType'
        toDate:
          description: new timestamp (is 0 if the entry was deleted)
          type: integer
          format: timestamp
        historyType:
          $ref: '#/components/schemas/TimestampHistoryType'
    TimestampDayClosing:
      description: |
        Describes a day closing of a timestamp statistic. Here, all values are persisted into the database with infos
        about working time, vacation, documented supports and the balance for this day.
      type: object
      properties:
        employeeId:
          type: integer
          description: id of the employee for this day closing
        date:
          type: string
          format: date
          description: day for this day closing (YYYY-mm-dd)
        totalTimestampWorkTime:
          type: integer
          description: Number of total minutes of all WORK timstamp periods for this day
        paidAbsences:
          type: integer
          description: Number of total minutes of paid absences (= vacation, illness, overtime and paid absences)
        unpaidAbsences:
          type: integer
          description: Number of total minutes of unpaid absences (= unpaid absences)
        documentedSupport:
          type: integer
          description: Number of total minutes of all documented supportd
        workingTime:
          type: integer
          description: The number of minutes, the employee has to work on this day (based on his working time model)
        workingTimeCleaned:
          type: integer
          description: Subtracts the "workingTime" with the minutes of "paid absences", thus returning the "effective" working time the employee has to work
        totalTime:
          type: integer
          description: Cumulating the "totalTimestampWorkTime", "paidAbsences" and "unpaidAbsences"
        documentedPercentage:
          type: integer
          description: a ration between the documented supports to the "WORK" timestamps
        balance:
          type: integer
          description: returns the effective balance for this account (= totalTime - workingTimeCleaned)
        completedByEmployeeId:
          type: integer
          description: the id of the employee who has approved the day
        completedOnDate:
          type: integer
          format: timestamp
          description: the timestamp, when the employee has approved the day closing
        totalBalance:
          type: integer
          description: the total balance of all previous days accumulated, plus the balance of the current day
        totalBalanceBeforeTimeframe:
          type: integer
          description: the total balance of all previous -not shown- days accumulated
    TimestampEditMode:
      description: |
        describes how a timestamp was (or may be) edited
        * NONE = may not be edited
        * MAY_REQUEST = user may only request changes
        * DIRECT_ACCESS = timestamps may be modified directyl
      type: string
      enum:
        - NONE
        - MAY_REQUEST
        - DIRECT_ACCESS
    TimestampInfo-With-History:
      description: |
        Object containing informations about timestamps grouped by employee and days:
        * a list of timestamp objects
        * infos about the single "periods" of timestamps
        * the working time model of the employee for the given day
        * history of timestamp changes
        * requested changes
      allOf:
        - $ref: '#/components/schemas/TimestampInfo'
        - type: object
          properties:
            history:
              type: array
              items:
                $ref: '#/components/schemas/TimestampHistory'
              description: history of all timestamp changes of this employee / day
              readOnly: true
            dayClosing:
              $ref: '#/components/schemas/TimestampDayClosing'
            editMode:
              $ref: '#/components/schemas/TimestampEditMode'
            changesRequested:
              description: if any change requests are present for this user / day, they are given here
              type: array
              items:
                $ref: '#/components/schemas/Timestamp'
    TimestampDayClosingId:
      description: |
        Describes a unique identifier for the "day closings"
      type: object
      properties:
        employeeId:
          type: integer
          description: id of the employee for this day closing
        date:
          type: string
          format: date
          description: day for this day closing (YYYY-mm-dd)
    TnsMetaMessage-Error:
      type: object
      properties:
        text:
          type: string
          description: error message goes here
    TimestampDayClosingTillDateParameters:
      description: |
        parameters that define, for which employees to which date the day closings shall be created
      type: object
      properties:
        tillDate:
          type: string
          description: date in the format YYYY-MM-DD
          example: '2020-06-17'
        employeeIds:
          type: array
          items:
            type: integer
          example:
            - 2
            - 3
            - 103
    TimestampDayClosingTillDateError:
      description: |
        details on an error that occured while creating multiple day closings
      type: object
      properties:
        employeeId:
          type: integer
          description: id of the employee
        date:
          type: string
          format: date
          description: day when the error occured
        text:
          description: key/identifier of the error message
          type: string
        localizedText:
          description: localized text of the error message
          type: string
    TimestampDayClosingTillDateResult:
      description: |
        response given when creating day closings till a given date
      type: object
      properties:
        createdDayClosings:
          description: a list of created day closing objects
          type: array
          items:
            $ref: '#/components/schemas/TimestampDayClosing'
        errors:
          description: a list of errors that occured while creating the day closings
          type: array
          items:
            $ref: '#/components/schemas/TimestampDayClosingTillDateError'
    TimestampDayClosing-Only-Balance:
      description: |
        Object containing the initial balance (in minutes)
      type: object
      properties:
        balance:
          type: integer
          description: initial balance for this employee (in minutes)
          example: -60
    TimestampPauseConfig:
      description: |
        Defines a configuration for automatical pause subtraction.

        This is needed because longer working periods must contain certain pauses.
      type: object
      properties:
        id:
          type: integer
        fromMinues:
          type: integer
          description: Describes the amount of minutes needed to require a minimum pause (defined in "minimumPause")
          example: 360
        minimumPause:
          type: integer
          description: A working period must contain at least a pause of x minutes
          example: 30
    TnsChatStatus:
      type: string
      description: Enum representing a the state of the chat
      enum:
        - OPEN
        - CLOSED
    TnsChatLoadMessageType:
      type: string
      description: describes if/which messages shall be loaded in a chat list
      enum:
        - NONE
        - ALL
        - LAST
    TnsChatConfiguration:
      type: object
      description: Here, the filter settings for the chat list are stored
      properties:
        employeeId:
          type: integer
          description: filters chats for a given employee id. All chats will be returned to which this employee has access to
        onlyExpectedTimeExpired:
          type: boolean
          description: if true, only open chats with an expired expected time will be shown (overrides "status")
        chatIds:
          type: array
          items:
            type: integer
          description: if a list of specific chat ids shall be used, you can place the here
        status:
          $ref: '#/components/schemas/TnsChatStatus'
        searchString:
          type: string
          description: If chats shall be filtered for a given search text, this text goes here
        linkTypeId:
          type: integer
          description: linkType of assignment
        linkId:
          type: integer
          description: id of assignment
        linkIds:
          type: array
          items:
            type: integer
          description: if multiple assignment ids schall be fetched, you can use an array of integers here
        creatorId:
          type: integer
          description: filters chats from this given chat creator
        showOnlyParticapatedChat:
          type: boolean
          description: |
            if true, only returns chats which the employee is assigned as creator or participant.
            Otherwise returns all chats whith access.
        loadMessages:
          $ref: '#/components/schemas/TnsChatLoadMessageType'
        fillLinkedEntities:
          type: boolean
          description: if true, the "linked entities" will be filled as well (with information regarding employees, tickets etc.)
        minimumCreationDate:
          type: integer
          format: timestamp
          description: only returns chats with at least the given creation date
        itemsPerPage:
          type: integer
          description: if pagination is used, you can enter the number of items per page
        page:
          type: integer
          description: if pagination is used, you can enter the page number here
    TnsChat:
      type: object
      description: TANSS chat
      properties:
        id:
          type: integer
        description:
          type: string
          description: if a general chat (without assignment) is created, a description is needed
        linkTypeId:
          type: integer
          description: linkType of assignment
        linkId:
          type: integer
          description: id of assignment
        status:
          $ref: '#/components/schemas/TnsChatStatus'
        closedByEmployeeId:
          type: integer
          description: id of employee who has closed this chat
        expectedResponseTime:
          type: integer
          format: timestamp
          description: timestamp of an expected response (if chat has an expected response)
        createdByEmployeeId:
          type: integer
          description: id of employee who has created this chat
        creationDate:
          type: integer
          format: timestamp
          description: timestamp of an chat creation
    TnsChatMessage-Create:
      description: chat message object (for persisting)
      type: object
      properties:
        chatId:
          type: integer
          description: id of the corresponding chat id
        content:
          type: string
          description: actual content / message
        expectedResponse:
          type: integer
          description: (optional) number of minutes in which a response is expected
    TnsChatMessage:
      description: chat message object
      allOf:
        - $ref: '#/components/schemas/TnsChatMessage-Create'
        - type: object
          properties:
            id:
              type: integer
              description: id of the chat message
            employeeId:
              type: integer
              description: id of the employee who has sent this message
            creationDate:
              type: integer
              format: timestamp
              description: date when the message was sent
            expectedResponse:
              type: integer
              description: if the message has an expected response time, this is given here (in minutes)
    TnsChatParticipant:
      type: object
      properties:
        chatId:
          type: integer
          description: id of the corresponding chat id
        employeeId:
          type: integer
          description: if the participant is an employee, the id is given here
        departmentId:
          type: integer
          description: if the participant is an department, the id is given here
    TnsChatLogType:
      type: string
      description: Enum representing a chat log type
      enum:
        - CLOSED
        - REOPENED
        - ADDED_EMPLOYEE
        - ADDED_DEPARTMENT
        - REMOVED_EMPLOYEE
        - REMOVED_DEPARTMENT
        - REQUESTED_CLOSING
        - DECLINED_CLOSING
    TnsChatLog:
      type: object
      properties:
        id:
          type: integer
          description: id of the chat log
        chatId:
          type: integer
          description: id of the corresponding chat id
        employeeId:
          type: integer
          description: id of the user who has done this action
        date:
          type: integer
          format: timestamp
          description: date and time of this log entry
        type:
          $ref: '#/components/schemas/TnsChatLogType'
        info:
          type: string
          description: |
            info to this log entry. For example if the type was "ADDED_EMPLOYEE", then the employee id is stored here
    TnsChat-Detail:
      description: TANSS chat (including info regarding messages, participants, logs)
      allOf:
        - $ref: '#/components/schemas/TnsChat'
        - type: object
          properties:
            messages:
              type: array
              items:
                $ref: '#/components/schemas/TnsChatMessage'
            participants:
              type: array
              items:
                $ref: '#/components/schemas/TnsChatParticipant'
            logs:
              type: array
              items:
                $ref: '#/components/schemas/TnsChatLog'
    TnsChatCloseAcceptDeclineResponse:
      type: object
      description: response when accepting or declining a close request
      properties:
        status:
          type: string
          description: Enum representing a the final closing state of a chat
          enum:
            - CLOSED
            - CLOSE_DECLINED
    TnsChatCloseResponse:
      type: object
      description: response when trying to close a chat
      properties:
        status:
          type: string
          description: Enum representing a the closing state of a chat
          enum:
            - CLOSED
            - CLOSE_REQUESTED
    TnsChatReOpenResponse:
      type: object
      description: response when trying to re-open a chat
      properties:
        status:
          type: string
          description: Enum representing a the opening state of a chat
          enum:
            - OPEN
    TnsOfferErpSelectionMaterialSource:
      type: string
      description: |
        determines the "source" for this material selection (either TANSS or MENTION).

        "articleId" determines the id of the material
      enum:
        - TANSS
        - MENTION
    TnsOfferErpSelectionMaterialType:
      type: string
      description: (not implemented yet, but a type can be used to determined the "type" of a material)
      enum:
        - DEFAULT
        - YES_NO
        - FLOAT
    TnsOfferErpSelectionMaterial:
      type: object
      description: This object represents a single source of material, which is used in erp selections
      properties:
        id:
          type: integer
          description: id of the erp selection material
        erpSelectionId:
          type: integer
          description: id of the associated erp selection
        source:
          $ref: '#/components/schemas/TnsOfferErpSelectionMaterialSource'
        articleId:
          type: string
          description: |
            determines the "id" of the material.
            * if the source TANSS is used, this represents the id of the TANSS material
            * if the source MENTION is used, this represents the id of the MENTION material
          example: '19'
        pos:
          type: integer
          description: position of this material.
          example: 1
        type:
          $ref: '#/components/schemas/TnsOfferErpSelectionMaterialType'
    TnsMaterial:
      type: object
      description: This object represents a TANSS material entry
      properties:
        id:
          type: integer
          description: id of this material
          example: 17
        articleNumber:
          type: string
          description: article number of this material
          example: ART12345
        label:
          type: string
          description: laben / name of this material
          example: Logitech Maus XYZ
        serialNumber:
          type: string
          description: serial number
        price:
          type: number
          description: price for this material
          example: 17.45
        remark:
          type: string
          description: addition text / remark for this material
          example: Maus für höchste Ansprüche
    TnsOfferErpSelectionMaterial-With-Material:
      description: This object represents a single source of material, which is used in erp selections (inlcuding attached material infos)
      allOf:
        - $ref: '#/components/schemas/TnsOfferErpSelectionMaterial'
        - type: object
          properties:
            material:
              $ref: '#/components/schemas/TnsMaterial'
    TnsOfferErpSelection:
      type: object
      description: This object represents an "erp selection" profile to be used in offer templates
      properties:
        id:
          type: integer
          description: id of the erp selection
        variableName:
          type: string
          description: |
            variable name of the erp selection.

            This name is used in the offer template within the {ERP:...} syntax
          example: erpAuswahl
        prompt:
          type: string
          description: This prompt will be shown when a user shall specify some material within an offer.
          example: Bitte geben Sie an, welches Material verwendet wird
        mats:
          type: array
          items:
            $ref: '#/components/schemas/TnsOfferErpSelectionMaterial-With-Material'
    TnsOfferTemplate:
      type: object
      description: Describes an offer template
      properties:
        id:
          type: integer
          description: id of the offer template
          example: 1
        name:
          type: string
          description: name of the offer template
          example: Angebots-Vorlage für TANSS-Angebote
        creationDate:
          type: integer
          format: timestamp
          description: timestamp of the creation of this offer template
          example: 1573479013
        createdByEmployeeId:
          type: integer
          description: id of the employee who has created this offer template
          example: 2
        previousId:
          type: integer
          description: if the offer template is a "newer" version of another template, the old template (pervious id) goes here
        validInDays:
          type: integer
          description: you can define here how long (in days) a generated offer will be valid
    TnsOfferTemplate-Details:
      description: Describes an offer template, including attached erp selections
      allOf:
        - $ref: '#/components/schemas/TnsOfferTemplate'
        - type: object
          properties:
            erpSelections:
              type: array
              items:
                $ref: '#/components/schemas/TnsOfferErpSelection'
    TnsChecklistItemVarType:
      description: defines the type of a checklist variable
      type: string
      enum:
        - INPUT
        - MULTISELECT
        - PASSWORD
        - OUTPUT
        - ERP_SELECTION
      example: MULTISELECT
    TnsChecklistItemVar:
      type: object
      description: This object represents a type of a checklist variable
      properties:
        name:
          type: string
          description: name of the variable
          example: Variablen-Name
        type:
          $ref: '#/components/schemas/TnsChecklistItemVarType'
        options:
          description: this fields is only set on MULTISELECT varaibles and contains all selectable options
          type: array
          items:
            type: string
          example:
            - Option 1
            - Option 2
    TnsOfferTemplate-Vars:
      description: Describes an offer template, including attached erp selections and processed vars
      allOf:
        - $ref: '#/components/schemas/TnsOfferTemplate-Details'
        - type: object
          properties:
            vars:
              type: array
              items:
                $ref: '#/components/schemas/TnsChecklistItemVar'
    TnsMaterial-With-Source:
      description: This object represents a TANSS material entry, including the "source" of the material (TANSS / MENTION)
      allOf:
        - $ref: '#/components/schemas/TnsMaterial'
        - type: object
          properties:
            source:
              $ref: '#/components/schemas/TnsOfferErpSelectionMaterialSource'
    TnsOfferConfiguration:
      type: object
      description: Filter, which offers shall be loaded
      properties:
        companyId:
          type: integer
          description: if only offers from one company shall be fetched, give the company id here
        onlyValid:
          type: boolean
          description: if true, only offers with a valid "validTill" shall be given
        templateId:
          type: integer
          description: only returns offers from this template
    TnsOffer:
      description: Describes an offer
      type: object
      properties:
        id:
          type: integer
          description: id of the offer
        name:
          type: string
          description: name of the offer
          example: Angebot für TANSS
        date:
          type: integer
          description: creation date of this offer
          format: timestamp
          example: 1573479013
        createdByEmployeeId:
          type: integer
          description: id othe employee who has created this offer
        linkTypeId:
          type: integer
          description: link type of the offer assignment
        linkId:
          type: integer
          description: id of the offer assignment
        validTill:
          type: integer
          description: date which the offer expires
          format: timestamp
          example: 1575154800
    TnsWorkflowContractState:
      type: string
      description: describes the state of a workflow
      enum:
        - CREATED
        - REQUEST_SENT
        - REQUEST_SEND_ERROR
        - LANDING_PAGE_1_OPENED
        - CONTRACT_REQUESTED
        - LANDING_PAGE_2_OPENED
        - CONTRACT_DECLINED
        - CONTRACT_CANCELLED
        - CONTRACT_AVAILABLE
        - CONTRACT_UPLOADED_MANUALLY
        - STATE_SET_MANUALLY
    TnsWorkflowContract:
      type: object
      description: describes a workflow contract
      properties:
        id:
          type: integer
          description: id of this workflow
        companyId:
          type: integer
          description: id of the company for this workflow
        date:
          type: integer
          format: timestamp
          description: date, when the workflow was started
          example: 1573833600
        state:
          $ref: '#/components/schemas/TnsWorkflowContractState'
    TnsWorkflowContractTokenType:
      type: string
      description: describes the type of a token
      enum:
        - LANDING_PAGE_1
        - LANDING_PAGE_2
    TnsWorkflowContractToken:
      type: object
      properties:
        id:
          type: integer
          description: id of this token
        date:
          type: integer
          format: timestamp
          description: date, when the token was generated
          example: 1573833600
        expires:
          type: integer
          format: timestamp
          description: date, when the token will expire
          example: 1574833600
        type:
          $ref: '#/components/schemas/TnsWorkflowContractTokenType'
    TnsWorkflowContract-With-Tokens:
      description: describes a workflow contract, including the hashes
      allOf:
        - $ref: '#/components/schemas/TnsWorkflowContract'
        - type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TnsWorkflowContractToken'
    TnsOffer-List:
      description: Describes an offer, may include workflows as well
      allOf:
        - $ref: '#/components/schemas/TnsOffer'
        - type: object
          properties:
            workflows:
              type: array
              items:
                $ref: '#/components/schemas/TnsWorkflowContract-With-Tokens'
    TnsOfferVariable:
      type: object
      description: Describes a variable for an offer
      properties:
        offerId:
          type: integer
          description: id of the offer
        variableName:
          type: string
          description: name of the variable which is used in the offer template
          example: anrede
        content:
          type: string
          description: content of the variable
          example: Sehr geehrte Damen und Herren
    TnsOfferMaterial:
      type: object
      description: Describes a material which is used in an offer
      properties:
        id:
          type: integer
          description: id of the offer material
        offerId:
          type: integer
          description: id of the associated offer
        pos:
          type: integer
          description: position of the material in the offer
          example: 1
        erpSelectionId:
          type: integer
          description: id of the corresponding erp selection for this material
        erpSelectionMaterialId:
          type: integer
          description: id of the corresponding erp selection material for this material
        amount:
          type: number
          format: float
          description: amount for this material
          example: 1
        articleNr:
          type: string
          description: article number (optional)
        label:
          type: string
          description: label / name for this material
        remark:
          type: string
          description: remark for this material (optional text)
        price:
          type: number
          format: float
          description: single price for this material
          example: 1090
        discount:
          type: number
          format: float
          description: discount for this material (optional)
    TnsOffer-Details:
      description: Describes an offer, including variables and material
      allOf:
        - $ref: '#/components/schemas/TnsOffer'
        - type: object
          properties:
            vars:
              type: array
              items:
                $ref: '#/components/schemas/TnsOfferVariable'
            mats:
              type: array
              items:
                $ref: '#/components/schemas/TnsOfferMaterial'
    TnsAvailability:
      type: object
      description: Representing the current "employee state", which can be set in TANSS
      properties:
        date:
          type: integer
          format: timestamp
          description: date when this state was set
          example: 1573833600
        employeeId:
          type: integer
          description: id of employee
          example: 2
        typeId:
          type: integer
          description: id of availability type
          example: 1
        host:
          type: string
          description: hostname which set this state
          example: 127.0.0.1
    TnsVacationEndTimeType:
      type: string
      description: specifies, when an absence will end (in word TODAY, TOMORROW or TIME). The frontend can then render the result in a better way
      enum:
        - TIME
        - TODAY
        - TOMORROW
      example: TODAY
    TnsVacationEndInfo:
      type: object
      description: informations regarding an "end time" for a absence
      properties:
        timeType:
          $ref: '#/components/schemas/TnsVacationEndTimeType'
        time:
          type: integer
          format: timestamp
          description: timestamp, when the vacation/absence will end
          example: 1573833600
    TnsAvailabilityInfo:
      type: object
      properties:
        employeeId:
          type: integer
          description: id of the employee
        availability:
          $ref: '#/components/schemas/TnsAvailability'
        absences:
          type: array
          description: list of absenced the employee has right now
          items:
            $ref: '#/components/schemas/TnsSupport-Small'
        appointments:
          type: array
          description: list of appointments the employee has right now
          items:
            $ref: '#/components/schemas/TnsSupport-Small'
        endInfos:
          type: object
          description: |
            specific informations about absences, when they will end.

            They key ist the id of the absence, the value is an info object regarding infos
          additionalProperties:
            $ref: '#/components/schemas/TnsVacationEndInfo'
          example:
            '1':
              timeType: TODAY
              time: 1573833600
    TnsMailTransportSecurityType:
      type: string
      description: enum representing the security setting of the mail server
      enum:
        - NONE
        - SSL
        - TLS
    TnsEmailSettings-Smtp:
      type: object
      description: configuration of smtp server settings (for sending mails)
      properties:
        smtpAddress:
          type: string
          description: e-mail address for sending e-mails
        smtpHost:
          type: string
          description: host (address) of the smtp server
        smtpUser:
          type: string
          description: username of the smtp server
        smtpPassword:
          type: string
          description: password of the smtp server
        smtpAuth:
          type: boolean
          description: true if the smtp server requires authentication
        smtpEncryptionType:
          $ref: '#/components/schemas/TnsMailTransportSecurityType'
        smtpSenderName:
          type: string
          description: send mails with this displayed name (optional)
    TnsTagAssignment:
      type: object
      description: represents a tag assigned to an assignment (ticket, pc, server)
      properties:
        tagId:
          type: integer
          description: id of the tag
          example: 1
        linkTypeId:
          type: integer
          description: linkType of the assignment
          example: 11
        linkId:
          type: integer
          description: id of the assignment
          example: 123456
    TnsTag-Without-GroupTag:
      type: object
      description: represents a tag
      properties:
        id:
          type: integer
        name:
          type: string
          description: name of the tag
          example: Störung
        backgroundColor:
          type: string
          description: background color of the tag (in hex, for example FF0000 - max. 6 chars!)
          example: FF0000
        fontColor:
          type: string
          description: font color of the tag (in hex, for example FF0000 - max. 6 chars!)
          example: FF0000
        description:
          type: string
          description: description of the tag (optional)
          example: System-Störung
        image:
          type: string
          description: name of image (optional)
        groupTagId:
          type: integer
          description: id of the group tag
        groupTagInheritance:
          type: boolean
          description: inherit visibilities from group tag
        isGroupParent:
          type: boolean
          description: is the tag a parent for other tags
        visibilities:
          type: array
          description: visibility assignments (departments, employees, company categories, ticket types)
          items:
            $ref: '#/components/schemas/TnsTagAssignment'
    TnsTag:
      description: represents a tag
      allOf:
        - $ref: '#/components/schemas/TnsTag-Without-GroupTag'
        - type: object
          properties:
            groupTag:
              $ref: '#/components/schemas/TnsTag-Without-GroupTag'
    TnsTagLogType:
      type: string
      enum:
        - TAG_ASSIGNED
        - TAG_REMOVED
    TnsTagLog:
      type: object
      description: tag log entry (assign or removal)
      properties:
        id:
          type: integer
        date:
          type: integer
          format: timestamp
          description: date of the log entry
          example: 1574938865
        employeeId:
          type: integer
          description: employee who has done the log entry
          example: 2
        logType:
          $ref: '#/components/schemas/TnsTagLogType'
        linkTypeId:
          type: integer
          description: linkType of the assignment
          example: 11
        linkId:
          type: integer
          description: id of the assignment
          example: 123456
    TnsCallbackState:
      description: Describes a current "state" of a callback
      type: string
      enum:
        - UNSEEN
        - NEW
        - NOBODY_ANSWERED
        - BUSY
        - NOT_PRESENT
        - NEW_CALLBACK_REENTERED
        - COMPLETED
        - EXPECTED_CALLBACK
        - EXPECTED_CALLBACK_COMPLETED
    TnsCallbackConfiguration:
      type: object
      description: filter settings for retrieving callbacks
      properties:
        timeframe:
          $ref: '#/components/schemas/TnsTimeframe'
        state:
          $ref: '#/components/schemas/TnsCallbackState'
        states:
          type: array
          description: if multiple states have to be filtered, give an array here
          items:
            $ref: '#/components/schemas/TnsCallbackState'
        fromEmployeeId:
          type: integer
          description: filters only callbacks which were created by this employee (technician)
        toEmployeeId:
          type: integer
          description: filters only callbacks to this employee (techncian)
        toAllEmployeesWithAccessTo:
          type: boolean
          description: if "toEmployeeId" is given, also retrieves all callbacks which the user has access to
        toDepartmentIds:
          type: integer
          description: filters only callbacks for these departments
        companyIds:
          type: integer
          description: filters only callbacks for these (customer) companies (ids given here)
        employeeIds:
          type: integer
          description: filters only callbacks for these (customer) employees (ids given here)
        loadLinkedEntites:
          type: boolean
          description: if true, "linked entities" will be loaded as well (given in the responses "meta" section)
        withLog:
          type: boolean
          description: if true, will also load all state logs of the retrieved callbacks
        itemsPerPage:
          type: integer
          description: if pagination shall be used, give here the items per page
        page:
          type: integer
          description: if pagination shall be used, the page number is given here
    TnsCallback:
      type: object
      description: Defines a callback
      properties:
        fromEmployeeId:
          type: integer
          description: Defines the employee who entered the callback
          example: 2
        toEmployeeId:
          type: integer
          description: The callback is assigned to this employee (This person has to do the call)
          example: 1234
        toDepartmentId:
          type: integer
          description: Callbacks can be assigned to a special department. Every employee of this department sees the callback.
        date:
          type: integer
          format: timestamp
          description: The callback was created on this date
          example: 1576234800
        companyId:
          type: integer
          description: Here, the id of the company is given which has to be called back
          example: 100000
        companyName:
          type: string
          description: same as "companyId", but here a string can be given (i.e. if the company wasn't created yet in TANSS)
          example: HUCK IT GmbH
        employeeId:
          type: integer
          description: Here, the id of the employee is given (who has to be called back)
        employeeName:
          type: string
          description: same as "employeeId", but here a string can be given (i.e. if the employee wasn't created yet in TANSS)
          example: Hans Mustermann
        phoneNumber:
          type: string
          description: You must define the phone number here
          example: 06154/6006-0
        info:
          type: string
          description: (Optional) Further information regarding the callback
          example: Kunde wünscht dringen Rückruf auf dem Handy!
        state:
          $ref: '#/components/schemas/TnsCallbackState'
        priority:
          type: integer
          description: priority of the callback from 1 (lowest) to 9 (highest)
        callbackAfterTime:
          type: integer
          format: timestamp
          description: If the callback has to be "later" than a specific time, give here the minimum date for the callback
        callbackUntilTime:
          type: integer
          format: timestamp
          description: If the callback has to be processed before a given date, specify this "latest" date here
        linkTypeId:
          type: integer
          description: If the callback is assigned to a ticket (or other assignment), linkType is given here
          example: 11
        linkId:
          type: integer
          description: If the callback is assigned to a ticket (or other assignment), the id is given here
          example: 12345
    TnsCallbackStateLog:
      description: Describes a state change of a callback
      type: object
      properties:
        date:
          type: integer
          format: timestamp
          description: Timestamp of this log entry
        state:
          $ref: '#/components/schemas/TnsCallbackState'
        infoText:
          type: string
          description: If a info was given, it will be shown here
        employeeId:
          type: integer
          description: This employee has done the state change
    TnsCallback-With-Log:
      description: ticket model with all fields
      allOf:
        - $ref: '#/components/schemas/TnsCallback'
        - type: object
          properties:
            stateLog:
              type: array
              items:
                $ref: '#/components/schemas/TnsCallbackStateLog'
    TnsSearchArea:
      type: string
      description: defines the area where to search in
      enum:
        - COMPANY
        - EMPLOYEE
        - TICKET
    TnsAreaSearchConfiguration:
      type: object
      properties:
        maxResults:
          type: integer
          description: maximum number of companies to fetch. If value is omitted (null), then 100 max. results are used
    TnsCompanySearchConfiguration:
      allOf:
        - $ref: '#/components/schemas/TnsAreaSearchConfiguration'
        - type: object
          description: parameters which specify the company search
    TnsEmployeeSearchConfiguration:
      allOf:
        - $ref: '#/components/schemas/TnsAreaSearchConfiguration'
        - type: object
          description: parameters which specify the employee search
          properties:
            companyId:
              type: integer
              description: if only is to be searched in one company
            inactive:
              type: boolean
              description: if false, inactive users won't be fetched (default = true)
            categories:
              type: boolean
              description: if true, categories will be fetches as well. The names are given in the "linked entities" - "employeeCategories" (default = false)
            callbacks:
              type: boolean
              description: if true, expected callbacks will be fetched as well (default = false)
    TnsTicketSearchConfiguration:
      allOf:
        - $ref: '#/components/schemas/TnsAreaSearchConfiguration'
        - type: object
          description: parameters which specify the ticket search
          properties:
            previewContentMaxChars:
              type: integer
              description: if defined, overrides the to preview the content (default values is 60)
            companyId:
              type: integer
              description: if only is to be searched in one company
    TnsSearchAreaConfiguration:
      type: object
      description: here, some specific search parameters can be overridden
      properties:
        company:
          $ref: '#/components/schemas/TnsCompanySearchConfiguration'
        employee:
          $ref: '#/components/schemas/TnsEmployeeSearchConfiguration'
        ticket:
          $ref: '#/components/schemas/TnsTicketSearchConfiguration'
    TnsSearchConfiguration:
      type: object
      description: object representing a definition for searching in misc. areas
      properties:
        areas:
          type: array
          description: describes in which areas to search
          items:
            $ref: '#/components/schemas/TnsSearchArea'
        query:
          type: string
          description: the query string
        configs:
          $ref: '#/components/schemas/TnsSearchAreaConfiguration'
    TnsCompanyCentralType:
      type: string
      description: defines, if a company is a central, or a branch (or none of it)
      enum:
        - NONE
        - CENTRAL
        - BRANCH
    TnsAnticipatedCallbackSearchResult:
      type: object
      description: gives infos about anticipated callbacks in company search results
      properties:
        fromEmployeeId:
          type: integer
          description: id of the employee who waits for this callback
          example: 2
        phoneNumber:
          type: string
          description: phone number of this callback
          example: 06154/6006-77
        date:
          type: integer
          format: timestamp
          description: date when the anticipated callback was entered
          example: 1575551949
    TnsCompanySearchResult:
      type: object
      description: object containing a found company with all associated infos
      properties:
        id:
          type: integer
          description: id fo the company
          example: 100001
        name:
          type: string
          description: name of the company
          example: HUCK IT GmbH
        street:
          type: string
          description: street of the company
          example: Am Schatzborn 1
        postCode:
          type: string
          description: postal code of the company
          example: '64380'
        city:
          type: string
          description: city of the company
          example: Roßdorf
        country:
          type: string
          description: country of the company
          example: Deutschland
        displayId:
          type: string
          description: display if (customer nr.)
          example: HIT-1000001
        phoneNumber:
          type: string
          description: phone number
          example: 06154/6006-0
        faxNumber:
          type: string
          description: fax number
          example: 06154/6006-20
        email:
          type: string
          description: e-Mail of the company
          example: kontakt@huckit.de
        website:
          type: string
          description: website of the company
          example: https://www.huckit.de
        inactive:
          type: boolean
          description: if the company is incative, info is given here
        lockout:
          type: boolean
          description: defines, if the company is locked (n service may be entered)
        centralType:
          $ref: '#/components/schemas/TnsCompanyCentralType'
        personalCustomer:
          type: boolean
          description: defines if the company is a "private customer"
        mobileNumber:
          type: string
          description: mobile phone number (only if its a private customer)
        privateNumber:
          type: string
          description: private phone number (only if its a private customer)
        types:
          type: array
          items:
            $ref: '#/components/schemas/TnsCompanyType'
        anticipatedCallbacks:
          type: array
          items:
            $ref: '#/components/schemas/TnsAnticipatedCallbackSearchResult'
    TnsEmployeeSearchResult:
      type: object
      description: object containing a found employee with all associated infos
      properties:
        id:
          type: string
          description: id of the employee
          example: '2'
        name:
          type: string
          description: full (displayed) name
          example: Mustermann, Hans
        firstName:
          type: string
          description: first name
          example: Hans
        lastName:
          type: string
          description: last name
          example: Mustermann
        departmentId:
          type: string
          description: department id of the employee, the name is given in the "linked entities"
          example: '2'
        role:
          type: string
          description: role of the employee
          example: Sachbearbeiter
        phoneNr:
          type: string
          description: phone number
          example: 06154/6006-123
        phoneNr2:
          type: string
          description: phone number
        email:
          type: string
          description: email
          example: hans@huckit.de
        mobileNr:
          type: string
          description: mobile phone number
        mobileNr2:
          type: string
          description: mobile phone number
        privateNr:
          type: string
          description: private phone number
        companies:
          type: array
          description: shows assigned companies of this user, the name is given in the "linked entities"
          items:
            type: integer
          example:
            - 100000
            - 100001
        active:
          type: boolean
          description: determines wether an employee is active or not
        anticipatedCallbacks:
          type: array
          items:
            $ref: '#/components/schemas/TnsAnticipatedCallbackSearchResult'
        categories:
          description: ids of all employee categories (if defined in the employee search configuration). The names are given in the "linked entities" - "employeeCategories"
          type: array
          items:
            type: integer
    TnsTicketSearchResult:
      type: object
      description: object containing a found ticket with all associated infos
      properties:
        id:
          type: string
          description: id of the ticket
          example: '10345'
        title:
          type: string
          description: title of the ticket
          example: Server Störung
        content:
          type: string
          description: content of the ticket. This is cut by the number of "previewContentMaxChars" as defined in the dearch config
          example: Versucht, den Server neuzustarten, doch es ...
        statusId:
          type: integer
          description: status id, name is given in the "linked entities"
          example: 2
        companyId:
          type: integer
          description: id of the company, name is given in the "linked entities"
          example: 100000
        assignedToEmployeeId:
          type: integer
          description: assigned to employee id, name is given in the "linked entities"
          example: 2
        assignedToDepartmentId:
          type: integer
          description: assigned to department id, name is given in the "linked entities"
        extTicketId:
          type: string
          description: the external ticket id (if given)
    TnsSearchResult:
      type: object
      description: object representing the search results
      properties:
        companies:
          type: array
          items:
            $ref: '#/components/schemas/TnsCompanySearchResult'
        employees:
          type: array
          items:
            $ref: '#/components/schemas/TnsEmployeeSearchResult'
        tickets:
          type: array
          items:
            $ref: '#/components/schemas/TnsTicketSearchResult'
    TnsChecklistItemType:
      type: string
      description: defines the type of a checklist item
      enum:
        - TEXT_FIELD
        - REQUIRED_FIELD
        - OPTIONAL_FIELD
        - INCLUDED_CHECKLIST
        - REQUIRED_TEXT_FIELD
        - OPTIONAL_TEXT_FIELD
        - REQUIRED_MULTISELECT
        - OPTIONAL_MULTISELECT
        - EVENT_CONTAINER
        - APPROVAL_PROCESS
    TnsChecklistAction:
      type: object
      description: describes the "state" of a checklist item, i.e. if it's checked
      properties:
        value:
          type: integer
          description: 1 = checked / 0 = not checked
        date:
          type: integer
          description: date, when the action took place
        userId:
          type: integer
          description: id of the user who checked this field
        supportId:
          type: integer
          description: if a support was created, while this item was check, the id is given here (which contains the sevice text for this item)
    TnsChecklistItem:
      description: represents an item in a checklist
      type: object
      properties:
        id:
          type: integer
          description: id of the item
        checklistId:
          type: integer
          description: id of the checklist, which the item is contained in
        type:
          $ref: '#/components/schemas/TnsChecklistItemType'
        heading:
          type: string
          description: headinh / title of the checklist item
        description:
          type: string
          description: description / text of the checklist item
        entryPoint:
          type: boolean
          description: true if this is the first item of a checklist
        nextItemId:
          type: integer
          description: id of the "next" field in the process chain
        serviceText:
          type: string
          description: text which is used when creating a support
        hidden:
          type: boolean
          description: true if thes field is hidden
        action:
          $ref: '#/components/schemas/TnsChecklistAction'
        vars:
          type: array
          description: if vars were used in teh text, these must be given in the "check" body to fill in the correct values / infos for checking the item
          items:
            $ref: '#/components/schemas/TnsChecklistItemVar'
    TnsChecklist-With-Process-Infos:
      description: detailled infos for the checklist, with all values (checked items, history, vars atc.)
      allOf:
        - $ref: '#/components/schemas/TnsChecklist'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/TnsChecklistItem'
    TnsChecklistItemCheckBody:
      type: object
      description: infos required for checking an item in a checklist
      properties:
        itemId:
          type: integer
          description: id of the checlist item that will be checked
        checklistId:
          type: integer
          description: id of the checklist which this item is in
        mainChecklistId:
          type: integer
          description: if the item is part of an "included" checklist, you must specify the "main" checklist as well
        linkTypeId:
          type: integer
          description: linktype of the assignment (i.e. 11 for ticket)
        linkId:
          type: integer
          description: link id of the assignment (if assigned to a ticket then the ticket id goes here)
        value:
          type: integer
          description: 1 = check / 0 = uncheck
        multiSelectId:
          type: integer
          description: if an multiselect option is checked, give the multiselect option id here
        vars:
          type: object
          description: if vars are needed for checking this field, then give these here
          additionalProperties:
            type: string
          example:
            var1: Eingegebener Text
            var2: Noch ein Text für eine Variable
    TnsInternalSupportFilter:
      type: string
      description: determines which filter for "internal support" shall be used
      enum:
        - ALL
        - ONLY_INTERNAL
        - ONLY_EXTERNAL
    LogicOperatorType:
      type: string
      description: Enum representing the logic linking of certain ids (AND / NOT / OR)
      enum:
        - AND
        - OR
        - NOT
    TnsDiscountedSupportTypeFilter:
      type: string
      description: determines which filter for "discounted" supports shall be used
      enum:
        - ALL
        - ONLY_WITH_ADDITION
        - ONLY_WITH_DISCOUNT
        - ONLY_WITH_ZERO_PERCENT
    TnsOpenTicketsFilter:
      type: string
      description: determines wether supports from open tickets shall be fecthed or not
      enum:
        - SUPPORTS_FROM_ALL_TICKETS
        - SUPPORTS_FROM_OPEN_TICKETS
        - SUPPORTS_FROM_CLOSED_TICKETS
        - ALL_SUPPORTS_BUT_OPEN_TICKETS
    TnsSupportTaskFilter:
      type: string
      description: determines wether supports from tasks shall be fetched as well
      enum:
        - ONLY_TASK_SUPPORTS
        - NO_TASK_SUPPORTS
    TnsSupportConfiguration:
      description: |
        object containing support list query parameters.

        When querying support with these parameters, you can only use the filter settings you need (You don't have to specify all)
      type: object
      properties:
        timeframe:
          $ref: '#/components/schemas/TnsTimeframe'
        supportLocations:
          description: show only supports from these support locations
          type: array
          items:
            $ref: '#/components/schemas/TnsSupportLocation'
        supportIconTypes:
          description: show only supports with these support icon types
          type: array
          items:
            $ref: '#/components/schemas/TnsSupportIconType'
        companies:
          type: array
          items:
            type: integer
          description: show only supports from this companies (ids)
        employees:
          type: array
          items:
            type: integer
          description: filter for emmployees (technician) ids
        internalSupport:
          $ref: '#/components/schemas/TnsInternalSupportFilter'
        companyCategories:
          type: array
          items:
            type: integer
          description: show supports from these company categories (ids)
        companyCategoriesMatchType:
          $ref: '#/components/schemas/LogicOperatorType'
        excludeOwnCompany:
          type: boolean
          description: true, if supports from the own company shall be excluded
        invoiceNumber:
          type: string
          description: filter for a certain invoice (erp) number
        excludeExternalEmployees:
          type: boolean
          description: true if external employees shall be excluded
        discountedSupports:
          $ref: '#/components/schemas/TnsDiscountedSupportTypeFilter'
        notChargedReasons:
          type: array
          items:
            type: integer
          description: show supports from these "Not charged reasons" only
        departmentFilter:
          type: array
          items:
            type: integer
          description: show supports from these departments only
        ticketTypes:
          type: array
          items:
            type: integer
          description: show supports from these ticket types
        tickets:
          type: array
          items:
            type: integer
          description: show supports from these ticket (ids) only
        ticketPhases:
          type: array
          items:
            type: integer
          description: show supports from these ticket phases only
        linkTypes:
          type: array
          items:
            type: integer
          description: show supports from these link types only
        supportTypes:
          type: array
          items:
            type: integer
          description: show supports from these support types only
        includeSubTickets:
          type: boolean
          description: if true, all sub-ticket supports will be included as well (when displaying support from projects)
        planningTypes:
          type: array
          items:
            $ref: '#/components/schemas/TnsPlanningType'
          description: show supports from these planning types only
        textFilter:
          type: string
          description: if filtering for support containing a given text, you can specify the text filter here
        useRelations:
          type: boolean
          description: true if relation supports shall fe fecthed as well (when specifying company filter)
        openTickets:
          $ref: '#/components/schemas/TnsOpenTicketsFilter'
        taskFilter:
          $ref: '#/components/schemas/TnsSupportTaskFilter'
        importTypes:
          type: array
          items:
            $ref: '#/components/schemas/TnsPlanningType'
          description: show supports from these support "import types" only
        contracts:
          type: array
          items:
            type: integer
          description: show supports from these contracts (ids)
        fetchRecurring:
          type: boolean
          description: true if recurrence rules (appointments) shall be fetched as well
    TnsSupport-Create:
      description: model for creating a new support
      allOf:
        - $ref: '#/components/schemas/TnsSupport'
        - type: object
          properties:
            remitterId:
              type: integer
              description: id of the remitter (employee who ordered the support)
            ticket:
              $ref: '#/components/schemas/Ticket-Save'
    TnsSupportSignature:
      type: object
      description: signature object
      properties:
        supportId:
          type: integer
          description: id of the support
        itemNumber:
          type: integer
          description: number of the signature
        date:
          type: integer
          format: timestamp
          description: timestamp of the signature upload
        employeeId:
          type: integer
          description: id of the employee who uploaded the signature
        accumulated:
          type: boolean
          description: true if the signature was used in an accumulated pdf
    TnsSupportType:
      type: object
      description: describes a support type
      properties:
        id:
          type: integer
          description: id of the support type
          example: 1
        name:
          type: string
          description: name of the support type
          example: Onsite Support
        hidden:
          type: boolean
          description: true, if this support type is hidden (not visible in UI)
        notCharged:
          type: boolean
          description: true, if this support type is not charged
          example: false
        notChargedReasonId:
          type: integer
          description: id of the not charged reason used for this support type (if not charged)
        description:
          type: string
          description: description of the support type
    TnsTicketBoardPanelType:
      type: string
      description: Panel type
      enum:
        - DEFAULT
        - PROJECT
    TnsTicketBoardRegisterType:
      type: string
      description: Register type
      enum:
        - NONE
        - COMPANY
        - EMPLOYEE
        - DEPARTMENT
        - TAG
        - TICKET_TYPE
        - TICKET_STATUS
        - PROJECT_PHASE
    TnsTicketBoardPanelVisibility:
      type: string
      description: Panel visibility
      enum:
        - ONLY_FOR_MYSELF
        - EVERYBODY
    TnsTicketBoardPanelCompany:
      type: object
      description: Panel company
      properties:
        panelId:
          type: integer
          description: Panel id
        companyId:
          type: integer
          description: Company id
    TnsTicketBoardPanelEmployee:
      type: object
      description: Panel employee
      properties:
        panelId:
          type: integer
          description: Panel id
        employeeId:
          type: integer
          description: Employee id
    TnsTicketBoardPanelDepartment:
      type: object
      description: Panel department
      properties:
        panelId:
          type: integer
          description: Panel id
        departmentId:
          type: integer
          description: Department id
    TnsTicketBoardPanelTag:
      type: object
      description: Panel tag
      properties:
        panelId:
          type: integer
          description: Panel id
        tagId:
          type: integer
          description: Tag id
    TnsTicketBoardPanelTicketType:
      type: object
      description: Panel ticket type
      properties:
        panelId:
          type: integer
          description: Panel id
        typeId:
          type: integer
          description: Type id
    TnsTicketBoardPanelTicketStatus:
      type: object
      description: Panel ticket status
      properties:
        panelId:
          type: integer
          description: Panel id
        statusId:
          type: integer
          description: Status id
    TnsTicketBoardPanel:
      type: object
      description: Ticket board panel
      properties:
        id:
          type: integer
          description: Panel id
        name:
          type: string
          description: Panel name
        projectId:
          type: integer
          description: Panel project id
        employeeId:
          type: integer
          description: Panel employee id
        panelType:
          $ref: '#/components/schemas/TnsTicketBoardPanelType'
        registerType:
          $ref: '#/components/schemas/TnsTicketBoardRegisterType'
        includeProjects:
          type: boolean
          description: Include project tickets
        includeSubTickets:
          type: boolean
          description: Include sub tickets
        includeWaitingStates:
          type: boolean
          description: Include tickets with waiting status
        visibility:
          $ref: '#/components/schemas/TnsTicketBoardPanelVisibility'
        companies:
          type: array
          description: Array of panel companies
          items:
            $ref: '#/components/schemas/TnsTicketBoardPanelCompany'
        employees:
          type: array
          description: Array of panel employees
          items:
            $ref: '#/components/schemas/TnsTicketBoardPanelEmployee'
        departments:
          type: array
          description: Array of panel departments
          items:
            $ref: '#/components/schemas/TnsTicketBoardPanelDepartment'
        tags:
          type: array
          description: Array of panel tags
          items:
            $ref: '#/components/schemas/TnsTicketBoardPanelTag'
        ticketTypes:
          type: array
          description: Array of panel ticket types
          items:
            $ref: '#/components/schemas/TnsTicketBoardPanelTicketType'
        ticketStatus:
          type: array
          description: Array of panel ticket status
          items:
            $ref: '#/components/schemas/TnsTicketBoardPanelTicketStatus'
    TnsTicketBoard:
      type: object
      description: Ticket board
      properties:
        panels:
          type: array
          description: Array of panels
          items:
            $ref: '#/components/schemas/TnsTicketBoardPanel'
    TnsTicketBoardPanelRegister:
      type: object
      description: Ticket board panel register
      properties:
        id:
          type: integer
          description: Panel register id
        name:
          type: string
          description: Panel register name
        tickets:
          type: array
          description: Array of tickets
          items:
            $ref: '#/components/schemas/Ticket-Standard'
    TnsTicketBoardPanelRegisters:
      type: object
      description: Ticket board panel registers
      properties:
        registers:
          type: array
          description: Array of panel registers
          items:
            $ref: '#/components/schemas/TnsTicketBoardPanelRegister'
    Timer:
      type: object
      description: a TANSS timer
      properties:
        id:
          type: integer
        employeeId:
          type: integer
          description: id of the employee of this timer
        companyId:
          type: integer
          description: id of the company (otional)
        title:
          type: string
          description: a title for this timer
        duration:
          type: integer
          description: total duration (in seconds) for this timer
        callbackId:
          type: integer
          description: (optional) if the timer was created for a callback, the id is given here
        ticketId:
          type: integer
          description: (optional) if the timer was created for a ticket, the id is given here
        linkTypeId:
          type: integer
          description: (optional) if the timer was created for a misc. assignment, the linkTypeId goes here
        linkId:
          type: integer
          description: (optional) if the timer was created for a misc. assignment, the linkId goes here
    TimerFragment:
      description: |
        Timers can have multiple fragments, meaning a start/stop timeframe.
        Each fragment can have a note.
        A timer is running if the last fragment has no stop time.
        If the last fragment has a stop time, the timer is stopped.
      type: object
      properties:
        timerId:
          type: integer
          description: id of the timer id for this fragment
        startTime:
          type: integer
          format: timestamp
          description: starting time of the fragment
        stopTime:
          type: integer
          format: timestamp
          description: end time of the fragment (if 0 means that the timer is still running)
        note:
          type: string
          description: |
            a note for this fragment.
            You could for example make notes of things which are done in this fragment which should help generating the support for this timer
    TnsDeviceOwnageType:
      type: string
      description: describes who "owns" this pc
      enum:
        - OWN
        - FOREIGN
        - OWN_RENT
        - FOREIGN_RENT
    TnsPersonalComputer:
      description: Describes a pc or server
      type: object
      properties:
        id:
          type: integer
          description: id of the pc / server
        inventoryNumber:
          type: string
          description: inventory number
          example: INV001-2021-05-21
        active:
          type: boolean
          description: is this pc active or not ?
          example: true
        companyId:
          type: integer
          description: id of the company which this pc is assigned to
          example: 100000
        name:
          type: string
          description: hostname
          example: SERVER-001
        serviceTechnicianId:
          type: integer
          description: id of the responsible service technician
        employeeId:
          type: integer
          description: id of employee, which this pc is assigned to
        date:
          type: integer
          format: timestamp
          description: date when this pc was purchased
        location:
          type: string
          description: location / room of this pc
          example: Server-Raum
        manufacturerId:
          type: integer
          description: id of the manufacturer of this pc
        model:
          type: string
          description: describes the "model" of the pc. This field often is used to describe the pc (mostly in lists)
          example: Acer Altos 11000
        serialNumber:
          type: string
          description: serial number
          example: GDSZRTWE3827210463284231
        osId:
          type: integer
          description: id of the operating system
          example: 1
        software:
          type: string
          description: a text field which contains infos about installed software
          example: Div. Software wurde installiert, ...
        remark:
          type: string
          description: a text field which contains misc. infos / remarks about this pc
          example: 'Folgendes ist beim Server zu beachten: ...'
        showRemark:
          type: boolean
          description: if true, the remark will be shown as popup when this pc is selected in a support/ticket mask and the employee has the permission
        mainboardManufacturerId:
          type: integer
          description: id of the mainboard manufacturer
        mainboardManufacturerRevision:
          type: string
          description: revision of the mainboard
          example: ''
        mainboardSerialNumber:
          type: string
          description: serial number of the mainboard
          example: ''
        bios:
          type: string
          description: infos about the bios
          example: ''
        biosRelease:
          type: string
          description: release infos of the bios
          example: ''
        cpuManufacturerId:
          type: integer
          description: id of the cpu manufacturer
        cpuTypeId:
          type: integer
          description: id of the cpu type
          example: 1
        cpuFrequency:
          type: integer
          description: frequency of the cpu (in MHz)
          example: 4200
        cpuNumber:
          type: integer
          description: number of cpus
          example: 4
        mouseSerialNumber:
          type: string
          description: serial number of the mouse
          example: ''
        keyboadSerialNumber:
          type: string
          description: serial number of the keyboard
          example: ''
        server:
          type: boolean
          description: true if this pc is a server
          example: true
        internalRemark:
          type: string
          description: internal remarks of the pc (can contain passwords), which only is seen by technicians or freelancers with the given permission
          example: 'Admin-Pw: ...'
        billingNumber:
          type: string
          description: infos about the billing number which this pc was purchased
          example: ''
        articleNumber:
          type: string
          description: article number of the pc
          example: ''
        manufacturerNumber:
          type: string
          description: manufacturer number of this pc
          example: ACER-ALT-11000
        hostId:
          type: integer
          description: if this pc is a virtual host, then here the id of the host is given
        purchasePrice:
          type: number
          description: purchase price of this pc
          example: 1000
        sellingPrice:
          type: number
          description: selling price of this pc
          example: 1200
        ownageType:
          $ref: '#/components/schemas/TnsDeviceOwnageType'
        storageId:
          type: integer
          description: id of the storage, the pc is contained in
        teamviewerId:
          type: string
          description: TeamViewer id
          example: 1120-452-124
        teamviewerPassword:
          type: string
          description: TeamViewer password
          example: '1234'
        anydeskId:
          type: string
          description: AnyDesk id
          example: server@kunde.de
        anydeskPassword:
          type: string
          description: AnyDesk password
          example: '1234'
        reservedRam:
          type: number
          description: reserved ram for this virtual host
        reservedHardDisk:
          type: number
          description: reserved hard disk space reserved for this virtual host
        reservedCpu:
          type: number
          description: reserved cpu capacity reserved for this virtual host
        description:
          type: string
          description: misc. description infos for this pc
          example: Test Beschreibung
    TnsIpMac-Minimum:
      description: Information of network interface options (such as ip or mac address)
      type: object
      properties:
        ip:
          type: string
          description: ip address
          example: 192.168.1.1
        mac:
          type: string
          description: mac address
          example: a1:bc:12:f3:fe:00
        remark:
          type: string
          description: remarks
          example: ''
        dhcp:
          type: boolean
          description: is this entry a dhcp assigned ip address?
    TnsIpMacAssignmentType:
      type: string
      description: determines, which "id" is meant by "assignmentId"
      enum:
        - PC
        - PERIPHERY
    TnsIpMac:
      allOf:
        - $ref: '#/components/schemas/TnsIpMac-Minimum'
        - type: object
          properties:
            id:
              type: integer
              description: id of this network interface entry
            assignmentType:
              $ref: '#/components/schemas/TnsIpMacAssignmentType'
            assignmentId:
              type: integer
              description: id of the assignment, which this entry is assigned to (i.e. id of the pc)
    TnsIpMacServiceAssignment-Only-ServiceId:
      type: object
      description: defines a service assignment of an ip address to a service
      properties:
        serviceId:
          type: integer
          description: id of the service
    TnsIpMac-With-ServiceAssignments:
      allOf:
        - $ref: '#/components/schemas/TnsIpMac'
        - type: object
          properties:
            serviceAssignments:
              type: array
              description: if you define ip addresses, you can also give a list of service assignments which shall be assigned to this ip address
              items:
                $ref: '#/components/schemas/TnsIpMacServiceAssignment-Only-ServiceId'
    TnsGuarantee:
      description: Information of the guarantee or warranty of a device
      type: object
      properties:
        linkTypeId:
          type: integer
          description: link type id of the assignment
        linkId:
          type: integer
          description: link id of the assignment
        purchaseDate:
          type: integer
          format: timestamp
          description: date when this device was purchased
          example: 1622498400
        guaranteeMonth:
          type: integer
          description: number of months (device guarantee)
          example: 12
        guaranteeExpire:
          type: integer
          format: timestamp
          description: date when the guarantee expires
          example: 1654034400
        warrantyMonth:
          type: integer
          description: number of months (device warranty)
          example: 24
        warrantyExpire:
          type: integer
          format: timestamp
          description: date when the warranty expires
          example: 1685570400
        remark:
          type: string
          description: Misc. remarks regarding the guarantee / warranty
          example: ''
    TnsPersonalComputer-With-Ip-Guarantee:
      description: Describes a pc or server with infos (ip address, guarantee)
      allOf:
        - $ref: '#/components/schemas/TnsPersonalComputer'
        - type: object
          properties:
            ips:
              type: array
              items:
                $ref: '#/components/schemas/TnsIpMac-With-ServiceAssignments'
            guarantee:
              $ref: '#/components/schemas/TnsGuarantee'
    TnsServiceIconType:
      type: string
      description: Defines the "type" of the service icon
      enum:
        - SERVICE
        - TEAMVIEWER
        - ANYDESK
    TnsServiceIcon:
      description: |
        Service icon which is shown when listing pcs or server.

        They are used to establish a connection to the device.
      type: object
      properties:
        type:
          $ref: '#/components/schemas/TnsServiceIconType'
        name:
          type: string
          description: name of the service
          example: Putty
        address:
          type: string
          description: address which is used to establish the connection (mostly the ip address)
          example: 10.0.0.3
        symbol:
          type: string
          description: if the service has an "own" icon, here the name of the image is given
          example: service.png
        command:
          type: string
          description: if the service has a special "call" (command line or url), the command is given
          example: http://%1
    TnsComponent:
      description: Describes a pc component
      type: object
      properties:
        id:
          type: integer
          description: id of the pc / server
        inventoryNumber:
          type: string
          description: inventory number of this component
          example: INV002-2021-04-27
        componentTypeId:
          type: integer
          description: id of the component type
          example: 1
        pcId:
          type: integer
          description: the component is built into this pc (0 if the component ist not attached to a pc)
          example: 1234
        peripheryId:
          type: integer
          description: if the component is built into a periphery, here the id is given
        manufacturerId:
          type: integer
          description: id of the components manufacturer
          example: 21
        type:
          type: string
          description: type of the component. This is mostly used to "describe" the component in lists
          example: IronWolf NAS HDD ST4000VN008
        serialNumber:
          type: string
          description: serial number of the component
          example: HDFGT10374627
        megabytes:
          type: integer
          description: capcity (in megbytes), which is used to determine the size of ram or HDDs
          example: 4000000
        hddTypeId:
          type: integer
          description: id of the HDD type
          example: 1
        scsiId:
          type: string
          description: SCSI id
          example: ''
        onBoard:
          type: boolean
          description: if true, the component is "onboard"
          example: false
        companyId:
          type: integer
          description: id of the company, which this component is assigned to. Only relevant if the component is not built into a pc!
          example: 0
        remark:
          type: string
          description: remarks for this component
          example: ''
        active:
          type: boolean
          description: true, if the component is active
          example: true
        date:
          type: integer
          format: timestamp
          description: date when the component was purchased (or entered into the system)
          example: 1622498400
        billingNumber:
          type: string
          description: infos about the billing number which this component was purchased
          example: ''
        articleNumber:
          type: string
          description: article number of the component
          example: 3406-25L
        storageId:
          type: integer
          description: id of the storage, the component is contained in
        purchasePrice:
          type: number
          description: purchase price of this component
          example: 90
        sellingPrice:
          type: number
          description: selling price of this component
          example: 120
        description:
          type: string
          description: misc. description infos for this component
          example: ''
    TnsPeripheryFieldInfo:
      description: infos regarding "additional" fields in a periphery
      type: object
      properties:
        additionalFieldId:
          type: integer
          description: id of the additional field
          example: 1
        title:
          type: string
          description: title name for the field
          example: Seitenzähler
        value:
          type: string
          description: value for this additional field
          example: 1000 Seiten
    TnsPeriphery:
      description: Describes a periphery
      type: object
      properties:
        id:
          type: integer
          description: id of the periphery
        companyId:
          type: integer
          description: id of the assigned company
        date:
          type: integer
          format: timestamp
          description: date when the device was purchased (or entered into the system)
          example: 1622498400
        peripheryTypeId:
          type: integer
          description: id of the periphery type
          example: 3
        manufacturerId:
          type: integer
          description: id of the device manufacturer
        type:
          type: string
          description: type of the periphery. This is mostly used to "describe" the periphery in lists
          example: ECOTANK ET-4750
        location:
          type: string
          description: location / room of this device
          example: Druckerraum
        remark:
          type: string
          description: remarks for this component
          example: Tintenflaschen steten im Regal
        internalRemark:
          type: string
          description: internal remarks of the device (can contain passwords), which only is seen by technicians or freelancers with the given permission
          example: ''
        serialNumber:
          type: string
          description: serial number of the device
          example: GDTWR1293724
        inventoryNumber:
          type: string
          description: inventory number of this device
          example: INV003-2021-06-21
        version:
          type: string
          description: infos of the version of this device
        active:
          type: boolean
          description: true, if the device is active
          example: true
        employeeId:
          type: integer
          description: id of the assigned employee
        pcId:
          type: integer
          description: if the device is built into this pc, a pc id is given here
        billingNumber:
          type: string
          description: infos about the billing number which this component was purchased
          example: ''
        articleNumber:
          type: string
          description: article number of the component
          example: '12241389'
        storageId:
          type: integer
          description: id of the storage, the component is contained in
        purchasePrice:
          type: number
          description: purchase price of this component
          example: 404
        sellingPrice:
          type: number
          description: selling price of this device
          example: 499
        ownageType:
          $ref: '#/components/schemas/TnsDeviceOwnageType'
        name:
          type: string
          description: hostname
          example: EPS_PRINT_001
        description:
          type: string
          description: misc. description infos for this device
          example: ''
        manufacturerNumber:
          type: string
          description: manufacturer number of this device
          example: ''
        fields:
          type: array
          items:
            $ref: '#/components/schemas/TnsPeripheryFieldInfo'
    TnsAssignment:
      description: Describes an assignment of an entity to another entity
      type: object
      properties:
        linkTypeId:
          type: integer
          description: link type of the assignment (1=PC, 2=Company, etc.)
        linkId:
          type: integer
          description: id of the linked entity (the entity to which the assignment is linked)
    TnsSoftwarelicense:
      description: Describes a software license
      type: object
      properties:
        id:
          type: integer
          description: id of the software license
        companyId:
          type: integer
          description: company id of the software license
          example: 100000
        remark:
          type: string
          description: misc. infos of for this software license
          example: Virenscanner Hauptlizenz
        internalRemark:
          type: string
          description: internal remarks of the license (can contain passwords), which only is seen by technicians or freelancers with the given permission
          example: ''
        serialNumber:
          type: string
          description: serial number
          example: VIRUS-012-836-242-962-745
        inventoryNumber:
          type: string
          description: inventory number
          example: INV010-2021-06-05
        softwarelicenseTypeId:
          type: integer
          description: id of the sofware license type
          example: 1
        expirationDate:
          type: integer
          format: timestamp
          description: date when the software license will expire
          example: 1659304800
        renew:
          type: boolean
          description: if true, the license must be renewed upon expiring and therefore needs further "attention"
          example: true
        date:
          type: integer
          format: timestamp
          description: starting date for this software license
          example: 1514761200
        maxNumberOfInstall:
          type: integer
          description: maximum number of installations
          example: 10
        numberOfVolumes:
          type: integer
          description: number of volumes (i.e. cds)
        active:
          type: boolean
          description: true if the software license is still active
          example: true
        employeeId:
          type: integer
          description: id of employee which uses this software license
        articleNumber:
          type: string
          description: article number of the component
          example: ''
        contractPrice:
          type: number
          description: price which is used in maintenace contracts
        assignments:
          type: array
          description: assignments of this software license to other entities
          items:
            $ref: '#/components/schemas/TnsAssignment'
    TnsPersonalComputer-With-Details:
      description: Describes a pc or server with all "attached" infos
      allOf:
        - $ref: '#/components/schemas/TnsPersonalComputer-With-Ip-Guarantee'
        - type: object
          properties:
            serviceIcons:
              type: array
              items:
                $ref: '#/components/schemas/TnsServiceIcon'
            components:
              type: array
              description: infos about components which are built into this pc
              items:
                $ref: '#/components/schemas/TnsComponent'
            devices:
              type: array
              description: infos about devices which are linked to this pc
              items:
                $ref: '#/components/schemas/TnsPeriphery'
            softwarelicenses:
              type: array
              description: infos about software licenses which are used by this pc
              items:
                $ref: '#/components/schemas/TnsSoftwarelicense'
    TnsBranchFilterType:
      type: string
      description: filter settings for branches
      enum:
        - COMPANY_ONLY
        - BRANCHES_ONLY
        - COMPANY_AND_BRANCHES
        - SPECIFIC_BRANCH
    TnsActiveFilterType:
      type: string
      description: filter settings for "active" state of the device
      enum:
        - ACTIVE_ONLY
        - INACTIVE_ONLY
        - ACTIVE_AND_INACTIVE
    TnsDeviceBaseConfiguration:
      description: Parameters which are used to query for pcs when displaying a list of pcs/servers
      type: object
      properties:
        companyId:
          type: integer
          description: show only entries of this company
        branches:
          $ref: '#/components/schemas/TnsBranchFilterType'
        active:
          $ref: '#/components/schemas/TnsActiveFilterType'
    TnsServerFilterType:
      type: string
      description: filter settings for the "server" state
      enum:
        - PCS_ONLY
        - SERVERS_ONLY
        - SERVERS_AND_PCS
    TnsPersonalComputerConfiguration:
      allOf:
        - $ref: '#/components/schemas/TnsDeviceBaseConfiguration'
        - type: object
          properties:
            osIds:
              type: array
              description: show only there os ids
              items:
                type: integer
            servers:
              $ref: '#/components/schemas/TnsServerFilterType'
    TnsPeriphery-With-Ip:
      description: Describes a periphery with all "ip" infos
      allOf:
        - $ref: '#/components/schemas/TnsPeriphery'
        - type: object
          properties:
            ips:
              type: array
              items:
                $ref: '#/components/schemas/TnsIpMac-With-ServiceAssignments'
    TnsPeriphery-With-Ip-Guarantee:
      description: Describes a periphery with all "attached" infos
      allOf:
        - $ref: '#/components/schemas/TnsPeriphery-With-Ip'
        - type: object
          properties:
            guarantee:
              $ref: '#/components/schemas/TnsGuarantee'
    TnsPeripheryConfiguration:
      allOf:
        - $ref: '#/components/schemas/TnsDeviceBaseConfiguration'
        - type: object
          description: Parameters which are used to query for peripheries when displaying a list of peripheries
          properties:
            peripheryTypeId:
              type: integer
              description: id of the periphery type to be filtered
              items:
                type: integer
    TnsPeripheryType:
      description: Periphery type
      type: object
      properties:
        id:
          type: integer
          description: id of the periphery type
          example: 1
        name:
          type: string
          description: name of the periphery type
          example: Drucker
        image:
          type: string
          description: icon used when displaying peripheries of this type
          example: drucker.png
    TnsComponentBuiltInFilterType:
      type: string
      description: filter settings for "built in" state of the component (i.e. only built into pcs, periphery)
      enum:
        - NOT_BUILT_IN_COMPONENTS
        - COMPONENTS_IN_PCS
        - COMPONENTS_IN_PERIPHERIES
    TnsComponentConfiguration:
      allOf:
        - $ref: '#/components/schemas/TnsDeviceBaseConfiguration'
        - type: object
          description: Parameters which are used to query for component when displaying a list of component
          properties:
            componentTypeId:
              type: integer
              description: id of the component type to be filtered
              items:
                type: integer
            pcId:
              type: integer
              description: if only components of a given pc shall be displayed
              items:
                type: integer
            peripheryId:
              type: integer
              description: if only components of a given periphery shall be displayed
              items:
                type: integer
            builtInFilter:
              $ref: '#/components/schemas/TnsComponentBuiltInFilterType'
    TnsComponentType:
      description: Component type
      type: object
      properties:
        id:
          type: integer
          description: id of the component type
          example: 3
        type:
          type: string
          description: name of the component type
          example: Festplatte
        shortName:
          type: string
          description: short name of the component type
          example: HDD
        shown:
          type: boolean
          description: if false, this type won't be shown in the select field (meaning its an inactive type)
    Employee:
      description: object representing an employee
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: full name of the employee
        firstName:
          type: string
          description: first name of the employee
        lastName:
          type: string
          description: last name of the employee
        salutationId:
          type: integer
          description: id of the salutation for this employee
        departmentId:
          type: integer
          description: id of the department which tis employee is assigned to
        room:
          type: string
          description: location / room of the employee
        telephoneNumber:
          type: string
          description: main telephone number
        emailAddress:
          type: string
          description: e-Mail address
        carId:
          type: integer
          description: if this employee is assigned to a specific car, the id goes here
        mobilePhone:
          type: string
          description: mobile telephone number
        initials:
          type: string
          description: initials for this employee
        workingHourModelId:
          type: integer
          description: working hour model for this employee
        accountingTypeId:
          type: integer
          description: id of the accounting type for this employee
        privatePhoneNumber:
          type: string
          description: private telephone number
        active:
          type: boolean
          description: true if the employee is active
        erpNumber:
          type: string
        personalFaxNumber:
          type: string
          description: fax number
        role:
          type: string
          description: role for this employee
        titleId:
          type: integer
          description: if the employee uses a title, the id goes here
        language:
          type: string
          description: language which this employee uses
        telephoneNumberTwo:
          type: string
          description: second telephone number
        mobileNumberTwo:
          type: string
          description: second mobile telephone number
        restrictedUserLicense:
          type: boolean
          description: true, if the user has a "restricted" user license (if he/she is from the own company). restricted user licenses won't use a user license
        birthday:
          type: string
          description: birthday in the format "YYYY-MM-DD"
          example: '1977-12-02'
    Company-Post:
      description: Company object to be saved.
      allOf:
        - $ref: '#/components/schemas/Company-Detail'
        - type: object
          properties:
            personalCustomer:
              type: boolean
              description: defines if this company is a "personal customer" - meaning that company and employee are the same person
            personalCustomerEmployee:
              $ref: '#/components/schemas/Employee'
    TnsLinkType:
      type: string
      description: Enum representing the "link type" of an assignment. The id is given in the field "linkId"
      enum:
        - PC
        - COMPANY
        - EMPLOYEE
        - PERIPHERY
        - COMPONENT
        - SOFTWARELICENSE
        - SUPPORT
        - VOUCHER
        - DOCUMENT
        - DOCUMENT_S2T
        - TICKET
        - KNOWLEDGE_BASE
        - PERMISSION
        - PERMISSION_PACKAGE
        - GROUP
        - CALLBACK
        - CONSULTATION
        - SLA
        - CONTRACT
        - PREPAID_PURCHASE
        - EVENT
        - FILE_LINKS
        - BIRTHDAY
        - DOMAIN
        - TEAMVIEWER
        - REMOTE_SUPPORT
        - DOCUSNAP
        - MATERIAL
        - CHAT
        - TODO
        - DOCUSNAP_SNMP
        - VACATION_REQUEST
        - TICKET_BOARD_PANEL
        - DEPARTMENT
        - COMPANY_TYPE
        - TICKET_TYPE
        - MAIL
        - OFFER
        - TICKET_STATE
        - OVERTIME_ADDITIONAL_CHARGE
        - CHECKLIST
    TnsTanssEventRuleConfiguration:
      type: object
      description: defines the filter for the event rule list
      properties:
        linkType:
          $ref: '#/components/schemas/TnsLinkType'
        linkIds:
          type: array
          description: ids of the assignment to be filtered
          items:
            type: integer
    TnsTanssEventRuleAssignment:
      type: object
      description: Defines an assignment from a TANSS event rule to an assignment (i.e. Ticket Board Panel)
      properties:
        linkType:
          $ref: '#/components/schemas/TnsLinkType'
        linkId:
          type: integer
          description: id of the assignment
      example:
        linkType: TICKET_BOARD_PANEL
        linkId: 1000
    TnsTanssEventRuleActionType:
      type: string
      description: defines which action shall be executed
      enum:
        - WEBHOOK
    TnsTanssEventRuleActionParams:
      type: object
      description: defines the parameters for the action
      properties:
        url:
          type: string
          description: defines the url a webhook url will be sent to (actionType WEBHOOK)
          example: https://your-service.example.com/webhook
        method:
          type: string
          description: defines the http method for a webhook notification (actionType WEBHOOK)
          example: POST
    TnsTanssEventRuleAction:
      type: object
      description: Defines an assignment from a TANSS event rule to an assignment (i.e. Ticket Board Panel)
      properties:
        actionType:
          $ref: '#/components/schemas/TnsTanssEventRuleActionType'
        params:
          $ref: '#/components/schemas/TnsTanssEventRuleActionParams'
    TnsTanssEventRule:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: defines a "name" for the rule
          example: Benachrichtigung für Ticket Panel
        active:
          type: boolean
          description: true if the rule is active. If "false", rule won't trigger notifications
        assignments:
          type: array
          description: defines for which "assignments" a rule shall be triggered (currently only used for ticket board panels)
          items:
            $ref: '#/components/schemas/TnsTanssEventRuleAssignment'
        actions:
          type: array
          description: defines which actions will be triggered when executing the rule
          items:
            $ref: '#/components/schemas/TnsTanssEventRuleAction'
    TnsTicketNotificationReason:
      type: string
      description: reason of the ticket notification
      enum:
        - STATUS_CHANGED
        - ASSIGNED_TO_ANOTHER_TECHNICIAN
        - NEW_COMMENT
        - NEW_SUPPORT
        - TICKET_CREATED
        - TICKET_REMINDER
        - EMAIL_RECEIVED
        - TICKET_NOT_MORE_ASSIGNED_TO_SELF
        - NEW_SERVICE_CAP
        - TICKET_CLOSED
        - NEW_DUE_DATE
        - NEW_DEADLINE
        - CHANGED_TAGS
    TnsTicketNotificationOptions:
      type: object
      description: object containing infos needed for a ticket notification
      properties:
        reason:
          $ref: '#/components/schemas/TnsTicketNotificationReason'
        mailId:
          type: integer
          description: if reason is "EMAIL_RECEIVED", the id of the mail is given here
        commentId:
          type: integer
          description: if reason is "NEW_COMMENT", the id of the comment is given here
        supportId:
          type: integer
          description: if reason is "NEW_SUPPORT", the id of the support is given here
    TnsTanssEventRuleActionTestOptions:
      type: object
      description: defines the infos needed to trigger a rule test action
      properties:
        linkType:
          $ref: '#/components/schemas/TnsLinkType'
        linkId:
          type: integer
          description: id of the assignment, for which an action shall be triggered (mostly a ticket id)
        ticketNotificationOptions:
          $ref: '#/components/schemas/TnsTicketNotificationOptions'
        action:
          $ref: '#/components/schemas/TnsTanssEventRuleAction'
    TnsTanssEventTriggerType:
      type: string
      description: describes the "trigger type" of an event
      enum:
        - TICKET_STATUS_CHANGED
        - TICKET_ASSIGNED_TO_ANOTHER_TECHNICIAN
        - TICKET_NEW_COMMENT
        - TICKET_NEW_SUPPORT
        - TICKET_CREATED
        - TICKET_REMINDER
        - TICKET_EMAIL_RECEIVED
        - TICKET_NOT_MORE_ASSIGNED_TO_SELF
        - TICKET_NEW_SERVICE_CAP
        - TICKET_CLOSED
        - TICKET_NEW_DUE_DATE
        - TICKET_NEW_DEADLINE
        - TICKET_RESUBMISSION_HIT
        - TICKET_TAGS_CHANGED
    TnsTanssEventTicketObject:
      type: object
      description: infos regarding a ticket which is stored as content in an tanss event
      properties:
        id:
          type: integer
          description: id of the ticket
        companyId:
          type: integer
          description: id of the company of the ticket
        companyName:
          type: string
          description: name of the company
        remitterId:
          type: integer
          description: id of the remitter (employee id)
        remitterName:
          type: string
          description: name of the remitter
        title:
          type: string
          description: title of the ticket
        content:
          type: string
          description: content of the ticket
        assignedToEmployeeId:
          type: integer
          description: id of the assigned employee
        assignedToEmployeeName:
          type: string
          description: name of the assigned employee
        assignedToDepartmentId:
          type: integer
          description: id of the assigned department
        assignedToDepartmentName:
          type: string
          description: name of the assigned department
        statusId:
          type: integer
          description: id of the ticket status
        statusName:
          type: string
          description: name of the ticket status
        typeId:
          type: integer
          description: id of the ticket type
        typeName:
          type: string
          description: name of the ticket type
        dueDate:
          type: integer
          format: timestamp
          description: due date as timestamp
        dueDateFormatted:
          type: string
          description: formatted due date
        deadlineDate:
          type: integer
          format: timestamp
          description: deadline date as timestamp
        deadlineDateFormatted:
          type: string
          description: formatted deadline date
        serviceCapAmount:
          type: number
          description: service cap of the ticket
        serviceCapAmountFormatted:
          type: string
          description: formatted service cap
    TnsTanssEventPostingObject:
      type: object
      description: if the tanss ticket object contains infos about a comment, then the infos are given here
      properties:
        id:
          type: integer
          description: id of the comment
        employeeId:
          type: integer
          description: id of the author / employee
        employeeName:
          type: string
          description: name of the author / employee
        title:
          type: string
          description: title of the comment
        content:
          type: string
          description: content of the comment
        internal:
          type: boolean
          description: true if it's an internal comment
    TnsTanssEventMailObject:
      type: object
      description: if the tanss ticket object contains infos about a mail, then the infos are given here
      properties:
        id:
          type: integer
          description: id of the mail
        senderName:
          type: string
          description: name of the sender
        senderEMail:
          type: string
          description: email of the sender
        subject:
          type: string
          description: mail subject
        bodyPlain:
          type: string
          description: plaintext body of the mail
        inbound:
          type: boolean
          description: true if it's an inbound E-Mail
        internal:
          type: boolean
          description: true if it's an internal E-Mail
        receiverEMails:
          type: array
          description: list of E-Mail receivers
          items:
            type: string
    TnsTanssEventSupportObject:
      type: object
      description: if the tanss ticket object contains infos about a support, then the infos are given here
      properties:
        id:
          type: integer
          description: id of the support
        companyId:
          type: integer
          description: id of the company
        companyName:
          type: string
          description: name of the company
        employeeId:
          type: integer
          description: id of the technician
        employeeName:
          type: string
          description: name of the technician
        location:
          $ref: '#/components/schemas/TnsSupportLocation'
        date:
          type: integer
          format: timestamp
          description: date of the support as timestamp
        dateFormatted:
          type: string
          description: formatted date of the support
        duration:
          type: integer
          description: duration in minutes
        typeId:
          type: integer
          description: id of the support type
        typeName:
          type: string
          description: name of the support type
        text:
          type: string
          description: text(description of the support
        internal:
          type: boolean
          description: true if it's an internal support
        planningType:
          $ref: '#/components/schemas/TnsPlanningType'
        planningTypeName:
          type: string
          description: name of the planning typ (i.e. "Getätigte Leistung", "Termin")
        outlook:
          type: boolean
          description: true if it's an outlook appointment
    TnsTanssEventTicketContent:
      type: object
      description: ticket content of a tanss event
      properties:
        ticket:
          $ref: '#/components/schemas/TnsTanssEventTicketObject'
        oldValues:
          $ref: '#/components/schemas/TnsTanssEventTicketObject'
        comment:
          $ref: '#/components/schemas/TnsTanssEventPostingObject'
        mail:
          $ref: '#/components/schemas/TnsTanssEventMailObject'
        support:
          $ref: '#/components/schemas/TnsTanssEventSupportObject'
        addedTags:
          type: array
          description: if tags were added, here the list of added tags is given
          items:
            $ref: '#/components/schemas/TnsTag'
        removedTags:
          type: array
          description: if tags were removed, here the list of removed tags is given
          items:
            $ref: '#/components/schemas/TnsTag'
    TnsTanssEvent:
      type: object
      description: Describes a tanss event / activity feed item
      properties:
        id:
          type: integer
        employeeId:
          type: integer
          description: id of the employee who this event is for
        linkType:
          $ref: '#/components/schemas/TnsLinkType'
        linkId:
          type: integer
          description: id of the assignment, which this event refers to
        triggerType:
          $ref: '#/components/schemas/TnsTanssEventTriggerType'
        content:
          $ref: '#/components/schemas/TnsTanssEventTicketContent'
    TnsServiceCallType:
      description: defines how a service will be executed
      type: string
      enum:
        - BATCH
        - URL
    TnsService:
      description: represents a service (which can be assigned to an ip address on a pc/periphery)
      type: object
      properties:
        id:
          type: integer
          description: id of the service
        text:
          type: string
          description: name of the service
          example: Putty
        symbol:
          type: string
          description: filename of the image representing the service
          example: putty.gif
        command:
          type: string
          description: |
            command which shall be executed (via batch file)

            %1% is the placeholder which contains the ip address
          example: C:\Programme\Putty\putty.exe\ -ssh -load "utf8" %1%"
        active:
          type: boolean
          description: is service active or not
        callType:
          $ref: '#/components/schemas/TnsServiceCallType'
    TnsPersonalComputerOperatingSystem:
      type: object
      description: representing a operating system to be used for pc/servers
      properties:
        id:
          type: integer
          description: id of the os
        name:
          type: string
          description: name of the os
          example: macOs monterey
        serverOperatingSystem:
          type: boolean
          description: define if this os is only to be used for servers
          example: false
        active:
          type: boolean
          description: define if this os is still active/used
          example: true
        articleNumber:
          type: string
          description: (optional) article number used in erp
          example: ''
    TnsManufacturer:
      type: object
      description: representing a manufacturer
      properties:
        id:
          type: integer
          description: id of the manufacturer
        name:
          type: string
          description: name of the manufacturer
          example: Acer
    TnsPersonalComputerCpu:
      type: object
      description: representing a cpu to be used for pc/servers
      properties:
        id:
          type: integer
          description: id of the cpu
        name:
          type: string
          description: name/type of the cpu
          example: Intel 486 DX/33
    TnsPersonalComputerHddType:
      type: object
      description: representing a hdd type
      properties:
        id:
          type: integer
          description: id of the hdd type
        name:
          type: string
          description: name/type of the hdd type
          example: S-ATA
    TnsCompanyCategory:
      type: object
      description: defines a company category
      properties:
        id:
          type: integer
          description: id of the company category
          example: 1
        name:
          type: string
          description: name of the company category
          example: Regionen
    TnsCompanyCategory-With-Types:
      description: company category with all contained types
      allOf:
        - $ref: '#/components/schemas/TnsCompanyCategory'
        - type: object
          properties:
            types:
              type: array
              description: all types within this category
              items:
                $ref: '#/components/schemas/TnsCompanyType'
    TnsLinkType-For-Search:
      type: string
      description: Enum representing the "link type" of an entity to be identifed
      enum:
        - PC
        - EMPLOYEE
        - CPU_TYPE
        - MANUFACTURER
        - OS
      example: MANUFACTURER
    TnsIdentifySearchSection:
      description: in which "sections" shall be searched
      type: string
      enum:
        - NAME
        - EMAIL
        - DOMAIN
        - SEARCH
    TnsIdentifyQueryItem:
      description: Describes a item which is to be "identifed" by the API (i.e. get an id by name)
      type: object
      properties:
        linkType:
          $ref: '#/components/schemas/TnsLinkType-For-Search'
        identifier:
          type: string
          description: identifier (or name) of the entity. This will be used to search the entity id.
          example: Intel
        searchSections:
          type: array
          items:
            $ref: '#/components/schemas/TnsIdentifySearchSection'
    TnsIdentifyRequest:
      description: A request for ideentifying misc. entities (i.e. get manufacturer id by name)
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TnsIdentifyQueryItem'
    TnsIdentifyItemResult:
      description: Describes a single result for a "query item"
      type: object
      properties:
        linkType:
          $ref: '#/components/schemas/TnsLinkType-For-Search'
        linkId:
          type: integer
          description: retrieved "id" of the entity which was found
          example: 1234
        percent:
          type: integer
          description: (optional) if not mathcin 100%, will return a certain percentage
        name:
          type: string
          description: name of the entity which was found
          example: Intel
        searchSection:
          $ref: '#/components/schemas/TnsIdentifySearchSection'
        object:
          type: object
          description: object of the target entity (containing the actual found entity, i.e. company, cpu type, manufacturer...)
          example:
            id: 1234
            name: Intel
    TnsIdentifyQueryItem-Result:
      description: This contains the identifed entity data
      allOf:
        - $ref: '#/components/schemas/TnsIdentifyQueryItem'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/TnsIdentifyItemResult'
    TnsIdentifyResponse:
      description: Response containing all identified objects
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TnsIdentifyQueryItem-Result'
    TnsEmailAccount:
      type: object
      description: describes an email account (mailbox)
      properties:
        id:
          type: integer
          example: 1
        companyId:
          type: integer
          description: mail account is assigned to this company
          example: 100000
        description:
          type: string
          description: name of the mailbox / description
          example: Catch-All Postfach von Firma A
        loginName:
          type: string
          description: login name
          example: TestUser1
        loginPassword:
          type: string
          description: login password
          example: 64gdfs_izda8!
        incomingServer:
          type: string
          description: name/address of the incoming mail server
          example: pop3.test.de
        outgoingServer:
          type: string
          description: name/address of the outgoing mail server
          example: smtp.test.de
        sendAttachments:
          type: boolean
          description: are attachments sent?
          example: true
        deleteArchived:
          type: boolean
          description: will archived mails be sent?
          example: true
        sendTrackingInfos:
          type: boolean
          description: shall tracking infos be sent?
          example: false
        catchAllAccount:
          type: boolean
          description: is this a catch-all-mailbox?
          example: true
        addresses:
          type: string
          description: list of assigned e-mail addresses (semicolon seperated)
          example: address1@kunde.de;address2@kunde.de
        active:
          type: boolean
          description: is this account activated?
          example: true
        typeId:
          type: integer
          description: id of the account type
          example: 1
        typeName:
          type: string
          description: if no existing type will match the account, you define a name for the type here
        remark:
          type: string
          description: remark for this mail account
        linkTypeId:
          type: integer
          description: linkType of the assignment for this mail account
          example: 0
        linkId:
          type: integer
          description: linkId of the assignment for this mail account
          example: 0
        domainId:
          type: integer
          description: if the account is assigned to an domain, the id is given here
          example: 0
    TnsEmailAccountType:
      type: object
      description: type of an E-mail account
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: POP3-Postfach
    TnsVacationRequestStatus:
      type: string
      description: Specifies the status of a vacation request
      enum:
        - NEW
        - REQUESTED
        - APPROVED
        - DECLINED
      example: NEW
    TnsVacationRequestConfiguration:
      type: object
      description: object to specify query parameters for fetching a list of vacation requests
      properties:
        year:
          type: integer
          description: only show vacation requests from certain year
          example: 2023
        month:
          type: integer
          description: only show vacation requests from certain month
          example: 11
        employeeIds:
          type: array
          items:
            type: integer
          description: filter for certain employees
        departmentIds:
          type: array
          items:
            type: integer
          description: filter for certain departments
        planningTypes:
          type: array
          items:
            $ref: '#/components/schemas/TnsPlanningType'
          description: filter for certain planning types
        planningAdditionalIds:
          type: array
          items:
            type: integer
          description: filter for certain "additional" planning types (used on absences)
        customTypeIds:
          type: array
          items:
            type: integer
          description: filter for certain custom types
        statesOnly:
          type: array
          items:
            $ref: '#/components/schemas/TnsVacationRequestStatus'
          description: filter for certain planning type states
    TnsVacationRequestDay:
      type: object
      description: describes a day used in a vacation request
      properties:
        vacationRequestId:
          type: integer
          description: id of the vacation request the day is assigned to
        date:
          type: integer
          format: timestamp
          description: timestamp for this day. always us the beginning of the day (0:00 o'clock)
        forenoon:
          type: boolean
          description: vacation request for the whole forenoon?
        afternoon:
          type: boolean
          description: vacation request for the whole afternoon?
        startHour:
          type: integer
          description: if only a certain timeframe is used - starting hour
        startMinute:
          type: integer
          description: if only a certain timeframe is used - starting minute
        endHour:
          type: integer
          description: if only a certain timeframe is used - end hour
        endMinute:
          type: integer
          description: if only a certain timeframe is used - end minute
        pause:
          type: integer
          description: if only a certain timeframe is used - pause (in minutes)
    TnsVacationRequest:
      type: object
      description: vacation request (or illness, absence, custom type, overtime, standBy, custom). If a custom type shall be stored, use the planningAdditionalId property to specify the custom type
      properties:
        id:
          type: integer
          description: id of the vacation request
        planningType:
          $ref: '#/components/schemas/TnsPlanningType'
        status:
          $ref: '#/components/schemas/TnsVacationRequestStatus'
        startDate:
          type: integer
          format: timestamp
          description: start for this vacation request
        endDate:
          type: integer
          format: timestamp
          description: start for this vacation request
        requesterId:
          type: integer
          description: id of the requester (employee)
        requestReason:
          type: string
          description: reason for this vacation request (optional)
        requestDate:
          type: integer
          format: timestamp
          description: timestamp when this vacation request was initially created
        supervisorId:
          type: integer
          description: id of the supervisor (employee who has accepted/declined this request)
        supervisorReason:
          type: string
          description: reason for accepting/declining this request (optional)
        supervisorDate:
          type: integer
          format: timestamp
          description: timestamp when this vacation request was accepted or declined
        planningAdditionalId:
          type: integer
          description: only if planningType is ABSENCE or CUSTOM / used for additional specification (Sonderurlaub, Kur, etc.)
        processId:
          type: integer
          description: if a approval process is used for this vacation request - specifies the id of the process
        processStepId:
          type: integer
          description: if a approval process is used for this vacation request - specifies the id of the current process step
        days:
          type: array
          items:
            $ref: '#/components/schemas/TnsVacationRequestDay'
    TnsPlanningAdditionalSubType:
      type: string
      description: determines the type - either ABSENCE or CUSTOM
      enum:
        - ABSENCE
        - CUSTOM
      example: CUSTOM
    TnsPlanningAdditionalType:
      type: object
      description: describes a "additional" absence type OR a custom type
      properties:
        id:
          type: integer
          description: if of this entry
        name:
          type: string
          description: displayed name for this absence type / custom type
          example: Home-Office
        charged:
          type: boolean
          description: shall this absence type be charged?
        type:
          $ref: '#/components/schemas/TnsPlanningAdditionalSubType'
        backgroundColor:
          type: string
          description: background color that shall be used (only for custom types)
        fontColor:
          type: string
          description: font color that shall be used (only for custom types)
        active:
          type: boolean
          description: is this type still active (is displayed in forms)?
    TnsEmployeeVacationDays:
      type: object
      description: gives details on the vacation days of an employee
      properties:
        employeeId:
          type: integer
          description: employee id
        year:
          type: integer
          description: infos for which year
        numberOfDays:
          type: integer
          description: how many days does this employee have
        transferred:
          type: integer
          description: number of days transferred from the previous year
        employee:
          $ref: '#/components/schemas/Employee'
    TnsTanssEventConfigurationSeenFilter:
      type: string
      description: filter for the field "seen"
      enum:
        - BOTH
        - ONLY_SEEN
        - ONLY_UNSEEN
    TnsTanssEventConfigurationConfirmedFilter:
      type: string
      description: filter for the field "confirmed"
      enum:
        - BOTH
        - ONLY_CONFIRMED
        - ONLY_UNCONFIRMED
    TnsTanssEventConfiguration:
      type: object
      description: defines the filter for the activity feed items
      properties:
        minimumCreationDate:
          type: integer
          format: timestamp
          description: if given, will only fetch newer activity feed items
        linkTypes:
          type: array
          items:
            $ref: '#/components/schemas/TnsLinkType'
        linkIds:
          type: array
          description: link ids that shall be filtered for
          items:
            type: integer
        triggerTypes:
          type: array
          items:
            $ref: '#/components/schemas/TnsTanssEventTriggerType'
        preventViewEvent:
          type: boolean
          description: if true, will nor mark item as "seen"
        includeContent:
          type: boolean
          description: if true, additional content will be given(i.e. ticket object)
        seenFilter:
          $ref: '#/components/schemas/TnsTanssEventConfigurationSeenFilter'
        confirmedFilter:
          $ref: '#/components/schemas/TnsTanssEventConfigurationConfirmedFilter'
    TnsTicketState:
      type: object
      description: represents a ticket state
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          description: Name of the ticket state
          example: In Bearbeitung
        image:
          type: string
          description: Name of the image. Must be in the folder `media/hp/bug_status`
          example: in_bearbeitung.gif
        waitState:
          type: boolean
          description: determines if this state is a waiting state
        rank:
          type: integer
          description: Rank of this state (position in lists)
        active:
          type: boolean
          description: is this an active state? (otherwise won't be shown)
    TnsDocumentTypeEnum:
      type: string
      description: describes the type of this document
      enum:
        - DOCUMENT
        - KNOWLEDGE_BASE_ARTICLE
        - LINK
        - FILE
      example: DOCUMENT
    TnsDocumentConfiguration:
      type: object
      description: filter object for fetching a document list
      properties:
        companyId:
          type: integer
          description: if given, will only show documents of this company
        linkTypeId:
          type: integer
          description: show only documents for this assignment (linkTypeId)
        linkId:
          type: integer
          description: show only documents for this assignment (linkId)
        branchFilter:
          $ref: '#/components/schemas/TnsBranchFilterType'
        textFilter:
          type: string
          description: text filter for documents
        types:
          type: array
          items:
            - $ref: '#/components/schemas/TnsDocumentTypeEnum'
    TnsDocument:
      type: object
      description: a company document
      properties:
        id:
          type: integer
          description: id of the document
          example: 1
        date:
          type: integer
          format: timestamp
          description: creation date of the document
        modificationDate:
          type: integer
          format: timestamp
          description: modification date of the document
        name:
          type: string
          description: name of the document
          example: Anleitung für TANSS Installation
        type:
          $ref: '#/components/schemas/TnsDocumentTypeEnum'
        companyId:
          type: integer
          description: id of the company for this document
        createdEmployeeId:
          type: integer
          description: id of the employee who created this document
        internal:
          type: boolean
          description: is this an internal document? (not shown for customers)
        linkTypeId:
          type: integer
          description: if this document is assigned to a pc/periphery etc. - give linkTypeId here
          example: 1
        linkId:
          type: integer
          description: if this document is assigned to a pc/periphery etc. - give linkId here
          example: 12312
        encrypted:
          type: boolean
          description: if true, the document will be stored encrypted in the database
    TnsDocument-With-Content:
      allOf:
        - $ref: '#/components/schemas/TnsDocument'
        - type: object
          properties:
            content:
              type: string
              description: content of this document
              example: Inhalt des Dokuments
            decodedContent:
              type: string
              description: |
                Is only used if this document is "encrypted". In this case the decoded content is shown here
    TnsDocumentFile:
      type: object
      description: an uploaded file for a document
      properties:
        id:
          type: integer
          description: id of the uploaded file
        documentId:
          type: integer
          description: id of the document this file belongs to
        filename:
          type: string
          description: stored filename of this file
          example: 100000_1726749928460_Dependency Update Mai 24.txt
        originalFilename:
          type: string
          description: original filename
          example: Dependency Update Mai 24.txt
        mime:
          type: string
          description: mime type for this file
          example: text/plain
        size:
          type: integer
          description: size of file (in bytes)
          example: 12312
        employeeId:
          type: integer
          description: id of the employee who uploaded the file
          example: 2
        createdDate:
          type: integer
          description: timestamp of the creation (upload)
          example: 1726749928
        modifiedDate:
          type: integer
          description: timestamp of the modification
          example: 1726749928
    TnsDocument-With-File:
      allOf:
        - $ref: '#/components/schemas/TnsDocument-With-Content'
        - type: object
          properties:
            uploadedFile:
              $ref: '#/components/schemas/TnsDocumentFile'
    TnsDomain:
      type: object
      description: represents a domain
      properties:
        id:
          type: integer
          description: id of the domain
        companyId:
          type: integer
          description: id of the company the domain belongs to
          example: 100000
        title:
          type: string
          description: title for the domain
          example: TANSS Webseite
        fqdn:
          type: string
          description: FQDN
          example: www.tanss.de
        description:
          type: string
          description: a description for this domain
    TnsDomain-Full:
      allOf:
        - $ref: '#/components/schemas/TnsDomain'
        - type: object
          properties:
            providerName:
              type: string
              description: Name of the provider
            customerId:
              type: string
              description: customer number
            adminUrl:
              type: string
              description: url for administration of this domain
            loginName:
              type: string
              description: login name
            loginPassword:
              type: string
              description: login password
            contractDurationStart:
              type: integer
              description: start time of the contract
            contractDurationEnd:
              type: integer
              description: end time of the contract
            purchasePrice:
              type: number
              format: double
              description: purchase price
            sellingPrice:
              type: number
              format: double
              description: selling price
            usage:
              type: string
              description: usage for this domain (text)
            forwardDomainId:
              type: integer
              description: if this domain is forwarded to another domain, give the id here
            responsibleTechId:
              type: integer
              description: id of the employee who is responsible for this domain
            certificate:
              type: string
              description: certificate
            certificateCa:
              type: string
              description: certificate chain
            ipv4:
              type: string
              description: IP V4 address
            ipv6:
              type: string
              description: IP V6 address
            ownerLinkTypeId:
              type: integer
              description: link type for "owner" (company or employee link types possible)
            owner:
              type: integer
              description: link id "owner" (id of company or employee, based on link type)
            admincLinkTypeId:
              type: integer
              description: link type for "adminc" (company or employee link types possible)
            adminc:
              type: integer
              description: link id "adminc" (id of company or employee, based on link type)
            techcLinkTypeId:
              type: integer
              description: link type for "techc" (company or employee link types possible)
            techc:
              type: integer
              description: link id "techc" (id of company or employee, based on link type)
    TnsSoftwarelicenseExpiryFilterType:
      description: Defines how software licenses are filtered by expiry status.
      type: string
      enum:
        - ALL
        - ONLY_EXPIRED
        - ONLY_NOT_EXPIRED
        - EXPIRE_IN_60_DAYS
        - EXPIRED_WITHOUT_RENEW
        - EXPIRED_WITH_RENEW
        - EXPIRES_IN_X_DAYS
    TnsSoftwarelicenseConfiguration:
      allOf:
        - $ref: '#/components/schemas/TnsDeviceBaseConfiguration'
        - type: object
          properties:
            softwarelicenseTypeId:
              type: integer
              format: integer
              description: Periphery type (software license type id).
            linkTypeId:
              type: integer
              format: integer
              description: Link type id (assignment relation type).
            linkId:
              type: integer
              format: integer
              description: Linked entity id (device id or other target depending on linkTypeId).
            includeSubTypes:
              type: boolean
              description: Whether sub types should be included as well.
              default: true
            expiryFilter:
              $ref: '#/components/schemas/TnsSoftwarelicenseExpiryFilterType'
              description: Expiry filter.
            onlyOverlicenced:
              type: boolean
              description: If true, return only over-licensed entries.
              default: false
    TnsSoftwarelicenseType:
      description: Describes a software license type including default values and pricing information.
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: Unique identifier of the software license type.
        manufacturerNumber:
          type: string
          description: Manufacturer article number.
          example: MN-12345
        name:
          type: string
          description: Name of the software license type.
          example: Antivirus Pro
        comment:
          type: string
          description: Comment or description of the software license type.
        previousId:
          type: integer
          format: int32
          description: Reference to a previous software license type.
        active:
          type: boolean
          description: Indicates whether the software license type is active.
        standardRunningTime:
          type: integer
          format: int32
          description: Default running time of the license (e.g. in months).
        standardRenew:
          type: boolean
          description: Indicates whether the license is renewed by default.
        standardMaxNumberOfInstallations:
          type: integer
          format: int32
          description: Default maximum number of installations.
        articleNumber:
          type: string
          description: Internal article number.
        path:
          type: array
          description: Hierarchical path of the software license type.
          items:
            type: string
          example:
            - Software
            - Security
            - Antivirus
    TnsPriceCommons:
      type: object
      properties:
        linkTypeId:
          type: integer
          description: link/entity type of the assignment
          example: 1
        linkId:
          type: integer
          description: id of the entity, based on the link type
          example: 1000
        price:
          type: number
          description: special price
          example: 11.25
    TnsAccountingTypePrice:
      description: This object represents a special accountig type price
      allOf:
        - $ref: '#/components/schemas/TnsPriceCommons'
        - type: object
          properties:
            accountingTypeId:
              type: integer
              description: id of the counting type
              example: 3
  responses:
    TicketListResponse:
      description: list of tickets
      content:
        application/json:
          schema:
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/TnsMetaMessage'
              content:
                type: array
                items:
                  $ref: '#/components/schemas/Ticket-List'
            example:
              meta:
                linkedEntities:
                  companies:
                    '100000':
                      name: 'Firma #100000'
                  tickets: {}
                  ticketStates:
                    '2':
                      image: auge.gif
                      name: gesichtet
                  ticketTypes:
                    '3':
                      name: Störung
                  departments:
                    '1':
                      name: Technik
                  employees:
                    '8094':
                      initials: tm
                      name: Mitarbeiter, Test
                  phases: {}
                  orderBys: {}
                  costCenters: {}
                properties:
                  extras:
                    departmentOrder:
                      value: []
                    count:
                      value: 1
                    showTicketTitle:
                      value: true
                    showTicketType:
                      value: false
                    waitingStates:
                      value:
                        - 6
                        - 7
                        - 8
                        - 13
                        - 19
                    prefs:
                      '4':
                        '8094':
                          '2': 0
                          '100': 0
                      '20':
                        '8094':
                          '2': 0
                      '22':
                        '8094':
                          '11': 0
                          '68': 0
                      '43':
                        '8094':
                          '2': 0
              content:
                - id: 142953
                  companyId: 100000
                  remitterId: 0
                  title: Test Ticket Überschrift
                  content: |-
                    Dies ist eine Ticket Beschreibung.
                    Folgendes ist zu tun:
                    1.) Office installieren
                    2.) PC ausliefern
                  extTicketId: ''
                  creationDate: 1563967125
                  assignedToEmployeeId: 8094
                  assignedToDepartmentId: 1
                  statusId: 2
                  linkTypeId: 0
                  linkId: 0
                  deadlineDate: 0
                  project: false
                  projectId: 0
                  createdEmployeeId: 8094
                  typeId: 3
                  repair: false
                  reminder: 0
                  reactionHours: 0
                  dueDate: 1564046280
                  attention: 'NO'
                  orderById: 0
                  locked: false
                  installationFee: 'NO'
                  installationFeeAmount: 0
                  separateBilling: false
                  serviceCapAmount: 0
                  relationshipLinkTypeId: 0
                  relationshipLinkId: 0
                  resubmissionDate: 0
                  resubmissionText: ''
                  phaseId: 0
                  estimatedMinutes: 0
                  localTicketAdminFlag: NONE
                  localTicketAdminEmployeeId: 0
                  modifiedBy: 0
                  modifiedTime: 0
                  numberOfDocuments: 0
                  chats: []
                  remitterDepartmentId: 0
                  modified: 1564046280
    ErrorResponse:
      description: error response
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                $ref: '#/components/schemas/TnsException'
          example:
            error:
              text: CANT_CHECK_ITEM_TWICE
              localizedText: Item is checked and can't be checked a second time
              type: InvalidArgumentException
x-tagGroups:
  - name: Authentication
    tags:
      - security
  - name: Tickets
    tags:
      - tickets
      - ticket lists
      - ticket content
      - ticket states
      - ticket types
      - ticket workflows
      - ticket priorities
      - ticket roles
      - ticket board
      - tickets - history & meta
  - name: Projects
    tags:
      - projects
  - name: Company
    tags:
      - company
      - company - master data
      - company - relations
      - company category
      - documents
      - entity files
      - files & links
      - emailAccounts
      - domains
  - name: Employees
    tags:
      - employees
      - employees - salutations
      - employees - titles
      - employees - departments
      - employees - personal data
      - employees - links & relations
      - permission packages
      - permissions
      - availability
      - daily services
  - name: Vacation
    tags:
      - vacationRequests
      - vacationRequests - balance & config
  - name: Timestamp
    tags:
      - timestamp
      - timestamp - config
      - timers
  - name: Planning
    tags:
      - planning
      - recurrence
  - name: Workflow & Tasks
    tags:
      - checklists
      - checklists - events
      - checklists - items
      - assignments
  - name: Escalations
    tags:
      - escalations
      - escalation categories
  - name: Supports
    tags:
      - supports
      - supportTypes
      - additional charges
      - support rules
      - not charged reasons
  - name: Communication & Activity
    tags:
      - mails
      - email settings
      - callback
      - activityFeed
  - name: Chat
    tags:
      - chats
  - name: Search, Tags & Identify
    tags:
      - tags
      - search
      - templates
      - textModules
      - popup notifications
      - identify
  - name: Documents & Editor
    tags:
      - knowledge base
  - name: Offers
    tags:
      - offer
      - erp selections
      - offer templates
  - name: Contracts
    tags:
      - contracts
      - sla
      - tasks
      - workflow contracts
  - name: Devices & Assets
    tags:
      - pc
      - periphery
      - components
      - services
      - ips
      - operating systems
      - manufacturer
      - cpus
      - hddTypes
      - device management
  - name: Software Licenses
    tags:
      - software licenses
      - software license types
  - name: Phone Calls
    tags:
      - calls (user context)
  - name: External API (Token-Based)
    tags:
      - calls
      - remote supports
      - monitoring
      - erp
      - webHooks
  - name: Administration
    tags:
      - administration
      - accounting types
      - currencies
      - holidays
      - cars
      - payment methods
      - text templates
      - preferences
      - working hours
      - search & maintenance
      - administration - export & ui-helpers
  - name: Internal & Advanced
    tags:
      - util routes
      - scheduled tasks
      - logging
      - git
      - ical
