El documento order.v1

Cada pedido que registra el configurador es un documento order.v1 firmado: el workflow en el que se creó, la lista de corte, el plan de producción, el presupuesto con precio y su token, y su procedencia. No contiene datos personales, solo tu customerRef opaco.

Las rutas, los nombres de campo, los códigos de error, los nombres de cabecera y los ejemplos de código se quedan en inglés: son el contrato.

Reglas que se cumplen en todos los pedidos

Toda longitud está en milímetros; unit es solo la unidad de visualización.
Todo importe es Money en unidades menores enteras y toda moneda es igual a la currency del pedido.
Un pedido es un workflow: workflow.mode selecciona la forma de la lista de corte y del plan (hoy panel2d).
plan.planHash es el SHA-256 del plan canónico; el token del presupuesto lo vincula, de modo que se detecta un plan modificado.
El documento es cerrado y solo aditivo dentro de v1: los campos nuevos son opcionales, no se quita ni se renombra nada.

Campos

Las tablas de abajo se generan a partir del propio JSON Schema; el mismo esquema está incluido, sin cambios, en el documento OpenAPI.

Las descripciones de esta tabla proceden del contrato en inglés (el JSON Schema o el documento OpenAPI).

Order

Campo	Tipo	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
materialId	string	sí	—
w	number	sí	—
h	number	sí	—
qty	integer	sí	—

HardwareLine

Campo	Tipo	Obligatorio	Descripción
hardwareId	string	sí	—
qty	integer	sí	—

BondedPanel

Campo	Tipo	Obligatorio	Descripción
id	string	sí	—
w	number	sí	—
h	number	sí	—
qty	integer	sí	—
layers	BondedLayer[]	sí	—
name	string	no	—

BondedLayer

Campo	Tipo	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
name	string	sí	—
w	number	sí	—
h	number	sí	—
qty	integer	sí	—

Quote

Campo	Tipo	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
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	Obligatorio	Descripción
net	Money	sí	—
tax	Money	sí	—
gross	Money	sí	—

Money

Campo	Tipo	Obligatorio	Descripción
amountMinor	integer	sí	—
currency	string	sí	—

OrderShipping

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

Campo	Tipo	Obligatorio	Descripción
method	"delivery" \| "pickup"	sí	—
zoneId	string	no	—
pickupLocationId	string	no	—

FileRef

Campo	Tipo	Obligatorio	Descripción
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	Obligatorio	Descripción
alg	"HMAC-SHA256"	sí	—
keyId	string	sí	—
value	string	sí	—

Aquí no hay un botón «probar» a propósito: la clave secreta pertenece a tu servidor, nunca a un navegador. La tienda demo muestra la incrustación y el traspaso del pedido funcionando de principio a fin.

Abrir la tienda demo en vivo CutOptim Configurador

Información legalCondiciones del configurador (EN) ·Contrato de encargo de tratamiento (EN) ·Aviso de privacidad para compradores ·Licencias de terceros (EN)