> ## 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 supplier order > **Erforderliche Berechtigungen:** `orders:write` Ermöglicht es einem Lieferanten, eine ihm zugeordnete Bestellung zu aktualisieren — Bestätigen, Ablehnen, Bearbeiten, Stornierung bestätigen, Abruf bestätigen oder Eingang bestätigen. Der API-Schlüssel muss mit einem Lieferanten verknüpft sein (`SUPPLIER_AND_OPTIONAL_CUSTOMER`). Lieferanten können ausschließlich Bestellungen aktualisieren, die ihrem Lieferantenkonto zugeordnet sind. **Verhalten der `change_type`-State-Machine:** - `CONFIRM_ORDER` — Setzt den Status auf `CONFIRMED`. - `DECLINE_ORDER` — Setzt den Status auf `DECLINED`. - `EDIT_ORDER` — Wendet die in `changes` übergebenen Felder an, ohne den Status zu ändern. - `CONFIRM_CANCEL_ORDER` — Setzt den Status auf `CANCEL_CONFIRMED` (nur möglich, wenn die Bestellung im Status `CANCELLED` ist). - `CONFIRM_ON_DEMAND` — Setzt den Status auf `ON_DEMAND_CONFIRMED`. - `RECEIVE_ORDER` — Setzt den Status auf `RECEIVED`. Das Feld `changes` wird nur für `EDIT_ORDER` ausgewertet — bei den übrigen Änderungstypen wird es ignoriert. So können ERP-Systeme bei Bestätigungen risikofrei den vollständigen Bestelldatensatz mitschicken, ohne ihn versehentlich zu mutieren. Optional kann `pdf_base64` ein base64-kodiertes PDF (z. B. Auftragsbestätigung) mitschicken. Identische PDFs werden per Content-Hash dedupliziert. Werden keine tatsächlichen Änderungen erkannt (z. B. weil die übergebenen Werte mit dem aktuellen Stand übereinstimmen), liefert der Endpunkt `Keine Änderungen` zurück und führt keinen Schreibvorgang aus. ## Overview This endpoint lets a supplier update one of their assigned orders through the comstruct API. Confirming, declining, editing, confirming a cancellation, confirming an on-demand call-off, and acknowledging receipt are all handled through a single `PATCH` call. The actual status transition is derived server-side from the `change_type` field — `status` is intentionally **not** part of the request body so the state machine stays on the server. If the submitted fields match the current state of the order, the endpoint replies with `Keine Änderungen` ("No changes") and skips the write. ERP systems can therefore safely include the full order payload on confirmations without risking accidental mutations. ## Permissions | Scope | Tenant type | | -------------- | --------------------------------------------------- | | `orders:write` | Supplier API key (`SUPPLIER_AND_OPTIONAL_CUSTOMER`) | The API key must be linked to a supplier. Customer-only API keys cannot use this endpoint. Suppliers can only update orders that are assigned to their own supplier account. ## Headers | Header | Required | Description | | -------------- | -------- | --------------------------------- | | `x-api-key` | Yes | API key with scope `orders:write` | | `Content-Type` | Yes | `application/json` | ## Path parameters | Parameter | Type | Description | | --------- | ------ | -------------------------------- | | `id` | `uuid` | Unique ID of the order to update | ## Change types (`change_type`) | Value | Effect | Precondition | | ---------------------- | ------------------------------------------------------ | ----------------------------------- | | `CONFIRM_ORDER` | Sets status to `CONFIRMED` | — | | `DECLINE_ORDER` | Sets status to `DECLINED` | — | | `EDIT_ORDER` | Applies the fields in `changes`; status stays the same | — | | `CONFIRM_CANCEL_ORDER` | Sets status to `CANCEL_CONFIRMED` | Order must be in status `CANCELLED` | | `CONFIRM_ON_DEMAND` | Sets status to `ON_DEMAND_CONFIRMED` | — | | `RECEIVE_ORDER` | Sets status to `RECEIVED` | — | `changes` is **only** consumed for `EDIT_ORDER`. For every other change type the body of `changes` is ignored. ## Optional PDF (`pdf_base64`) | Field | Type | Required | Description | | --------------- | -------- | -------- | ----------------------------------------------- | | `pdf_base64` | `string` | No | Base64-encoded PDF (max. 10 MB decoded) | | `pdf_file_name` | `string` | No | Optional filename for the stored document title | The PDF can be sent with any `change_type` — for example confirm an order and attach the order confirmation in one request. Identical PDFs are deduplicated by content hash. ## Editable fields (only on `EDIT_ORDER`) | Field | Type | Description | | ----------------------- | ------------------- | ------------------------------------------------------------------------- | | `supplier_order_number` | `string` | Supplier-side order number | | `planned_delivery_time` | `string` (ISO 8601) | Planned delivery date / time | | `comment` | `string` | Supplier comment on the order | | `properties` | `object` | Free-form additional metadata (shallow-merged with existing `properties`) | | `items` | `array` | Order line items — replaces the existing item list | ### Item fields (`items[]`) | Field | Type | Description | | ---------------- | -------------- | ------------------------------------------------------- | | `title` | `string` | Line item title | | `quantity` | `number` (≥ 0) | Quantity | | `unit` | `string` | Unit of measure (`m3`, `t`, `kg`, `stk`, `h`, `pau`, …) | | `description` | `string` | Optional long description | | `product_number` | `string` | Supplier product number | | `type` | `string` | Line item type | | `marked` | `boolean` | Flag the line item as verified | ## Behavior * Only fields that actually differ from the current state are written. * If `EDIT_ORDER` produces no real diff, the endpoint replies with `Keine Änderungen` and writes nothing. * `properties` is **shallow-merged** with the existing payload — keys you don't send keep their previous value. * `items` is **fully replaced** when present in `changes`. * Every successful mutation triggers a change notification email to the customer; the `comment` is forwarded in that email. ## Response codes | Code | Description | | ----- | ------------------------------------------------------------------------------ | | `200` | Order updated successfully or no changes detected | | `400` | Invalid input — validation failed | | `401` | Unauthorized — API key is not linked to a supplier | | `403` | Forbidden — missing `orders:write` scope, or order belongs to another supplier | | `404` | Order not found / invalid `id` | | `500` | Internal server error | ## OpenAPI ````yaml PATCH /supplier-orders/{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 - 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: /supplier-orders/{id}: patch: tags: - Orders (Supplier) summary: Lieferantenbestellung aktualisieren description: > **Erforderliche Berechtigungen:** `orders:write` Ermöglicht es einem Lieferanten, eine ihm zugeordnete Bestellung zu aktualisieren — Bestätigen, Ablehnen, Bearbeiten, Stornierung bestätigen, Abruf bestätigen oder Eingang bestätigen. Der API-Schlüssel muss mit einem Lieferanten verknüpft sein (`SUPPLIER_AND_OPTIONAL_CUSTOMER`). Lieferanten können ausschließlich Bestellungen aktualisieren, die ihrem Lieferantenkonto zugeordnet sind. **Verhalten der `change_type`-State-Machine:** - `CONFIRM_ORDER` — Setzt den Status auf `CONFIRMED`. - `DECLINE_ORDER` — Setzt den Status auf `DECLINED`. - `EDIT_ORDER` — Wendet die in `changes` übergebenen Felder an, ohne den Status zu ändern. - `CONFIRM_CANCEL_ORDER` — Setzt den Status auf `CANCEL_CONFIRMED` (nur möglich, wenn die Bestellung im Status `CANCELLED` ist). - `CONFIRM_ON_DEMAND` — Setzt den Status auf `ON_DEMAND_CONFIRMED`. - `RECEIVE_ORDER` — Setzt den Status auf `RECEIVED`. Das Feld `changes` wird nur für `EDIT_ORDER` ausgewertet — bei den übrigen Änderungstypen wird es ignoriert. So können ERP-Systeme bei Bestätigungen risikofrei den vollständigen Bestelldatensatz mitschicken, ohne ihn versehentlich zu mutieren. Optional kann `pdf_base64` ein base64-kodiertes PDF (z. B. Auftragsbestätigung) mitschicken. Identische PDFs werden per Content-Hash dedupliziert. Werden keine tatsächlichen Änderungen erkannt (z. B. weil die übergebenen Werte mit dem aktuellen Stand übereinstimmen), liefert der Endpunkt `Keine Änderungen` zurück und führt keinen Schreibvorgang aus. operationId: updateSupplierOrder parameters: - name: id in: path required: true schema: type: string format: uuid description: Bestellungs-ID (UUID) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSupplierOrderRequest' examples: confirm_order: summary: Bestellung bestätigen value: change_type: CONFIRM_ORDER comment: Bestellung wird wie geplant ausgeliefert. confirm_order_with_pdf: summary: Bestellung bestätigen und PDF anhängen value: change_type: CONFIRM_ORDER comment: Auftragsbestätigung im Anhang. pdf_base64: >- JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c+PgplbmRvYmoK pdf_file_name: order-confirmation.pdf decline_order: summary: Bestellung ablehnen value: change_type: DECLINE_ORDER comment: Material derzeit nicht lieferbar. edit_order: summary: Bestellung bearbeiten (Lieferdatum + Positionen) value: change_type: EDIT_ORDER comment: Lieferdatum und Mengen angepasst. changes: supplier_order_number: SUP-2024-0001 planned_delivery_time: '2024-06-12T08:30:00Z' items: - title: Beton C25/30 quantity: 50 unit: m3 product_number: BET-C2530 - title: Bewehrungsstahl quantity: 2 unit: t product_number: BST-500 confirm_on_demand: summary: Abrufbestellung bestätigen value: change_type: CONFIRM_ON_DEMAND comment: Abruf bestätigt. receive_order: summary: Bestelleingang bestätigen value: change_type: RECEIVE_ORDER responses: '200': description: Bestellung erfolgreich aktualisiert oder keine Änderungen erkannt content: application/json: schema: $ref: '#/components/schemas/UpdateSupplierOrderResponse' examples: updated: summary: Bestellung aktualisiert value: message: >- Die aktualisierte Bestellung wurde an das Bauunternehmen gesendet. error: null no_changes: summary: Keine Änderungen erkannt value: message: Keine Änderungen error: null '400': $ref: '#/components/responses/BadRequest' '401': description: Nicht autorisiert - Schlüssel ist mit keinem Lieferanten verknüpft content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_supplier_link: summary: API-Schlüssel ohne Lieferantenbindung value: error: >- Unauthorized. API key must be linked to a supplier (customer is optional). '403': description: >- Verboten - Fehlende Berechtigung oder Bestellung gehört einem anderen Lieferanten content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_scope: summary: Fehlende Berechtigung value: error: 'Unauthorized. Missing scope: orders:write' wrong_supplier: summary: Bestellung gehört einem anderen Lieferanten value: error: Forbidden. Order does not belong to this supplier. '404': description: Bestellung nicht gefunden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Bestellungs-ID unbekannt value: error: Die Bestellnummer ist ungültig. '500': $ref: '#/components/responses/InternalServerError' security: - ApiKey: - orders:write components: schemas: UpdateSupplierOrderRequest: type: object required: - change_type properties: change_type: type: string enum: - CONFIRM_ORDER - DECLINE_ORDER - EDIT_ORDER - CONFIRM_CANCEL_ORDER - CONFIRM_ON_DEMAND - RECEIVE_ORDER description: > Treibt die Statusübergänge der Bestellung: - `CONFIRM_ORDER` → Status `CONFIRMED` - `DECLINE_ORDER` → Status `DECLINED` - `EDIT_ORDER` → Status unverändert; `changes` werden angewendet - `CONFIRM_CANCEL_ORDER` → Status `CANCEL_CONFIRMED` (Bestellung muss vorher `CANCELLED` sein) - `CONFIRM_ON_DEMAND` → Status `ON_DEMAND_CONFIRMED` - `RECEIVE_ORDER` → Status `RECEIVED` comment: type: string maxLength: 2000 description: >- Optionaler Kommentar des Lieferanten zu dieser Änderung. Wird in der Benachrichtigung an das Bauunternehmen mitgesendet. changes: allOf: - $ref: '#/components/schemas/SupplierOrderChangesInput' description: > Konkrete Feldänderungen. Wird nur für `change_type: EDIT_ORDER` ausgewertet — bei allen anderen Änderungstypen wird der Inhalt ignoriert, sodass ERP-Systeme den vollständigen Bestelldatensatz risikofrei mitschicken können. pdf_base64: type: string description: >- Optionales base64-kodiertes PDF (roh oder mit data-URI-Präfix, max. 10 MB dekodiert) pdf_file_name: type: string description: Optionaler Dateiname für den Dokumenttitel bei `pdf_base64` UpdateSupplierOrderResponse: type: object properties: message: type: string description: >- Menschenlesbare Statusmeldung; `Keine Änderungen` signalisiert, dass keine Mutation durchgeführt wurde. example: Die aktualisierte Bestellung wurde an das Bauunternehmen gesendet. error: type: string nullable: true description: Fehlermeldung, sofern aufgetreten (sonst `null`) example: null 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 SupplierOrderChangesInput: type: object description: > Felder, die ein Lieferant via API mutieren darf. Wird nur ausgewertet, wenn `change_type` den Wert `EDIT_ORDER` hat. Der Status wird **nicht** über dieses Objekt gesteuert — er ergibt sich aus dem `change_type` und wird serverseitig gesetzt. properties: items: type: array description: >- Bestellpositionen. Wird übergeben, ersetzt der Server die bestehenden Positionen. items: $ref: '#/components/schemas/SupplierOrderItemInput' supplier_order_number: type: string description: Lieferanteneigene Bestellnummer example: SUP-2024-0001 planned_delivery_time: type: string format: date-time description: Geplantes Lieferdatum (ISO 8601) example: '2024-06-12T08:30:00Z' comment: type: string description: Lieferantenkommentar zur Bestellung properties: type: object description: >- Frei strukturierte Zusatzinformationen. Wird mit den vorhandenen `properties` zusammengeführt (Shallow-Merge). additionalProperties: true SupplierOrderItemInput: type: object description: > Lieferantenseitige Sicht auf eine einzelne Bestellposition. Nur in `EDIT_ORDER`-Anfragen relevant — bei anderen `change_type`-Werten wird das Feld ignoriert. properties: title: type: string description: Positionsbezeichnung example: Beton C25/30 quantity: type: number minimum: 0 description: Bestellmenge example: 50 unit: type: string description: Mengeneinheit example: m3 description: type: string description: Optionale Detailbeschreibung der Position product_number: type: string description: Produktnummer beim Lieferanten example: BET-C2530 type: type: string description: Positionstyp marked: type: boolean description: Position als verifiziert markieren responses: BadRequest: description: Ungültige Anfrage - Ungültige Eingabe oder Validierung fehlgeschlagen content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Feldvalidierungsfehler value: error: Validation failed for field external_id array_expected: summary: Array erwartet value: error: Invalid request body. Expected an array of purchase orders. InternalServerError: description: Interner Serverfehler content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: server_error: summary: Server-Verarbeitungsfehler value: error: The server was unable to process processing_error: summary: Verarbeitungsfehler mit Details value: error: Error processing Purchase Orders message: >- Supplier not found. creditor_number does not match an existing supplier. invoice_processing_error: summary: Rechnungsverarbeitungsfehler value: success: false error: Failed to parse invoice supplier_processing_error: summary: Lieferantenverarbeitungsfehler value: message: Error processing supplier data. 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. ````