Il documento order.v1

Ogni ordine registrato dal Configurator è un documento order.v1 firmato: il flusso di lavoro in cui è stato creato, la distinta di taglio, il piano di produzione, il preventivo con il suo token e la sua provenienza. Non contiene dati personali, solo il tuo customerRef opaco.

Percorsi, nomi dei campi, codici di errore, nomi degli header ed esempi di codice restano in inglese: sono il contratto.

Regole valide per ogni ordine

Ogni lunghezza è in millimetri; unit è solo l'unità di visualizzazione.
Ogni importo è Money in unità minori intere, e ogni valuta è uguale alla currency dell'ordine.
Un ordine è un flusso di lavoro: workflow.mode seleziona la forma della distinta di taglio e del piano (oggi panel2d).
plan.planHash è lo SHA-256 del piano canonico; il token del preventivo lo vincola, quindi un piano modificato viene rilevato.
Il documento è chiuso e solo additivo nella v1: i nuovi campi sono opzionali, nulla viene rimosso o rinominato.

Campi

Le tabelle qui sotto sono generate dal JSON Schema stesso; lo stesso schema è incorporato, invariato, nel documento OpenAPI.

Le descrizioni di questa tabella provengono dal contratto in inglese (il JSON Schema o il documento OpenAPI).

Order

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

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

Campo	Tipo	Obbligatorio	Descrizione
id	string	sì	—
mode	"panel2d"	sì	A BUILT mode (x-cfg-modes.built). Reserved ⇒ `mode_unavailable`; unknown ⇒ `enum`.
profile	"furniture"	sì	—

Source

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

Campo	Tipo	Obbligatorio	Descrizione
embedVersion	string	sì	—
engineVersion	string	sì	= plan.engineVersion (the Engine API's engineVersion).
configVersion	integer	sì	= $.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).

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

EdgeBanding

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

Campo	Tipo	Obbligatorio	Descrizione
top	string	no	—
right	string	no	—
bottom	string	no	—
left	string	no	—

MachiningOp

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

Campo	Tipo	Obbligatorio	Descrizione
typeId	string	sì	—
qty	integer	sì	—
params	object	no	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

Campo	Tipo	Obbligatorio	Descrizione
materialId	string	sì	—
w	number	sì	—
h	number	sì	—
qty	integer	sì	—

HardwareLine

Campo	Tipo	Obbligatorio	Descrizione
hardwareId	string	sì	—
qty	integer	sì	—

BondedPanel

Campo	Tipo	Obbligatorio	Descrizione
id	string	sì	—
w	number	sì	—
h	number	sì	—
qty	integer	sì	—
layers	BondedLayer[]	sì	—
name	string	no	—

BondedLayer

Campo	Tipo	Obbligatorio	Descrizione
materialId	string	sì	—
thicknessMm	number	sì	—

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

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

Sheet

= ApiSheet (types.ts).

Campo	Tipo	Obbligatorio	Descrizione
w	number	sì	—
h	number	sì	—
price	number \| null	sì	The engine's unit-less per-sheet price; the issuer passes null.
parts	PlacedPart2D[]	sì	—
offcuts	Rect[]	no	—
material	string	no	—
grain	"w" \| "h"	no	—
meta	object	no	—

PlacedPart2D

= ApiPlacedPart2D (types.ts).

Campo	Tipo	Obbligatorio	Descrizione
name	string	sì	—
x	number	sì	—
y	number	sì	—
w	number	sì	—
h	number	sì	—
rotated	boolean	sì	—
meta	object	no	—

Rect

= ApiRect (types.ts).

Campo	Tipo	Obbligatorio	Descrizione
x	number	sì	—
y	number	sì	—
w	number	sì	—
h	number	sì	—

Metrics2D

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

Campo	Tipo	Obbligatorio	Descrizione
sheetCount	integer	sì	—
yieldPct	number	sì	—
placed	integer	sì	—
total	integer	sì	—
cutLines	integer	sì	—
sawPasses	integer	sì	—
cutLength	number	sì	—
totalPrice	number	sì	—

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.

Campo	Tipo	Obbligatorio	Descrizione
sheet	integer	sì	—
step	integer	sì	—
axis	"h" \| "v"	sì	—
pos	number	sì	—
length	number	sì	—
stage	integer	sì	—

Unplaced2D

= ApiUnplaced2D (types.ts).

Campo	Tipo	Obbligatorio	Descrizione
name	string	sì	—
w	number	sì	—
h	number	sì	—
qty	integer	sì	—

Quote

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

QuoteLine

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

LineRef

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

Campo	Tipo	Obbligatorio	Descrizione
partId	string	no	—
materialId	string	no	—
edgingId	string	no	—
hardwareId	string	no	—
machiningId	string	no	—
zoneId	string	no	—
ruleId	string	no	—
bondedPanelId	string	no	—

Totals

Campo	Tipo	Obbligatorio	Descrizione
net	Money	sì	—
tax	Money	sì	—
gross	Money	sì	—

Money

Campo	Tipo	Obbligatorio	Descrizione
amountMinor	integer	sì	—
currency	string	sì	—

OrderShipping

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

Campo	Tipo	Obbligatorio	Descrizione
method	"delivery" \| "pickup"	sì	—
zoneId	string	no	—
pickupLocationId	string	no	—

FileRef

Campo	Tipo	Obbligatorio	Descrizione
kind	"pdf" \| "labels" \| "csv" \| "dxf" \| "svg" \| "xlsx" \| "json"	sì	—
url	string	sì	—
sha256	string	no	—
bytes	integer	no	—

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

Campo	Tipo	Obbligatorio	Descrizione
alg	"HMAC-SHA256"	sì	—
keyId	string	sì	—
value	string	sì	—

Qui non c'è un pulsante "provalo" di proposito: la chiave segreta appartiene al tuo server, mai a un browser. Lo shop demo mostra l'incorporamento e il passaggio dell'ordine in funzione da un capo all'altro.

Apri lo shop demo dal vivo CutOptim Configurator

Note legaliCondizioni del configuratore (EN) ·Accordo sul trattamento dei dati (EN) ·Informativa privacy per gli acquirenti ·Licenze di terze parti (EN)