Das Dokument order.v1

Jede Bestellung, die der Configurator erfasst, ist ein signiertes Dokument order.v1: der Workflow, in dem sie entstand, die Zuschnittliste, der Produktionsplan, das bepreiste Angebot mit seinem Token und ihre Herkunft. Es enthält keine personenbezogenen Daten, nur Ihre undurchsichtige customerRef.

Pfade, Feldnamen, Fehlercodes, Header-Namen und Codebeispiele bleiben englisch: Sie sind der Vertrag.

Regeln, die für jede Bestellung gelten

Jede Länge ist in Millimetern; unit ist nur die Anzeigeeinheit.
Jeder Betrag ist Money in ganzen kleinsten Währungseinheiten, und jede Währung entspricht der currency der Bestellung.
Eine Bestellung ist ein Workflow: workflow.mode bestimmt die Form der Zuschnittliste und des Plans (heute panel2d).
plan.planHash ist der SHA-256 des kanonischen Plans; das Angebots-Token bindet ihn, sodass ein geänderter Plan erkannt wird.
Das Dokument ist geschlossen und innerhalb von v1 nur erweiterbar: Neue Felder sind optional, nichts wird entfernt oder umbenannt.

Felder

Die Tabellen unten werden aus dem JSON Schema selbst erzeugt; dasselbe Schema ist unverändert in das OpenAPI-Dokument eingebettet.

Die Beschreibungen in dieser Tabelle stammen aus dem englischen Vertrag (dem JSON Schema oder dem OpenAPI-Dokument).

Order

Feld	Typ	Pflicht	Beschreibung
schemaVersion	1	ja	—
idempotencyKey	string	ja	The caller's replay key for POST /cfg/v1/order (P2-09): the same key returns the same order.
tenantId	string	ja	—
configVersion	integer	ja	The tenant-config snapshot this order was priced against. Capped at 2^53−1 (one JSON text per integer, so one hash / token claim per version).
workflow	Workflow	ja	—
customerRef	string	nein	Opaque reference into the merchant's own customer records. Never a name or an address.
customerGroup	string	nein	The tenant-config customer group the price list was chosen for.
locale	"en" \| "de" \| "it" \| "fr" \| "pl" \| "cs" \| "ro" \| "hu" \| "es" \| "hr"	ja	—
unit	"mm" \| "cm" \| "in"	ja	Display unit at ordering time; every length in this document is millimetres.
currency	string	ja	—
pricingMode	"platform" \| "external"	ja	—
createdAt	string	ja	—
expiresAt	string	ja	Quote validity; equals the token's exp.
source	Source	ja	—
cutList	CutPart[]	ja	MODE-DISCRIMINATED by workflow.mode (Order.allOf). One branch today: panel2d CutPart.
fullSheets	FullSheetItem[]	ja	Full stock units bought uncut. MODE-DISCRIMINATED; panel2d: whole sheets.
hardware	HardwareLine[]	ja	Mode-independent (catalogue hardware).
bondedPanels	BondedPanel[]	nein	Glued multi-layer panels (P5-05). MODE-DISCRIMINATED; panel2d only today. Shape may gain optional fields there; this is the v1 minimum.
plan	Plan	ja	MODE-DISCRIMINATED; the plan carries its own `mode` tag (= workflow.mode), covered by planHash.
quote	Quote	ja	—
shipping	OrderShipping	nein	—
files	FileRef[]	nein	—
signature	Signature	nein	—

Workflow

The tenant workflow this order was made in (tenant-config.v1 workflows[].id, or `default` for the implicit workflow). `mode` and `profile` are repeated so a consumer can dispatch without fetching the config; the quote token binds `id` and `mode`.

Feld	Typ	Pflicht	Beschreibung
id	string	ja	—
mode	"panel2d"	ja	A BUILT mode (x-cfg-modes.built). Reserved ⇒ `mode_unavailable`; unknown ⇒ `enum`.
profile	"furniture"	ja	—

Source

Provenance: which embed build collected the list, which engine version produced the plan, which config snapshot priced it.

Feld	Typ	Pflicht	Beschreibung
embedVersion	string	ja	—
engineVersion	string	ja	= plan.engineVersion (the Engine API's engineVersion).
configVersion	integer	ja	= $.configVersion.

CutPart

panel2d cut-list row = Engine API ApiPart2D (name, w, h, qty, rotatable, grain, grainGroup, priority, edgeBanding, material, meta) + the order's own id, group and machining. name/qty/material are REQUIRED here (optional on the API).

Feld	Typ	Pflicht	Beschreibung
id	string	ja	—
name	string	ja	No C0/C1 control characters (audit P7-01 F1: a newline in a name wrote DXF entities).
w	number	ja	The size the engine was given (after the tenant's dimension convention / edging deduction were applied).
h	number	ja	—
qty	integer	ja	—
material	string	ja	Catalogue MaterialItem.id (the API's material partition key).
rotatable	boolean	nein	—
grain	"w" \| "h"	nein	—
grainGroup	string	nein	—
priority	boolean	nein	—
edgeBanding	EdgeBanding	nein	—
meta	object	nein	Opaque passthrough (= ApiPart2D.meta), ≤ 2048 bytes canonical.
group	string	nein	Room / cabinet / project the customer assigned; printed on labels and exports.
machining	MachiningOp[]	nein	—

EdgeBanding

Per-edge banding TYPE references (catalogue EdgingItem.id); an absent side is not banded (= ApiPart2D.edgeBanding).

Feld	Typ	Pflicht	Beschreibung
top	string	nein	—
right	string	nein	—
bottom	string	nein	—
left	string	nein	—

MachiningOp

A machining operation on the part (catalogue MachiningType.id). `params` stays open in v1; P5-04 types its known keys additively (see params).

Feld	Typ	Pflicht	Beschreibung
typeId	string	ja	—
qty	integer	ja	—
params	object	nein	Open object; the KNOWN keys are typed (P5-04, additive): corner, measure, xMm, yMm, diameterMm, radiusMm, lengthMm, widthMm, depthMm. Per catalogue kind: hole/hinge = corner+measure+xMm+yMm+diameterMm[+depthMm]; groove = corner(top-left\|top-right)+xMm+lengthMm[+widthMm+depthMm]; radius = corner+radiusMm. Any other key stays valid.

FullSheetItem

Feld	Typ	Pflicht	Beschreibung
materialId	string	ja	—
w	number	ja	—
h	number	ja	—
qty	integer	ja	—

HardwareLine

Feld	Typ	Pflicht	Beschreibung
hardwareId	string	ja	—
qty	integer	ja	—

BondedPanel

Feld	Typ	Pflicht	Beschreibung
id	string	ja	—
w	number	ja	—
h	number	ja	—
qty	integer	ja	—
layers	BondedLayer[]	ja	—
name	string	nein	—

BondedLayer

Feld	Typ	Pflicht	Beschreibung
materialId	string	ja	—
thicknessMm	number	ja	—

Plan

The panel2d production plan as the Engine API returned it (ApiOptimize2DResponse fields), plus the `mode` tag and planHash. Numbers are the engine's own, in millimetres; sheets[].price / metrics.totalPrice are the engine's unit-less price fields, NOT money (prices live in `quote`).

Feld	Typ	Pflicht	Beschreibung
mode	"panel2d"	ja	The mode tag — INSIDE the plan so planHash covers it; must equal $.workflow.mode (D15).
engine	"heuristic" \| "balanced" \| "max"	ja	—
engineVersion	string	ja	—
deterministic	boolean	ja	—
sheets	Sheet[]	ja	—
metrics	Metrics2D	ja	—
cutPlan	array \| null	ja	null when the layout is not guillotine.
unplaced	Unplaced2D[]	ja	—
warnings	string[]	ja	—
guillotineValid	boolean	ja	—
planHash	string	ja	sha256 hex of canonicalize(plan without planHash) — RFC 8785; covers `mode`.

Sheet

= ApiSheet (types.ts).

Feld	Typ	Pflicht	Beschreibung
w	number	ja	—
h	number	ja	—
price	number \| null	ja	The engine's unit-less per-sheet price; the issuer passes null.
parts	PlacedPart2D[]	ja	—
offcuts	Rect[]	nein	—
material	string	nein	—
grain	"w" \| "h"	nein	—
meta	object	nein	—

PlacedPart2D

= ApiPlacedPart2D (types.ts).

Feld	Typ	Pflicht	Beschreibung
name	string	ja	—
x	number	ja	—
y	number	ja	—
w	number	ja	—
h	number	ja	—
rotated	boolean	ja	—
meta	object	nein	—

Rect

= ApiRect (types.ts).

Feld	Typ	Pflicht	Beschreibung
x	number	ja	—
y	number	ja	—
w	number	ja	—
h	number	ja	—

Metrics2D

= ApiMetrics2D (types.ts), unchanged: cutLines (collinear cuts merged), sawPasses (every strip crossed), cutLength (mm, convention-independent).

Feld	Typ	Pflicht	Beschreibung
sheetCount	integer	ja	—
yieldPct	number	ja	—
placed	integer	ja	—
total	integer	ja	—
cutLines	integer	ja	—
sawPasses	integer	ja	—
cutLength	number	ja	—
totalPrice	number	ja	—

CutStep

= ApiCutStep (types.ts): sheet is the 0-based index into plan.sheets, step restarts at 1 per sheet, stage is the 1-based machine pass.

Feld	Typ	Pflicht	Beschreibung
sheet	integer	ja	—
step	integer	ja	—
axis	"h" \| "v"	ja	—
pos	number	ja	—
length	number	ja	—
stage	integer	ja	—

Unplaced2D

= ApiUnplaced2D (types.ts).

Feld	Typ	Pflicht	Beschreibung
name	string	ja	—
w	number	ja	—
h	number	ja	—
qty	integer	ja	—

Quote

Feld	Typ	Pflicht	Beschreibung
priced	boolean	ja	false under pricingMode = external: lines carry quantities, every amount is 0.
lines	QuoteLine[]	ja	—
totals	Totals	ja	—
quoteToken	string	ja	See x-cfg-quote-token. The merchant's server verifies it with the tenant's key (P4-02 /quote/verify).

QuoteLine

Feld	Typ	Pflicht	Beschreibung
id	string	ja	—
type	"cutPart" \| "fullSheet" \| "hardware" \| "machining" \| "bondedPanel" \| "edging" \| "surcharge" \| "shipping" \| "tax"	ja	—
label	string	ja	—
qty	number	ja	Pieces, sheets, metres (edging) — the line's own unit.
unitAmount	Money	ja	—
amount	Money	ja	Line total after the tenant's rounding. Σ non-tax amounts = totals.net.
ref	LineRef	nein	—
meta	object	nein	—

LineRef

What the line prices. At least one id when present.

Feld	Typ	Pflicht	Beschreibung
partId	string	nein	—
materialId	string	nein	—
edgingId	string	nein	—
hardwareId	string	nein	—
machiningId	string	nein	—
zoneId	string	nein	—
ruleId	string	nein	—
bondedPanelId	string	nein	—

Totals

Feld	Typ	Pflicht	Beschreibung
net	Money	ja	—
tax	Money	ja	—
gross	Money	ja	—

Money

Feld	Typ	Pflicht	Beschreibung
amountMinor	integer	ja	—
currency	string	ja	—

OrderShipping

Ids only — the delivery address is the merchant shop's data, not the contract's.

Feld	Typ	Pflicht	Beschreibung
method	"delivery" \| "pickup"	ja	—
zoneId	string	nein	—
pickupLocationId	string	nein	—

FileRef

Feld	Typ	Pflicht	Beschreibung
kind	"pdf" \| "labels" \| "csv" \| "dxf" \| "svg" \| "xlsx" \| "json"	ja	—
url	string	ja	—
sha256	string	nein	—
bytes	integer	nein	—

Signature

HMAC-SHA256 over canonicalize(order without signature). keyId names the tenant key (P2-07: derived from a master, the DB holds only the id).

Feld	Typ	Pflicht	Beschreibung
alg	"HMAC-SHA256"	ja	—
keyId	string	ja	—
value	string	ja	—

Eine Schaltfläche "Ausprobieren" gibt es hier mit Absicht nicht: Der geheime Schlüssel gehört auf Ihren Server, nie in einen Browser. Der Demo-Shop zeigt Einbettung und Bestellübergabe von Anfang bis Ende.

Live-Demo-Shop öffnen CutOptim Configurator

RechtlichesKonfigurator-Bedingungen (EN) ·Auftragsverarbeitungsvertrag (EN) ·Datenschutzhinweis für Käufer ·Drittanbieter-Lizenzen (EN)