Dokument order.v1

Każde zamówienie zapisane przez Configurator to jeden podpisany dokument order.v1: przepływ, w którym powstało, lista formatek, plan produkcji, wycena z cenami wraz z tokenem oraz informacja, skąd pochodzi. Nie zawiera danych osobowych, tylko Twój nieprzejrzysty customerRef.

Ścieżki, nazwy pól, kody błędów, nazwy nagłówków i przykłady kodu pozostają po angielsku: to jest kontrakt.

Zasady obowiązujące w każdym zamówieniu

Każda długość jest w milimetrach; unit to tylko jednostka wyświetlania.
Każda kwota to Money w całych jednostkach podstawowych, a każda waluta jest równa currency zamówienia.
Jedno zamówienie to jeden przepływ: workflow.mode wybiera kształt listy formatek i planu (obecnie panel2d).
plan.planHash to SHA-256 planu kanonicznego; token wyceny go wiąże, więc zmieniony plan zostanie wykryty.
Dokument jest zamknięty i w v1 tylko addytywny: nowe pola są opcjonalne, nic nie jest usuwane ani przemianowywane.

Pola

Tabele poniżej są generowane z samego schematu JSON; ten sam schemat jest osadzony bez zmian w dokumencie OpenAPI.

Opisy w tej tabeli pochodzą z angielskiego kontraktu (schematu JSON lub dokumentu OpenAPI).

Order

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

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

Pole	Typ	Wymagane	Opis
id	string	tak	—
mode	"panel2d"	tak	A BUILT mode (x-cfg-modes.built). Reserved ⇒ `mode_unavailable`; unknown ⇒ `enum`.
profile	"furniture"	tak	—

Source

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

Pole	Typ	Wymagane	Opis
embedVersion	string	tak	—
engineVersion	string	tak	= plan.engineVersion (the Engine API's engineVersion).
configVersion	integer	tak	= $.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).

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

EdgeBanding

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

Pole	Typ	Wymagane	Opis
top	string	nie	—
right	string	nie	—
bottom	string	nie	—
left	string	nie	—

MachiningOp

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

Pole	Typ	Wymagane	Opis
typeId	string	tak	—
qty	integer	tak	—
params	object	nie	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

Pole	Typ	Wymagane	Opis
materialId	string	tak	—
w	number	tak	—
h	number	tak	—
qty	integer	tak	—

HardwareLine

Pole	Typ	Wymagane	Opis
hardwareId	string	tak	—
qty	integer	tak	—

BondedPanel

Pole	Typ	Wymagane	Opis
id	string	tak	—
w	number	tak	—
h	number	tak	—
qty	integer	tak	—
layers	BondedLayer[]	tak	—
name	string	nie	—

BondedLayer

Pole	Typ	Wymagane	Opis
materialId	string	tak	—
thicknessMm	number	tak	—

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`).

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

Sheet

= ApiSheet (types.ts).

Pole	Typ	Wymagane	Opis
w	number	tak	—
h	number	tak	—
price	number \| null	tak	The engine's unit-less per-sheet price; the issuer passes null.
parts	PlacedPart2D[]	tak	—
offcuts	Rect[]	nie	—
material	string	nie	—
grain	"w" \| "h"	nie	—
meta	object	nie	—

PlacedPart2D

= ApiPlacedPart2D (types.ts).

Pole	Typ	Wymagane	Opis
name	string	tak	—
x	number	tak	—
y	number	tak	—
w	number	tak	—
h	number	tak	—
rotated	boolean	tak	—
meta	object	nie	—

Rect

= ApiRect (types.ts).

Pole	Typ	Wymagane	Opis
x	number	tak	—
y	number	tak	—
w	number	tak	—
h	number	tak	—

Metrics2D

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

Pole	Typ	Wymagane	Opis
sheetCount	integer	tak	—
yieldPct	number	tak	—
placed	integer	tak	—
total	integer	tak	—
cutLines	integer	tak	—
sawPasses	integer	tak	—
cutLength	number	tak	—
totalPrice	number	tak	—

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.

Pole	Typ	Wymagane	Opis
sheet	integer	tak	—
step	integer	tak	—
axis	"h" \| "v"	tak	—
pos	number	tak	—
length	number	tak	—
stage	integer	tak	—

Unplaced2D

= ApiUnplaced2D (types.ts).

Pole	Typ	Wymagane	Opis
name	string	tak	—
w	number	tak	—
h	number	tak	—
qty	integer	tak	—

Quote

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

QuoteLine

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

LineRef

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

Pole	Typ	Wymagane	Opis
partId	string	nie	—
materialId	string	nie	—
edgingId	string	nie	—
hardwareId	string	nie	—
machiningId	string	nie	—
zoneId	string	nie	—
ruleId	string	nie	—
bondedPanelId	string	nie	—

Totals

Pole	Typ	Wymagane	Opis
net	Money	tak	—
tax	Money	tak	—
gross	Money	tak	—

Money

Pole	Typ	Wymagane	Opis
amountMinor	integer	tak	—
currency	string	tak	—

OrderShipping

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

Pole	Typ	Wymagane	Opis
method	"delivery" \| "pickup"	tak	—
zoneId	string	nie	—
pickupLocationId	string	nie	—

FileRef

Pole	Typ	Wymagane	Opis
kind	"pdf" \| "labels" \| "csv" \| "dxf" \| "svg" \| "xlsx" \| "json"	tak	—
url	string	tak	—
sha256	string	nie	—
bytes	integer	nie	—

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

Pole	Typ	Wymagane	Opis
alg	"HMAC-SHA256"	tak	—
keyId	string	tak	—
value	string	tak	—

Nie ma tu przycisku „wypróbuj” celowo: klucz tajny należy do Twojego serwera, nigdy do przeglądarki. Sklep demonstracyjny pokazuje osadzenie i przekazanie zamówienia działające od początku do końca.

Otwórz sklep demonstracyjny CutOptim Configurator

Informacje prawneWarunki konfiguratora (EN) ·Umowa powierzenia przetwarzania danych (EN) ·Informacja o prywatności dla kupujących ·Licencje stron trzecich (EN)