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

# Update delivery

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

Aktualisiert eine bestehende Lieferung und ihre Positionen. Änderungen werden in der Lieferhistorie protokolliert.
Nur Lieferungen, die dem Kunden des API-Schlüssels gehören, können bearbeitet werden.
Markierte (gesperrte) Lieferungen können nicht bearbeitet werden. Um eine markierte Lieferung zu aktualisieren, muss sie zuerst über die Web-App entmarkiert werden.


## Overview

This endpoint allows customers to update existing deliveries. Changes are recorded in the delivery history. Only deliveries belonging to the API key's customer can be patched.

<Info>
  Marked (locked) deliveries cannot be edited. To update a marked delivery, unmark it first via the web app.
</Info>

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

## Headers

| Header            | Required | Description                                        |
| ----------------- | -------- | -------------------------------------------------- |
| `x-api-key`       | Yes      | API key with scope `deliveries:patch`              |
| `x-change-reason` | No       | Reason for the change (stored in delivery history) |

## Editable fields

### Delivery

| Field                  | Type                | Description                                  |
| ---------------------- | ------------------- | -------------------------------------------- |
| `comment`              | `string`            | Free-text comment                            |
| `planned_arrival_time` | `string` (ISO 8601) | Planned arrival time                         |
| `order_number`         | `string`            | Order number                                 |
| `project_id`           | `uuid`              | Project assignment                           |
| `project_number`       | `string`            | Project number                               |
| `invoice_number`       | `string`            | Invoice number                               |
| `delivery_number`      | `string`            | Delivery note number                         |
| `work_type_id`         | `string`            | Work type ID                                 |
| `charging_number`      | `string`            | Charging number                              |
| `received_at`          | `string` (ISO 8601) | Received timestamp                           |
| `invoice_matched`      | `boolean`           | Invoice matching confirmed                   |
| `marked`               | `boolean`           | Mark delivery as verified                    |
| `charged`              | `boolean`           | Mark delivery as charged                     |
| `properties`           | `object`            | Additional properties (merged with existing) |
| `plant`                | `object`            | Plant (`{ "title": "..." }`)                 |

### Items

| Field                    | Type      | Description                   |
| ------------------------ | --------- | ----------------------------- |
| `title`                  | `string`  | Item description              |
| `quantity`               | `number`  | Quantity                      |
| `unit`                   | `string`  | Unit of measure               |
| `product_number`         | `string`  | Product number                |
| `type`                   | `string`  | Item type                     |
| `work_type_id`           | `string`  | Work type ID                  |
| `marked`                 | `boolean` | Mark item as verified         |
| `invoice_matched`        | `boolean` | Invoice matching confirmed    |
| `charged`                | `boolean` | Mark item as charged          |
| `purchase_order_item_id` | `uuid`    | Link to a purchase order item |

## Behavior

* Only changed fields are updated. Fields not included in the body remain unchanged.
* If no changes are detected, the existing delivery is returned unchanged.
* When boolean fields (`marked`, `invoice_matched`, `charged`) are changed at the delivery level, all items are synchronized.
* Setting `marked: true` automatically sets `received_at` to the current timestamp.
* Changes to `properties` are merged with existing properties.

## Response codes

| Code  | Description                                           |
| ----- | ----------------------------------------------------- |
| `200` | Delivery successfully updated (or returned unchanged) |
| `400` | Invalid input or delivery is marked/locked            |
| `403` | Forbidden — delivery belongs to another customer      |
| `404` | Delivery not found                                    |
| `422` | Update failed                                         |


## OpenAPI

````yaml PATCH /deliveries/{id}
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

    - 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}:
    patch:
      tags:
        - Deliveries (Customer)
      summary: Lieferung aktualisieren
      description: >
        **Erforderliche Berechtigungen:** `deliveries:patch`


        Aktualisiert eine bestehende Lieferung und ihre Positionen. Änderungen
        werden in der Lieferhistorie protokolliert.

        Nur Lieferungen, die dem Kunden des API-Schlüssels gehören, können
        bearbeitet werden.

        Markierte (gesperrte) Lieferungen können nicht bearbeitet werden. Um
        eine markierte Lieferung zu aktualisieren, muss sie zuerst über die
        Web-App entmarkiert werden.
      operationId: patchDelivery
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Lieferungs-ID (UUID)
        - name: x-change-reason
          in: header
          required: false
          schema:
            type: string
          description: Grund für die Änderung (wird in der Lieferhistorie gespeichert)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchDeliveryRequest'
      responses:
        '200':
          description: Lieferung erfolgreich aktualisiert (oder unverändert zurückgegeben)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryResponse'
        '400':
          description: Ungültige Eingabe oder Lieferung ist markiert/gesperrt
          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'
        '422':
          description: Aktualisierung fehlgeschlagen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey:
            - deliveries:patch
components:
  schemas:
    PatchDeliveryRequest:
      type: object
      description: Alle Felder sind optional. Nur angegebene Felder werden aktualisiert.
      properties:
        comment:
          type: string
          description: Freitext-Kommentar
        planned_arrival_time:
          type: string
          format: date-time
          description: Geplante Ankunftszeit (ISO 8601)
        order_number:
          type: string
          description: Bestellnummer
        project_id:
          type: string
          format: uuid
          description: Projektzuordnung
        project_number:
          type: string
          description: Projektnummer
        invoice_number:
          type: string
          description: Rechnungsnummer
        delivery_number:
          type: string
          description: Lieferscheinnummer
        work_type_id:
          type: string
          description: Leistungsart-ID
        charging_number:
          type: string
          description: Verrechnungsnummer
        received_at:
          type: string
          format: date-time
          description: Empfangszeitpunkt (ISO 8601)
        invoice_matched:
          type: boolean
          description: Rechnungszuordnung bestätigt
        marked:
          type: boolean
          description: Lieferung als verifiziert markieren
        charged:
          type: boolean
          description: Lieferung als berechnet markieren
        items:
          type: array
          items:
            $ref: '#/components/schemas/PatchDeliveryItemRequest'
          description: Positionen der Lieferung
        properties:
          type: object
          description: Zusätzliche Eigenschaften (wird mit bestehenden zusammengeführt)
        plant:
          type: object
          properties:
            title:
              type: string
              description: Name des Werks
    DeliveryResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Lieferungs-ID
        delivery_number:
          type: string
          description: Lieferscheinnummer
        comment:
          type: string
          description: Kommentar
        planned_arrival_time:
          type: string
          format: date-time
          description: Geplante Ankunftszeit
        marked:
          type: boolean
          description: Ob die Lieferung markiert/verifiziert wurde
        invoice_matched:
          type: boolean
          description: Rechnungszuordnung bestätigt
        charged:
          type: boolean
          description: Lieferung als berechnet markiert
        received_at:
          type: string
          format: date-time
          description: Empfangszeitpunkt
        items:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              quantity:
                type: number
              unit:
                type: string
              product_number:
                type: string
              work_type_id:
                type: string
                format: uuid
              marked:
                type: boolean
              invoice_matched:
                type: boolean
              charged:
                type: boolean
    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
    PatchDeliveryItemRequest:
      type: object
      properties:
        title:
          type: string
          description: Positionsbezeichnung
        quantity:
          type: number
          description: Menge
        unit:
          type: string
          description: Mengeneinheit (z.B. m3, t, kg, stk)
        product_number:
          type: string
          description: Produktnummer
        type:
          type: string
          description: Positionstyp
        work_type_id:
          type: string
          description: Leistungsart-ID
        marked:
          type: boolean
          description: Position als verifiziert markieren
        invoice_matched:
          type: boolean
          description: Rechnungszuordnung bestätigt
        charged:
          type: boolean
          description: Position als berechnet markieren
        purchase_order_item_id:
          type: string
          format: uuid
          description: Zuordnung zu einer Bestellposition
  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.

````