Packing API

Guida rapida

1. Accedi → clicca sul tuo nome → API → genera una chiave.
2. Invia un job di packing (questo viene eseguito in sandbox — gratuito su ogni piano):

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

Interroga status_url (stesso header di autenticazione) finché status non è "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/..."
  }
}

Endpoint

Campi della risposta

L'oggetto result di un job completato:

Versionamento e stabilità

Il contratto è versionato nel percorso (/api/v1/). All'interno di v1, le modifiche sono solo additive — nuovi campi opzionali nella richiesta, nuovi campi nella risposta, nuovi codici di veicoli e codici di errore possono apparire, e i client devono ignorare i campi che non riconoscono. I campi esistenti non cambiano mai significato o tipo, e nulla viene rimosso. Una modifica breaking comporta un nuovo percorso di versione, con v1 mantenuto in parallelo per almeno 12 mesi e avviso di deprecazione inviato via email a ogni workspace con una chiave attiva.

Campi della richiesta

Campi degli articoli

Codici veicolo

Generati dalle specifiche del motore live. I veicoli personalizzati dalla flotta del tuo workspace funzionano tramite custom_vehicle_id.

Camion e rimorchi

Container

Livelli di accesso e limiti

Vengono conteggiati solo gli imballaggi riusciti — le validazioni fallite e i job non completati non vengono addebitati sulla quota. Entrambi i contatori si azzerano il 1° del mese (UTC). I risultati della sandbox sono completi e non limitati — il limite riguarda l'accesso, non l'output. Hai bisogno di più di 5.000 imballaggi al mese? Contattaci per soluzioni su volumi elevati e prezzi OEM.

Webhook

Passa callback_url per ricevere il risultato tramite POST al completamento del job. Ogni callback include X-Hansatic-Signature: un HMAC-SHA256 del corpo grezzo con il segreto webhook della tua chiave (mostrato una sola volta alla creazione della chiave). Verificalo:

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

La consegna avviene con un singolo tentativo e timeout di 5s — status_url rimane sempre la fonte di verità.

Errori

Tutti gli errori sono { "error": { "code", "message", ... } } — codice leggibile dalla macchina, messaggio leggibile dall'utente e field quando un input specifico è errato.