POST /api/case-design

探索產品外箱排列、TI-HI、卡板／貨櫃使用率同每件出貨成本。匿名每分鐘 10 次、每日 100 次；JSON 上限 32 KB。可用 X-API-Key 或 Authorization。GET 提供可執行範例。

請求：units 為 cm-kg 或 in-lb；product 包含 l,w,h,weight 及可選 keepUpright,label；unitsPerCase 為整數或 {min,max}。可選 caseConstraints、pallet、container、costs 同 candidates（1–10，預設 5）。GET 範例列出格式。

回應 found 或 none_within_search；候選方案包含排列、雙單位外箱尺寸同重量、卡板、貨櫃、可選成本分項、檢查同假設。頂層提供 checks、semantics、engineVersion、SHA-256 inputHash、notes、搜尋數目同限制。冇成本按每櫃件數再按卡板使用率排序；有成本按每件最低已填成本排序。缺少成本當零，每板同每櫃運費相加。可不填目的地，只篩選外箱。

最多平均抽樣 24 個件數（包括上下限）、400 個按 0.1 cm 尺寸去重嘅設計、2,000 個散裝箱。每箱件數 1–2,000。運輸保持箱直放、只計直柱疊法、最多疊兩板，卡板自重假設 25 kg。紙板每平方米 0.6 kg 係估算，預設每邊厚 0.4 cm、頂部空隙 0.5 cm。唔係 ECT/BCT 認證或最優證明。不可行方案會淘汰；冇可行結果會明示未評估。錯誤：400 輸入欄位、413 過大、415 格式、429 限流。

curl https://www.dimpack3d.com/api/case-design
curl https://www.dimpack3d.com/api/case-design -H 'Content-Type: application/json' --data-binary @case-design-request.json

訂單方案 — 慳返下一板

POST /api/order-options 接受 order-quote 請求加以下欄位。先用三種策略同四種貨品排序試原有數量；搵唔到更好砌法先試獲准嘅單 SKU 同雙 SKU 數量變更。最多回傳三個完整方案，依板數、變更件數絕對值、淨節省排序。卡板範圍、堆疊、包裝同收貨方限制全部不變。

• targetPalletCount: 整數 1–20；預設原板數減一，最少一板。屬目標：亦可能回傳未達目標嘅改善或唔加板嘅加貨方案。
• adjustments[]: {sku,minQty,maxQty,qtyStep?}: 預設所有 SKU 鎖定。SKU 必須存在而且唯一；範圍 0–200 要包含原數量；步幅預設 1，以原數量為起點。零代表整個 SKU 延後出貨；唔會回傳空貨運方案。
• searchBudget: 整數 1–200，預設 60；唔計基準報價。用盡額度會有 SEARCH_BUDGET 警告。只係搵到嘅最佳方案，唔係最佳化證明。
• economics: 可選填 palletFreight、handlingPerPallet、按 SKU 嘅 contributionPerUnit 同 deferralCostPerUnit、currency（三個大寫字母）。只用你提供嘅非負費用。淨節省 = 慳運費 + 慳處理費 − 延後貢獻利潤 − 延後出貨費。加貨利潤以負嘅延後利潤表示。欠所需費用會回 netSavings:null；冇費用請填零。

回應包含 baseline、target、searched、alternatives（連完整 quote、quantityChanges、candidateHash、economics 同 packing）、outcome、checks、semantics、notes、engineVersion、inputHash、tier；無效 key 另有 warning。內層報價同時回傳 cm/in 同 kg/lb。quoteOrder 亦接受 actuals.summary{actualPalletCount,selectedOptionId,measuredAt} 並喺 variance.summary 原樣回傳；measuredAt 係 ISO 時間。重現選中砌法可將 packing 連新數量交返 order-quote。

匿名：每分鐘 5 次、每日 50 次。JSON 內容最多 48 KB。GET 回傳例子；OPTIONS 支援 CORS、X-API-Key 同 Authorization。錯誤：400 驗證錯誤附 field、413 內容過大、415 內容類型錯誤、429 超額。檢查只屬篩查，唔係認證。

curl -s https://www.dimpack3d.com/api/order-options > order-options-help.json
curl -X POST https://www.dimpack3d.com/api/order-options -H 'Content-Type: application/json' --data-binary @order-options-request.json

訂單 → 卡板報價 API

POST /api/order-quote 係 order-plan 之上嘅報價流程封裝:明確單位(cm-kg 或 in-lb)、穩定 sku id、連板底同包裝嘅毛重、收貨方/承運商限制檢查(附假設)、inputHash + engineVersion、以及計費 id(每張訂單一次)。互動版連 CSV 匯入同預測 vs 實量記錄: /order-quote

status

complete — 全部箱已放入且所有限制通過。partial — maxPallets 內放唔晒;絕不可當整張訂單報價。needs_review — 已放入但某個限制(limits.maxLoadedHeight / maxGrossWeight)未通過;reviewReasons[] 指明。

pallets[].outerDims / grossWeight / checks[]

外高 = 板底 + 貨 + packagingAllowance.height;毛重 = 貨 + pallet.tareWeight + packagingAllowance.weight。兩種單位一併回傳。每項檢查都有 code、status(pass|fail|warn|not_evaluated)、observed、limit 同所用假設 — 冇檢查或 not_evaluated 從來唔等於通過。

inputHash / engineVersion / meter

規劃輸入(統一 cm/kg)嘅 SHA-256;單位制同 actuals 都唔會改變佢。同 hash + 同 engineVersion = 同結果。meter.unit 係 "order",meter.id 係你嘅 orderId(或 hash 前綴)— 付費方案嘅計費單位。

actuals

可選 { "0": { height, grossWeight, note } },以板序號為 key,用請求單位;回傳每板 variance(delta、deltaPct)。試點就係用呢個量度我哋。

限制

每張訂單 20 種箱型、200 箱、20 板、32 KB。匿名每 IP 10/分、100/日;免費 key 5 倍。GET 該 endpoint 可取得完整範例請求。

curl -s https://www.dimpack3d.com/api/order-quote | jq .request > order-quote-request.json
curl -X POST https://www.dimpack3d.com/api/order-quote \
  -H "Content-Type: application/json" -H "X-API-Key: dp_live_…" \
  --data-binary @order-quote-request.json | jq '{status, reviewReasons, summary, pallets: [.pallets[] | {outerDims, grossWeight, checks: [.checks[] | {code, status}]}]}'

估算卡板連底座高度

POST /api/pallet-estimate 比較三種擺法，回傳最佳方案。高度包含底座；partial 只代表已放入紙箱，並非整批訂單。結果不是已證明的最低高度。

舊版同步 API 只接受 cm/kg：卡板請求帶 units 欄位會被拒絕。回應提供 version，冇 engineVersion 或 inputHash。需要單位轉換同 SHA-256 識別請用 /api/order-quote。

{
  "pallet": {
    "l": 120,
    "w": 80,
    "baseHeight": 15,
    "maxHeight": 160,
    "maxWeight": 750
  },
  "items": [
    {
      "label": "Main cartons",
      "l": 60,
      "w": 40,
      "h": 30,
      "qty": 12,
      "weight": 8,
      "keepUpright": true
    },
    {
      "label": "Small cartons",
      "l": 40,
      "w": 30,
      "h": 20,
      "qty": 8,
      "weight": 4,
      "keepUpright": true
    }
  ]
}

pallet

l/w：底面；baseHeight：空板高度；maxHeight：連底座總高度上限；maxWeight：只計貨物的載重。cm/kg，必須提供限制。

items[]

必須提供 label、l/w/h、整數 qty、正數 weight 及布林 keepUpright。可選 maxStack 為上方容許重量，0 表示不可堆疊；未提供則不檢查紙箱承重。

status / loadedHeight / byItem / boxes

complete 表示全部放入；partial 表示尚有餘箱。loadedHeight 包含 baseHeight。byItem 列出訂購、已放入及剩餘數量。boxes 的 px/py/pz 為最小角位置，py 由板面起計。cargoWeight 不含空板重量。

限制與錯誤

每次 20 種 / 200 箱 / 32 KB。免費 Beta：設定限流儲存後每 IP 每分鐘 20 次、每日 200 次。400：JSON 或欄位錯誤；413：內容過大；415：類型錯誤；429：限流（Retry-After）。大量訂單請聯絡我們。