Kubova REST API

すべてのリクエストの Authorization ヘッダーにAPIキーを含める必要があります。

Authorization: Bearer kbv_abc123...

Proプランにアップグレード後、ダッシュボードからキーを生成してください。

積載リクエストを送信する前に、/me エンドポイントを使用してキーが有効であることを確認します。

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

貨物情報とコンテナ情報を指定して /api/v1/pack にPOSTします。シミュレーターは、コンテナごとの配置、使用容量、および配置できなかった貨物を返します。

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 とエラー文字列を返します。

/pack と同じボディ形式で /api/v1/report にPOSTします。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プラン以上でご利用いただけます。