Kubova REST-API

Jede Anfrage benötigt einen API-Schlüssel im Authorization-Header:

Authorization: Bearer kbv_abc123...

Generieren Sie Schlüssel im Dashboard, sobald Sie den Pro-Tarif nutzen.

Verwenden Sie den Endpunkt /me, um zu bestätigen, dass Ihr Schlüssel gültig ist, bevor Sie Pack-Anfragen senden:

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

POST an /api/v1/pack mit Fracht und einem Container. Der Packer gibt die Platzierungen pro Container, das genutzte Volumen und alle nicht platzierten Stücke zurück.

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
    }
  }'

Bei Erfolg wird ok=true mit result.containers und result.unplaced zurückgegeben. Bei Fehlern wird ok=false mit einer Fehlermeldung zurückgegeben.

POST an /api/v1/report mit derselben Struktur wie /pack. format=json gibt ein base64-PDF + 3D-PNG pro Container zurück; format=binary streamt ein einzelnes kombiniertes PDF, das Sie direkt speichern können.

# 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

Erfordert die Berechtigung „report“ für den Schlüssel. Neue Schlüssel werden standardmäßig mit „pack“ und „report“ ausgeliefert.

• Standardmäßig 60 Anfragen pro Minute und Schlüssel (auf Anfrage pro Schlüssel konfigurierbar).
• Pack-Anfragen laufen nach 290 Sekunden ab. Das deckt alle bisherigen Arbeitslasten ab; das asynchrone Job-Muster wird eingeführt, sobald echte Benutzer an diese Grenze stoßen.
• Jeder Schlüssel hat einen Berechtigungssatz (pack, report). Der Endpunkt /pack benötigt die Berechtigung „pack“.
• Der API-Zugriff ist ab dem Pro-Tarif verfügbar.