Nest linear parts onto stock bars
Solves a 1D bin-packing problem: given a set of part cut-lengths and a set of raw-stock bar lengths, decides how many bars are needed and which parts land on each bar, minimizing waste. Applies saw allowances (chuck at bar start, kerf per cut) and a per-stock remnant policy that governs whether leftover pieces are returned to inventory or billed as scrap.
Notes
- Response
PartIdvalues echo the caller-suppliedParts[].PartIdfrom the request when provided, otherwise a server-generated id. The id is an opaque correlation token — nothing on the server resolves it against a stored part.StockIdvalues are always server-generated. TotalNestedLength/TotalNestedWeightare proportional shares of the total stock consumed, allocated by each part's summed length. They include kerf + chuck; they are not simplyLength × TotalItemsNested.StockLayoutResponse.Parts[].QuantityandNumberOfPartsPerUnitare per single bar; multiply byNumberOfUnitsfor the aggregate count.
x-api-keyapplication/jsonField | Type | Required | Description |
|---|---|---|---|
| parts[] | object[] | Yes | Cut requirements: one entry per distinct part length + quantity. |
| parts[]. | uuid | null | No | Opaque caller-supplied correlation id, echoed on the corresponding
|
| parts[]. | string | No | Free-form display name echoed back on the corresponding
|
| parts[]. | number | No | Length of one cut piece, expressed in LengthUnit. |
| parts[]. | string | No | Length unit for Length (e.g. |
| parts[]. | integer | No | How many copies of this length are required. |
| product | object | Yes | The material grade being cut. Supplies weight-per-length so the total weight of cut pieces and stock consumed can be reported. |
| product. | string | No | Display name of the product (e.g. |
| product. | number | No | Weight of the product per unit of length. Combined with the layout's stock length to compute weight totals in the response. |
| product. | string | No | Unit for WeightPerLength (e.g. |
| stock[] | object[] | Yes | Available raw-stock bars: one entry per distinct stock length + quantity, each with its own remnant-keeping policy. |
| stock[]. | number | No | Length of one stock bar, expressed in LengthUnit. |
| stock[]. | string | No | Length unit for Length. |
| stock[]. | integer | null | No | How many bars of this length are available. Null means unlimited. |
| stock[]. | object | No | Rules for whether to keep the leftover piece from each bar (a "remnant") or discard it. |
| stock[]. | boolean | No | If |
| stock[]. | number | null | No | Minimum remnant length worth keeping. Ignored when
KeepRemnant is |
| stock[]. | string | No | Unit for MinimumLength. |
| stock[]. | number | null | No | Minimum remnant weight worth keeping. Ignored when
KeepRemnant is |
| stock[]. | string | No | Unit for MinimumWeight. |
| options | object | No | Machine allowances (chuck at bar start, kerf per cut). May be null; both allowances then default to 0. |
| options. | number | null | No | Chuck / grip allowance at the start of every stock bar — length that cannot be cut because it is held in the saw's chuck. |
| options. | string | No | Unit for Chuck. |
| options. | number | null | No | Kerf allowance — width of material the saw blade removes on each cut. |
| options. | string | No | Unit for Kerf. |
| outputLengthUnit | string | Yes | Length unit to use for all length values in the response.
Default: |
Status | When |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 500 | An unexpected error occurred on the server. |
Field | Type | Required | Description |
|---|---|---|---|
| data | object | null | No | Result of a linear-nesting calculation: which parts landed on which stock bars, and how much of each stock was consumed. |
| data. | uuid | No | Server-generated identifier for this nesting result. Pass it to
|
| data. | object[] | No | Per-part summary: one entry per distinct requested part length. |
| data. | uuid | No | Echo of the caller-supplied |
| data. | string | No | Echo of the caller-supplied |
| data. | number | No | The requested cut length, restated in the request's output length unit.
Send a 30 mm part on an inch nest and this reads |
| data. | string | No | The request's output length unit — not the unit the part was submitted in. Matches LengthUnit. |
| data. | integer | No | Echo of the requested quantity. Compare against TotalItemsNested to detect a shortfall when stock was exhausted before all pieces could be placed. |
| data. | integer | No | Actual number of pieces placed across all stock bars. Equals Quantity when stock was sufficient; less when it was not. |
| data. | number | No | This part's proportional share of total stock length consumed —
|
| data. | number | No | This part's proportional share of total stock weight consumed (same length-ratio allocation as TotalNestedLength). Includes waste (kerf + chuck) attributed to this part. |
| data. | number | No | Net material weight of the finished cut pieces for this part —
|
| data. | object[] | No | Per-stock-variant layout: one entry per distinct stock length. Each entry describes how one bar of that variant is cut, and how many bars were used. |
| data. | uuid | No | Server-generated identifier for this stock variant. The request DTO does not accept caller-supplied stock ids. |
| data. | boolean | No | Effective remnant decision for this layout: |
| data. | integer | No | Total number of parts placed on one bar of this variant. Same for every bar of the variant, since all use the same layout. |
| data. | integer | No | How many bars of this variant were consumed by the nesting. |
| data. | number | No | Total raw stock length allocated for this variant —
|
| data. | number | No | Total consumed stock length. When KeepRemnant is |
| data. | number | No | Weight of TotalStockLength at the product's
|
| data. | number | No | Weight of TotalStockLengthUsed at the product's
|
| data. | number | No | Length of one raw bar of this variant. |
| data. | number | No | Consumed length of one bar. Same remnant conditional as TotalStockLengthUsed. |
| data. | number | No | Weight of one raw bar. |
| data. | number | No | Weight of the consumed portion of one bar. |
| data. | string | No | Length unit used for every length field on this layout and in Parts. |
| data. | string | No | Weight unit used for every weight field on this layout. |
| data. | object[] | No | Parts placed on one bar of this variant. |
| data. | uuid | No | The PartId this row corresponds to. |
| data. | integer | No | Count of that part placed on a single bar of the owning stock variant. Multiply by the layout's NumberOfUnits for the aggregate count. |
| errors[] | object[] | null | No | One or more errors describing why the request failed. Absent ( |
| errors[]. | string | null | No | Human-readable explanation of the error. Intended for display to end users or logs. Wording is not stable and should not be branched on. |
| errors[]. | string | null | No | Machine-readable, stable error identifier. Consumers should branch on this value
rather than on Description. See |
| paging | object | null | No | Paging metadata for list endpoints. Absent on single-item responses. |
| paging. | integer | No | |
| paging. | integer | No | |
| paging. | integer | No |
{
"data": {
"nestingId": "11e99bc8-e511-474a-b049-938734f567db",
"parts": [
{
"partId": "08fcc2e5-7760-493b-b8f1-1ad26fcb0a9e",
"name": "string",
"length": 0.1,
"lengthUnit": "string",
"quantity": 0,
"totalItemsNested": 0,
"totalNestedLength": 0.1,
"totalNestedWeight": 0.1,
"totalTrueWeight": 0.1
}
],
"stock": [
{
"stockId": "a43dc3b0-820c-4762-b37b-45e91f17720c",
"keepRemnant": true,
"numberOfPartsPerUnit": 0,
"numberOfUnits": 0,
"totalStockLength": 0.1,
"totalStockLengthUsed": 0.1,
"totalStockWeight": 0.1,
"totalStockWeightUsed": 0.1,
"unitStockLength": 0.1,
"unitStockLengthUsed": 0.1,
"unitStockWeight": 0.1,
"unitStockWeightUsed": 0.1,
"lengthUnit": "string",
"weightUnit": "string",
"parts": [
{
"partId": "08fcc2e5-7760-493b-b8f1-1ad26fcb0a9e",
"quantity": 0
}
]
}
]
},
"errors": [
{
"description": "string",
"errorId": "string"
}
],
"paging": {
"limit": 0,
"start": 0,
"total": 0
}
}