Packing API

Schnellstart

1. Melden Sie sich an → klicken Sie auf Ihren Namen → API → generieren Sie einen Schlüssel.
2. Senden Sie einen Pack-Job ab (dieser läuft in der Sandbox — kostenlos in jedem Tarif):

curl -X POST https://hansatic.com/api/v1/pack \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle": "CURTAINSIDER_136",
    "objective": "ldm",
    "sandbox": true,
    "items": [{
      "name": "Machine crate",
      "length": 2300, "width": 750, "height": 1400,
      "weight": 300, "quantity": 7,
      "stackable": false, "tiltable": false
    }]
  }'

{
  "job_id": "5e3617d1-abe4-4549-b7e6-d18c6baf814f",
  "status": "queued",
  "sandbox": true,
  "status_url": "https://hansatic.com/api/v1/jobs/5e3617d1-..."
}

Fragen Sie die status_url ab (gleicher Auth-Header), bis status "done" ist:

{
  "job_id": "5e3617d1-...",
  "status": "done",
  "result": {
    "placed_count": 7,
    "unplaced_count": 0,
    "units": "metric",
    "metrics": {
      "ldm_m": 5.25,
      "span_mm": 5250,
      "linear_ft": 17.2,
      "pallet_positions_eur": 14,
      "total_weight_kg": 2100,
      "overlaps": 0
    },
    "items": [
      { "id": "...", "name": "Machine crate", "placed": true,
        "x": 8370, "y": 0, "z": 0,
        "rotation_deg": 90, "tilt_deg": 0, "...": "..." }
    ],
    "plan_url": "https://hansatic.com/en/app/plans/..."
  }
}

Endpunkte

Antwortfelder

Das result-Objekt eines abgeschlossenen Jobs:

Versionierung & Stabilität

Der Vertrag ist in der Pfadangabe (/api/v1/) versioniert. Innerhalb von v1 sind Änderungen nur additiv — neue optionale Anfragefelder, neue Antwortfelder, neue Fahrzeugcodes und Fehlercodes können hinzugefügt werden, und Clients sollten Felder ignorieren, die sie nicht kennen. Bestehende Felder ändern niemals ihre Bedeutung oder ihren Typ, und nichts wird entfernt. Eine Breaking Change führt zu einem neuen Versionspfad, wobei v1 mindestens 12 Monate parallel gepflegt und die Abschaltung per E-Mail an jeden Arbeitsbereich mit einem aktiven Schlüssel angekündigt wird.

Anfragefelder

Artikelfelder

Fahrzeugcodes

Generiert aus den Live-Engine-Spezifikationen. Benutzerdefinierte Fahrzeuge aus Ihrer Arbeitsbereichsflotte funktionieren über custom_vehicle_id.

LKW & Anhänger

Container

Zugriffsebenen & Limits

Nur erfolgreiche Packungen werden gezählt – fehlgeschlagene Validierungen und Jobs belasten das Kontingent nicht. Beide Zähler werden am 1. (UTC) zurückgesetzt. Sandbox-Ergebnisse sind vollständig und uneingeschränkt – die Limits sind die Grenze, nicht die Ausgabe. Brauchen Sie mehr als 5.000 Packungen pro Monat? Sprechen Sie mit uns über Volumen- und OEM-Preise.

Webhooks

Geben Sie callback_url an, um das Ergebnis per POST zu erhalten, wenn der Job abgeschlossen ist. Jeder Callback enthält eine X-Hansatic-Signature: ein HMAC-SHA256 der Rohdaten mit dem Webhook-Geheimnis Ihres Schlüssels (wird einmalig bei der Schlüsselerstellung angezeigt). Überprüfen Sie diese:

const crypto = require('crypto');

function verify(rawBody, signatureHeader, webhookSecret) {
  const expected = crypto.createHmac('sha256', webhookSecret)
    .update(rawBody).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signatureHeader));
}

Die Zustellung erfolgt in einem Versuch mit 5s Timeout — die status_url bleibt immer die Quelle der Wahrheit.

Fehler

Alle Fehler haben die Form { "error": { "code", "message", ... } } — maschinenlesbarer Code, menschenlesbare Nachricht und field, wenn ein bestimmtes Eingabefeld fehlerhaft ist.