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

# Replace delivery components

> **Erforderliche Berechtigungen:** `deliveries:patch`

Ersetzt alle Komponentenzuordnungen der Lieferung durch die übergebenen Gruppen.
Alle `component_ids` müssen zum Projekt der Lieferung gehören; innerhalb einer Gruppe müssen sie eindeutig sein.
Verteilungswerte müssen endliche, nicht negative Zahlen sein.
Gruppen, deren `distribution` leer ist oder nur Nullen enthält, werden ignoriert (wie in der Web-App).
Mit einem leeren Array `groups` werden alle Zuordnungen entfernt.


## Overview

Replaces **all** component assignments for the delivery with the provided groups — equivalent to saving the component overview in the web app. Each group typically combines several project components (often one per component type) that share the same quantity split across delivery line items.

## Permissions

| Scope              | Tenant type                     |
| ------------------ | ------------------------------- |
| `deliveries:patch` | Customer only (`CUSTOMER_ONLY`) |

The API key must be linked to a customer. Supplier API keys cannot use this endpoint.

## Request body

| Field    | Type    | Description                                 |
| -------- | ------- | ------------------------------------------- |
| `groups` | `array` | List of groups; `[]` clears all assignments |

### Per group (`groups[]`)

| Field           | Type       | Description                                                                                    |
| --------------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `component_ids` | `number[]` | Project component IDs; at least one per group, unique within the group                         |
| `distribution`  | `object`   | Map from delivery line item title (`title` on the line item) to a finite non-negative quantity |

## Validation and behavior

* Every `component_id` must belong to the delivery's **project**.
* Distribution values must be **finite, non-negative** numbers.
* Groups whose `distribution` is empty or contains only zeros are **skipped** (same as the web app).
* The response matches **GET** `/deliveries/{id}/components` (including server-assigned `group_id` and enriched component metadata).

## Response codes

| Code  | Description                                              |
| ----- | -------------------------------------------------------- |
| `200` | Components saved; body same shape as GET                 |
| `400` | Invalid body or components not on the delivery's project |
| `403` | Forbidden — delivery belongs to another customer         |
| `404` | Delivery not found                                       |


## OpenAPI

````yaml PUT /deliveries/{id}/components
openapi: 3.0.3
info:
  title: comstruct Public API
  description: >
    Die comstruct API ist eine umfassende und flexible Lösung zur Optimierung
    des Materialbeschaffungsprozesses für Unternehmen. Diese API bietet eine
    einfache Schnittstelle für Entwickler, um auf Materialbeschaffungsdaten
    zuzugreifen und diese zu verwalten, einschließlich Lieferanteninformationen,
    Lieferungen und Projekte.


    ## Erste Schritte

    Um Zugang zur comstruct API zu erhalten, wenden Sie sich bitte an Ihren
    zuständigen Customer Success Manager. Unser Expertenteam steht Ihnen mit
    erstklassigem Support zur Verfügung, um Ihnen zu helfen, das Beste aus
    unserer API herauszuholen.


    ## Authentifizierung

    Alle API-Endpunkte unter `/v1` erfordern eine Authentifizierung mittels
    API-Schlüssel im `x-api-key`-Header. Jeder API-Schlüssel hat spezifische
    Berechtigungen (Scopes), die bestimmen, welche Endpunkte und Operationen
    verfügbar sind. Die Authentifizierung wird durch Middleware durchgesetzt,
    die den API-Schlüssel und die Berechtigungen für jede Anfrage validiert.


    Kalender-Endpunkte unter `/calendars` und IDS-Endpunkte unter `/ids` liegen
    **ohne** `/v1`-Präfix (Basis-URL `https://api.comstruct.com`). Kalender
    verwenden Token-basierte Authentifizierung; IDS ist ein öffentlicher
    Callback ohne API-Schlüssel.


    ## Datenformate

    - Alle Zeitstempel sind im ISO 8601-Format (UTC)

    - Geldbeträge werden als Dezimalzahlen dargestellt

    - IDs sind UUIDs, sofern nicht anders angegeben


    ## Anfragegrößenbeschränkungen

    - PDF-Rechnungsverarbeitung, benutzerdefinierte Rechnungsverarbeitung und
    Workflow-Verarbeitung: 32MiB

    - Asynchroner Lieferschein-PDF-Upload (`POST /deliveries/pdf`): 16MiB

    - Alle anderen Endpunkte: 10MiB


    ## Fehlerbehandlung

    Die API verwendet Standard-HTTP-Statuscodes und gibt detaillierte
    Fehlermeldungen im JSON-Format zurück. Weitere Details finden Sie in den
    Fehlerschemas.


    ## Integrationsmuster

    - **SAP-Integration**: Spezialisierte Endpunkte für SAP-ERP-Systeme

    - **Projektverwaltung**: Vollständiges Projektlebenszyklusmanagement mit
    Benutzerrollen

    - **Lieferverfolgung**: Unterstützung mehrerer Lieferscheinformate
    (OpenTrans, PAHM, Q-Point, benutzerdefiniert)

    - **Rechnungsverarbeitung**: Automatisierte Rechnungsanalyse und
    -validierung mit KI/GPT-Unterstützung

    - **Auftragsverwaltung**: IDS-Auftragsverarbeitung mit XML-Parsing und
    Projektkalenderintegration

    - **Kalenderintegration**: Separate Kalender-Endpunkte für
    iCalendar-Abonnement-Feeds
  version: 1.0.10
  license:
    name: Proprietary
    url: https://comstruct.com
  contact:
    name: comstruct ICT GmbH
    url: https://comstruct.com
    email: support@comstruct.com
  termsOfService: https://comstruct.com/datenschutzerklarung/
  x-logo:
    url: https://app.comstruct.com/logo-light-text.png
    altText: comstruct logo
servers:
  - url: https://api.comstruct.com/v1
    description: Haupt-API-Endpunkte (erfordert API-Schlüssel-Authentifizierung)
    variables: {}
  - url: https://api.comstruct.com
    description: Basisserver für Kalender- und IDS-Endpunkte (andere Authentifizierung)
    variables: {}
security:
  - ApiKey: []
tags:
  - name: Projects
    description: Endpunkte für Projekte.
  - name: Projects (SAP)
    description: SAP-spezifische Projekt-Endpunkte.
  - name: Project Regions
    description: Endpunkte für die Verwaltung von Projektregionen.
  - name: Deliveries
    description: Endpunkte für Lieferungen.
  - name: Deliveries (Supplier)
    description: Lieferantenspezifische Liefer-Endpunkte.
  - name: Accounts
    description: Endpunkte für die Verwaltung von Sachkonten.
  - name: Payment Terms
    description: Endpunkte für die Verwaltung von Zahlungsbedingungen.
  - name: Tax Codes
    description: Endpunkte für die Verwaltung von Steuercodes.
  - name: Company Codes
    description: Endpunkte für die Verwaltung von Buchungskreisen (juristische Einheiten).
  - name: Suppliers
    description: Endpunkte für die Verwaltung von Lieferanten.
  - name: Purchase Orders
    description: Endpunkte für Bestellungen.
  - name: Purchase Orders (SAP)
    description: SAP-spezifische Bestellungs-Endpunkte.
  - name: Orders (Supplier)
    description: >-
      Lieferantenspezifische Bestellungs-Endpunkte (Bestätigung, Ablehnung,
      Bearbeitung).
  - name: Suppliers (SAP)
    description: SAP-spezifische Lieferanten-Endpunkte.
  - name: Invoices
    description: Endpunkte für Rechnungen.
  - name: Invoices (Supplier)
    description: Lieferantenspezifische Rechnungs-Endpunkte.
  - name: Invoices (SAP)
    description: SAP-spezifische Rechnungs-Endpunkte.
  - name: Invoice Dimensions
    description: >
      Rechnungs-Dimensionen (benutzerdefinierte Eigenschaften) und Zuweisungen
      auf Rechnung (`header`), Position (`line_item`) oder Kontierung
      (`account`).


      Dimensionen haben den Typ `option` (vordefinierte Werte) oder `text`
      (Freitext über `dimension_id` + `text_value`). Bulk-Konto-POST
      (`/assignments/account/bulk`) unterstützt nur Options-Zuweisungen über
      `option_ids`; Freitext auf Kontoebene über Einzel-POST, PATCH-Bulk oder
      Positions-Bulk.
  - name: Workflows
    description: Endpunkte für Workflow- und Prozessmanagement.
  - name: Calendar
    description: Kalender-Abonnement-Endpunkte mit separater Authentifizierung.
  - name: Orders
    description: Endpunkte für Auftragsverarbeitung und -verwaltung.
paths:
  /deliveries/{id}/components:
    put:
      tags:
        - Deliveries (Customer)
      summary: Lieferkomponenten ersetzen
      description: >
        **Erforderliche Berechtigungen:** `deliveries:patch`


        Ersetzt alle Komponentenzuordnungen der Lieferung durch die übergebenen
        Gruppen.

        Alle `component_ids` müssen zum Projekt der Lieferung gehören; innerhalb
        einer Gruppe müssen sie eindeutig sein.

        Verteilungswerte müssen endliche, nicht negative Zahlen sein.

        Gruppen, deren `distribution` leer ist oder nur Nullen enthält, werden
        ignoriert (wie in der Web-App).

        Mit einem leeren Array `groups` werden alle Zuordnungen entfernt.
      operationId: setDeliveryComponents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Lieferungs-ID (UUID)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetDeliveryComponentsRequest'
            examples:
              two_groups:
                summary: Zwei Gruppen mit Verteilung
                value:
                  groups:
                    - component_ids:
                        - 42
                        - 17
                      distribution:
                        Beton C30/37: 5.5
                        Betonpumpe: 1
                    - component_ids:
                        - 99
                      distribution:
                        Beton C25/30: 3
              clear_all:
                summary: Alle Komponenten entfernen
                value:
                  groups: []
      responses:
        '200':
          description: >-
            Komponentengruppen nach der Aktualisierung (gleiche Struktur wie
            GET)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryComponentsResponse'
        '400':
          description: >-
            Ungültiger Anfragetext oder Komponenten gehören nicht zum
            Lieferprojekt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Lieferung nicht gefunden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey:
            - deliveries:patch
components:
  schemas:
    SetDeliveryComponentsRequest:
      type: object
      required:
        - groups
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/SetDeliveryComponentGroupRequest'
          description: Liste der Komponentengruppen; leeres Array entfernt alle Zuordnungen
    DeliveryComponentsResponse:
      type: object
      required:
        - groups
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryComponentGroupResponse'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Fehlermeldung, die beschreibt, was schiefgelaufen ist
        message:
          type: string
          description: Zusätzliche Fehlerdetails oder benutzerfreundliche Nachricht
        success:
          type: boolean
          description: Zeigt Fehlschlag an, wenn in Fehlerantworten vorhanden
      anyOf:
        - required:
            - error
        - required:
            - message
        - required:
            - success
      example:
        error: Validation failed
        message: The provided data did not pass validation checks
    SetDeliveryComponentGroupRequest:
      type: object
      required:
        - component_ids
        - distribution
      properties:
        component_ids:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: integer
          description: IDs der Projektkomponenten in dieser Gruppe
          example:
            - 42
            - 17
        distribution:
          type: object
          additionalProperties:
            type: number
          description: >-
            Mengen je Positionsbezeichnung der Lieferung (Schlüssel = `title`
            der Position)
          example:
            Beton C30/37: 5.5
    DeliveryComponentGroupResponse:
      type: object
      properties:
        group_id:
          type: string
          format: uuid
          description: Gruppenkennung, die alle Komponenten dieser Gruppe teilen
        distribution:
          type: object
          additionalProperties:
            type: number
          nullable: true
          description: >-
            Mengen je Positionsbezeichnung der Lieferung (Schlüssel = `title`
            der Position)
          example:
            Beton C30/37: 5.5
        components:
          type: array
          description: Eine Zeile pro Projektkomponente in dieser Gruppe
          items:
            $ref: '#/components/schemas/DeliveryComponentAssignment'
    DeliveryComponentAssignment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID der Zuordnungszeile
        component_id:
          type: integer
          description: ID der Projektkomponente
        component_title:
          type: string
          description: Titel der Projektkomponente
        component_type_id:
          type: string
          format: uuid
          nullable: true
          description: ID des Komponententyps (Kategorie)
        component_type_title:
          type: string
          nullable: true
          description: Titel des Komponententyps (Kategorie)
  responses:
    Forbidden:
      description: Verboten - Ungültige oder fehlende Berechtigung
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid_scope:
              summary: Ungültige Berechtigung
              value:
                message: Invalid scope.
            missing_scope:
              summary: Fehlende spezifische Berechtigung
              value:
                error: 'Unauthorized. Missing scope: projects:write'
            missing_invoices_scope:
              summary: Fehlende Rechnungsberechtigung
              value:
                error: 'Unauthorized. Missing scope: invoices:write'
            missing_suppliers_scope:
              summary: Fehlende Lieferantenberechtigung
              value:
                error: 'Unauthorized. Missing scope: suppliers:write'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        API-Schlüssel zur Authentifizierung. Kontaktieren Sie Ihren Customer
        Success Manager, um einen API-Schlüssel zu erhalten.


        Jeder Endpunkt erfordert spezifische Berechtigungen (Scopes); die
        erforderlichen Scopes werden pro Endpunkt angezeigt.

````