Kubova REST API

每个请求都需要在 Authorization 标头中提供 API 密钥：

Authorization: Bearer kbv_abc123...

在 Pro 套餐后从仪表板生成密钥。

在发送打包请求之前，使用 /me 端点确认您的密钥有效：

curl https://kubova.com/api/v1/me \
  -H "Authorization: Bearer kbv_..."

POST 到 /api/v1/pack 与货物和集装箱。打包器返回每个集装箱的放置、已用体积和任何未放置的件。

curl -X POST https://kubova.com/api/v1/pack \
  -H "Authorization: Bearer kbv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cargos": [{
      "id": "sku-a",
      "name": "Box A",
      "shape": "box",
      "lengthCm": 50, "widthCm": 40, "heightCm": 30,
      "quantity": 20,
      "weightKg": 5,
      "color": "#e85d3a",
      "includeInLoading": true,
      "allowStacking": true,
      "allowRotation": true
    }],
    "container": {
      "id": "40hc",
      "name": "40HC",
      "innerLengthCm": 1203.0,
      "innerWidthCm": 235.2,
      "innerHeightCm": 269.7,
      "doorWidthCm": 233.5,
      "doorHeightCm": 258.5,
      "maxPayloadKg": 26330
    },
    "options": {
      "loadingDirection": "floor-to-top",
      "vnsTimeLimitMs": 5000
    }
  }'

成功返回 ok=true 包含 result.containers 和 result.unplaced。错误返回 ok=false 包含 error 字符串。

POST 到 /api/v1/report，与 /pack 相同的 body 结构。format=json 返回每个集装箱的 base64 PDF + 3D PNG；format=binary 流式返回可直接保存的合并 PDF。

# JSON response: base64 PDF + 3D PNG per container
curl -X POST https://kubova.com/api/v1/report \
  -H "Authorization: Bearer kbv_..." \
  -H "Content-Type: application/json" \
  -d '{ "cargos": [...], "container": {...}, "format": "json" }'

# Binary response: a single combined PDF
curl -X POST "https://kubova.com/api/v1/report?format=binary" \
  -H "Authorization: Bearer kbv_..." \
  -H "Content-Type: application/json" \
  -d '{ "cargos": [...], "container": {...} }' \
  --output kubova-report.pdf

需要密钥上的 report 范围。新密钥默认带有 pack 和 report 两者。

• 默认每个密钥每分钟 60 个请求（每个密钥可按需配置）。
• 打包请求 290 秒后超时。覆盖目前所见的所有工作负载；异步作业模式将在真实用户触及上限时推出。
• 每个密钥都有范围集 (pack, report)。/pack 端点需要 pack 范围。
• API 访问在 Pro 套餐及以上可用。