curl --request PATCH \
  --url https://api.comstruct.com/v1/supplier-orders/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "change_type": "CONFIRM_ORDER",
  "comment": "Bestellung wird wie geplant ausgeliefert."
}
'

{
  "message": "Die aktualisierte Bestellung wurde an das Bauunternehmen gesendet.",
  "error": null
}

Bestellungen (Lieferanten)

Lieferantenbestellung aktualisieren

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.

PATCH

supplier-orders

{id}

curl --request PATCH \
  --url https://api.comstruct.com/v1/supplier-orders/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "change_type": "CONFIRM_ORDER",
  "comment": "Bestellung wird wie geplant ausgeliefert."
}
'

{
  "message": "Die aktualisierte Bestellung wurde an das Bauunternehmen gesendet.",
  "error": null
}

Übersicht

Mit diesem Endpunkt können Lieferanten eine ihnen zugeordnete Bestellung über die comstruct API aktualisieren — Bestätigung, Ablehnung, Bearbeitung, Bestätigung einer Stornierung, Bestätigung eines Abrufs sowie Bestätigung des Bestelleingangs werden über einen einzigen PATCH-Aufruf abgewickelt. Der eigentliche Statusübergang wird serverseitig aus dem Feld change_type abgeleitet — das Feld status ist im Body bewusst nicht zugelassen, damit die Statusmaschine im Backend bleibt.

Wenn die übergebenen Felder mit dem aktuellen Stand der Bestellung übereinstimmen, antwortet der Endpunkt mit Keine Änderungen und führt keinen Schreibvorgang aus. ERP-Systeme können bei Bestätigungen daher gefahrlos den vollständigen Bestelldatensatz mitschicken.

Berechtigungen

Scope	Tenant-Typ
`orders:write`	Lieferanten-API-Schlüssel (`SUPPLIER_AND_OPTIONAL_CUSTOMER`)

Der API-Schlüssel muss mit einem Lieferanten verknüpft sein. Reine Kunden-API-Schlüssel können diesen Endpunkt nicht verwenden. Lieferanten dürfen ausschließlich Bestellungen aktualisieren, die ihrem eigenen Lieferantenkonto zugeordnet sind.

Header	Pflicht	Beschreibung
`x-api-key`	Ja	API-Schlüssel mit Scope `orders:write`
`Content-Type`	Ja	`application/json`

Pfadparameter

Parameter	Typ	Beschreibung
`id`	`uuid`	Eindeutige ID der zu aktualisierenden Bestellung

Änderungstypen (`change_type`)

Wert	Wirkung	Vorbedingung
`CONFIRM_ORDER`	Setzt den Status auf `CONFIRMED`	—
`DECLINE_ORDER`	Setzt den Status auf `DECLINED`	—
`EDIT_ORDER`	Wendet die in `changes` übergebenen Felder an, Status bleibt unverändert	—
`CONFIRM_CANCEL_ORDER`	Setzt den Status auf `CANCEL_CONFIRMED`	Bestellung muss im Status `CANCELLED` sein
`CONFIRM_ON_DEMAND`	Setzt den Status auf `ON_DEMAND_CONFIRMED`	—
`RECEIVE_ORDER`	Setzt den Status auf `RECEIVED`	—

changes wird ausschließlich für EDIT_ORDER ausgewertet. Bei den übrigen Änderungstypen wird der Inhalt von changes ignoriert.

Feld Supplier Comment (Lieferantenkommentar)

Das Feld comment ist ein optionales String-Feld auf oberster Ebene (max. 2000 Zeichen), das mit jedem change_type mitgesendet werden kann. Es wird von Lieferanten verwendet, um:

Hinweise bei der Bestellbestätigung hinzuzufügen (z. B. ‘Bestätigt, Lieferung nächste Woche geplant’)
Gründe bei Ablehnung zu erklären (z. B. ‘Material erst ab Q2 verfügbar’)
Kontext bei Bearbeitungen zu geben (z. B. ‘Menge auf Kundenwunsch erhöht’)

Das Feld comment wird immer in der Änderungsbenachrichtigung an den Kunden mitgeführt, unabhängig davon, welcher change_type verwendet wurde. Es eignet sich daher ideal für die Kommunikation vom Lieferanten zum Kunden.

Das Feld comment ist getrennt von dem editierbaren Feld changes.comment in EDIT_ORDER. Der Top-Level-comment gilt für diese spezifische Aktion, während changes.comment den dauerhaft gespeicherten Kommentar der Bestellung aktualisiert.

Beispiele

Bestätigung mit Kommentar:

{
  "change_type": "CONFIRM_ORDER",
  "comment": "Bestellung bestätigt, Lieferung voraussichtlich Montag"
}

Ablehnung mit Begründung:

{
  "change_type": "DECLINE_ORDER",
  "comment": "Kann nicht liefern - angefordertes Material nicht mehr verfügbar"
}

Bearbeitung mit Kommentar:

{
  "change_type": "EDIT_ORDER",
  "comment": "Liefertermin nach Kundenanruf angepasst",
  "changes": {
    "planned_delivery_time": "2026-09-20T08:00:00Z"
  }
}

Optionales PDF (`pdf_base64`)

Feld	Typ	Pflicht	Beschreibung
`pdf_base64`	`string`	Nein	Base64-kodiertes PDF (max. 10 MB dekodiert)
`pdf_file_name`	`string`	Nein	Optionaler Dateiname für den gespeicherten Dokumenttitel

Das PDF kann zu jedem change_type mitgeschickt werden — z. B. Bestellung bestätigen und Auftragsbestätigung in einem Request. Identische PDFs werden per Content-Hash dedupliziert.

Editierbare Felder (nur `EDIT_ORDER`)

Feld	Typ	Beschreibung
`supplier_order_number`	`string`	Lieferanteneigene Bestellnummer
`planned_delivery_time`	`string` (ISO 8601)	Geplantes Lieferdatum
`comment`	`string`	Lieferantenkommentar zur Bestellung
`properties`	`object`	Frei strukturierte Zusatzinformationen (Shallow-Merge mit bestehenden `properties`)
`items`	`array`	Bestellpositionen — überschreibt die bestehende Positionsliste

Felder einer Position (`items[]`)

Feld	Typ	Beschreibung
`title`	`string`	Positionsbezeichnung
`quantity`	`number` (≥ 0)	Bestellmenge
`unit`	`string`	Mengeneinheit (`m3`, `t`, `kg`, `stk`, `h`, `pau`, …)
`description`	`string`	Optionale Detailbeschreibung
`product_number`	`string`	Produktnummer beim Lieferanten
`type`	`string`	Positionstyp
`marked`	`boolean`	Position als verifiziert markieren

Verhalten

Nur tatsächlich geänderte Felder werden geschrieben — übereinstimmende Werte werden serverseitig erkannt und übersprungen.
Werden in EDIT_ORDER keine echten Änderungen erkannt, antwortet der Endpunkt mit Keine Änderungen.
properties wird flach gemerged mit den bestehenden Werten; Schlüssel ohne neuen Wert bleiben erhalten.
items wird vollständig ersetzt, wenn das Feld in changes übergeben wird.
Bei jeder erfolgreichen Mutation wird automatisch eine Änderungsbenachrichtigung an das Bauunternehmen gesendet — comment wird in dieser Mail mitgeführt.

Response Codes

Code	Beschreibung
`200`	Bestellung erfolgreich aktualisiert oder keine Änderungen erkannt
`400`	Ungültige Eingabe — Validierung fehlgeschlagen
`401`	Nicht autorisiert — API-Schlüssel ist mit keinem Lieferanten verknüpft
`403`	Verboten — fehlender Scope `orders:write` oder Bestellung gehört einem anderen Lieferanten
`404`	Bestellung nicht gefunden / `id` ungültig
`500`	Interner Serverfehler

Autorisierungen

X-API-Key

string

header

erforderlich

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.

Scopes

orders:write

Pfadparameter

string<uuid>

erforderlich

Bestellungs-ID (UUID)

Body

application/json

change_type

enum<string>

erforderlich

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

Verfügbare Optionen:

CONFIRM_ORDER,

DECLINE_ORDER,

EDIT_ORDER,

CONFIRM_CANCEL_ORDER,

CONFIRM_ON_DEMAND,

RECEIVE_ORDER

comment

string

Optionaler Kommentar des Lieferanten zu dieser Änderung. Wird in der Benachrichtigung an das Bauunternehmen mitgesendet.

Maximum string length: 2000

changes

object

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.

Show child attributes

pdf_base64

string

Optionales base64-kodiertes PDF (roh oder mit data-URI-Präfix, max. 10 MB dekodiert)

pdf_file_name

string

Optionaler Dateiname für den Dokumenttitel bei pdf_base64

Antwort

Bestellung erfolgreich aktualisiert oder keine Änderungen erkannt

message

string

Menschenlesbare Statusmeldung; Keine Änderungen signalisiert, dass keine Mutation durchgeführt wurde.

Beispiel:

"Die aktualisierte Bestellung wurde an das Bauunternehmen gesendet."

error

string | null

Fehlermeldung, sofern aufgetreten (sonst null)

Beispiel:

null

Übersicht

Projekte

Lieferungen

Rechnungen

Rechnungs-Dimensionen

Lieferanten

Bestellungen

Bestellungen (Lieferanten)

Stammdaten

Q-Point Integration

Workflows

Kalender

IDS Aufträge

Lieferantenbestellung aktualisieren

Übersicht

Berechtigungen

Header

Pfadparameter

Änderungstypen (`change_type`)

Feld Supplier Comment (Lieferantenkommentar)

Beispiele

Optionales PDF (`pdf_base64`)

Editierbare Felder (nur `EDIT_ORDER`)

Felder einer Position (`items[]`)

Verhalten

Response Codes

Autorisierungen

Scopes

Pfadparameter

Body

Antwort

​Übersicht

​Berechtigungen

​Header

​Pfadparameter

​Änderungstypen (change_type)

​Feld Supplier Comment (Lieferantenkommentar)

​Beispiele

​Optionales PDF (pdf_base64)

​Editierbare Felder (nur EDIT_ORDER)

​Felder einer Position (items[])

​Verhalten

​Response Codes

Autorisierungen

Scopes

Pfadparameter

Body

Antwort

Übersicht

Berechtigungen

Header

Pfadparameter

Änderungstypen (`change_type`)

Feld Supplier Comment (Lieferantenkommentar)

Beispiele

Optionales PDF (`pdf_base64`)

Editierbare Felder (nur `EDIT_ORDER`)

Felder einer Position (`items[]`)

Verhalten

Response Codes