Packing API

Quick start

1. Sign in → click your name → API → generate a key.
2. Submit a pack job (this one runs in sandbox — free on every plan):

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-..."
}

Poll the status_url (same auth header) until status is "done":

{
  "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/..."
  }
}

Endpoints

Response fields

The result object on a finished job:

Versioning & stability

The contract is versioned in the path (/api/v1/). Within v1, changes are additive only — new optional request fields, new response fields, new vehicle codes and error codes may appear, and clients should ignore fields they don't recognize. Existing fields never change meaning or type, and nothing is removed. A breaking change means a new version path, with v1 maintained in parallel for at least 12 months and deprecation notice by email to every workspace with an active key.

Request fields

Item fields

Vehicle codes

Generated from the live engine specs. Custom vehicles from your workspace fleet work via custom_vehicle_id.

Trucks & trailers

Containers

Access levels & limits

Only successful packs count — failed validation and failed jobs never bill against a quota. Both counters reset on the 1st (UTC). Sandbox results are complete and uncrippled — the limits are the gate, not the output. Need more than 5,000 packs a month? Talk to us about volume and OEM pricing.

Webhooks

Pass callback_url to receive the result via POST when the job completes. Every callback carries X-Hansatic-Signature: an HMAC-SHA256 of the raw body with your key's webhook secret (shown once at key creation). Verify it:

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));
}

Delivery is one attempt with a 5s timeout — the status_url always remains the source of truth.

Errors

All errors are { "error": { "code", "message", ... } } — machine-readable code, human-readable message, and field when a specific input is at fault.