Le document order.v1

Chaque commande enregistrée par le Configurator est un document order.v1 signé : le workflow dans lequel elle a été créée, la liste de découpe, le plan de production, le devis chiffré avec son jeton, et son origine. Il ne contient aucune donnée personnelle, seulement votre customerRef opaque.

Les chemins, noms de champs, codes d’erreur, noms d’en-têtes et exemples de code restent en anglais : ils font partie du contrat.

Règles valables pour chaque commande

Toute longueur est en millimètres ; unit n’est que l’unité d’affichage.
Tout montant est un Money en unités mineures entières, et chaque devise est égale à la currency de la commande.
Une commande correspond à un workflow : workflow.mode choisit la forme de la liste de découpe et du plan (aujourd’hui panel2d).
plan.planHash est le SHA-256 du plan canonique ; le jeton de devis le lie, de sorte qu’un plan modifié est détecté.
Le document est fermé et uniquement additif au sein de la v1 : les nouveaux champs sont optionnels, rien n’est supprimé ni renommé.

Champs

Les tableaux ci-dessous sont générés à partir du schéma JSON lui-même ; le même schéma est intégré, tel quel, dans le document OpenAPI.

Les descriptions de ce tableau proviennent du contrat en anglais (le schéma JSON ou le document OpenAPI).

Order

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

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

Champ	Type	Obligatoire	Description
id	string	oui	—
mode	"panel2d"	oui	A BUILT mode (x-cfg-modes.built). Reserved ⇒ `mode_unavailable`; unknown ⇒ `enum`.
profile	"furniture"	oui	—

Source

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

Champ	Type	Obligatoire	Description
embedVersion	string	oui	—
engineVersion	string	oui	= plan.engineVersion (the Engine API's engineVersion).
configVersion	integer	oui	= $.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).

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

EdgeBanding

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

Champ	Type	Obligatoire	Description
top	string	non	—
right	string	non	—
bottom	string	non	—
left	string	non	—

MachiningOp

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

Champ	Type	Obligatoire	Description
typeId	string	oui	—
qty	integer	oui	—
params	object	non	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

Champ	Type	Obligatoire	Description
materialId	string	oui	—
w	number	oui	—
h	number	oui	—
qty	integer	oui	—

HardwareLine

Champ	Type	Obligatoire	Description
hardwareId	string	oui	—
qty	integer	oui	—

BondedPanel

Champ	Type	Obligatoire	Description
id	string	oui	—
w	number	oui	—
h	number	oui	—
qty	integer	oui	—
layers	BondedLayer[]	oui	—
name	string	non	—

BondedLayer

Champ	Type	Obligatoire	Description
materialId	string	oui	—
thicknessMm	number	oui	—

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

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

Sheet

= ApiSheet (types.ts).

Champ	Type	Obligatoire	Description
w	number	oui	—
h	number	oui	—
price	number \| null	oui	The engine's unit-less per-sheet price; the issuer passes null.
parts	PlacedPart2D[]	oui	—
offcuts	Rect[]	non	—
material	string	non	—
grain	"w" \| "h"	non	—
meta	object	non	—

PlacedPart2D

= ApiPlacedPart2D (types.ts).

Champ	Type	Obligatoire	Description
name	string	oui	—
x	number	oui	—
y	number	oui	—
w	number	oui	—
h	number	oui	—
rotated	boolean	oui	—
meta	object	non	—

Rect

= ApiRect (types.ts).

Champ	Type	Obligatoire	Description
x	number	oui	—
y	number	oui	—
w	number	oui	—
h	number	oui	—

Metrics2D

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

Champ	Type	Obligatoire	Description
sheetCount	integer	oui	—
yieldPct	number	oui	—
placed	integer	oui	—
total	integer	oui	—
cutLines	integer	oui	—
sawPasses	integer	oui	—
cutLength	number	oui	—
totalPrice	number	oui	—

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.

Champ	Type	Obligatoire	Description
sheet	integer	oui	—
step	integer	oui	—
axis	"h" \| "v"	oui	—
pos	number	oui	—
length	number	oui	—
stage	integer	oui	—

Unplaced2D

= ApiUnplaced2D (types.ts).

Champ	Type	Obligatoire	Description
name	string	oui	—
w	number	oui	—
h	number	oui	—
qty	integer	oui	—

Quote

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

QuoteLine

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

LineRef

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

Champ	Type	Obligatoire	Description
partId	string	non	—
materialId	string	non	—
edgingId	string	non	—
hardwareId	string	non	—
machiningId	string	non	—
zoneId	string	non	—
ruleId	string	non	—
bondedPanelId	string	non	—

Totals

Champ	Type	Obligatoire	Description
net	Money	oui	—
tax	Money	oui	—
gross	Money	oui	—

Money

Champ	Type	Obligatoire	Description
amountMinor	integer	oui	—
currency	string	oui	—

OrderShipping

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

Champ	Type	Obligatoire	Description
method	"delivery" \| "pickup"	oui	—
zoneId	string	non	—
pickupLocationId	string	non	—

FileRef

Champ	Type	Obligatoire	Description
kind	"pdf" \| "labels" \| "csv" \| "dxf" \| "svg" \| "xlsx" \| "json"	oui	—
url	string	oui	—
sha256	string	non	—
bytes	integer	non	—

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

Champ	Type	Obligatoire	Description
alg	"HMAC-SHA256"	oui	—
keyId	string	oui	—
value	string	oui	—

Il n’y a volontairement pas de bouton « essayer » ici : la clé secrète appartient à votre serveur, jamais à un navigateur. La boutique de démonstration montre l’intégration et la transmission de la commande de bout en bout.

Ouvrir la boutique de démonstration CutOptim Configurator

Mentions légalesConditions du configurateur (EN) ·Accord de traitement des données (EN) ·Notice de confidentialité pour les acheteurs ·Licences tierces (EN)