API de Planificare a Încărcăturii

Începeți rapid

1. Autentificați-vă → faceți clic pe numele dvs. → API → generați o cheie.
2. Trimiteți o cerere de planificare (aceasta rulează în sandbox — gratuit pe fiecare 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-..."
}

Interogați status_url (cu același antet de autentificare) până când status este "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-uri

Câmpuri de răspuns

Obiectul result pentru o cerere finalizată:

Versiuni și stabilitate

Contractul este versionat în calea (/api/v1/). În cadrul v1, modificările sunt doar aditive — noi câmpuri opționale în cerere, noi câmpuri în răspuns, noi coduri de vehicule și coduri de eroare pot apărea, iar clienții trebuie să ignore câmpurile pe care nu le recunosc. Câmpurile existente nu își schimbă niciodată semnificația sau tipul, iar nimic nu este eliminat. O modificare incompatibilă înseamnă o nouă cale de versiune, cu v1 menținut în paralel timp de cel puțin 12 luni și notificare de depreciere prin e-mail către fiecare spațiu de lucru cu o cheie activă.

Câmpuri de cerere

Câmpuri pentru articole

Coduri de vehicule

Generate din specificațiile motorului live. Vehiculele personalizate din flota spațiului dvs. de lucru funcționează prin custom_vehicle_id.

Camioane și remorci

Containere

Nivele de acces și limite

Sunt luate în calcul doar planificările reușite — validările eșuate și sarcinile nereușite nu sunt facturate la cota lunară. Ambele contoare se resetează pe data de 1 (UTC). Rezultatele din mediul Sandbox sunt complete și nealterate — limitele reprezintă pragul de acces, nu calitatea ieșirii. Aveți nevoie de peste 5.000 de planificări pe lună? Discutați cu noi despre tarifele pentru volume mari și parteneriate OEM.

Webhook-uri

Trimiteți callback_url pentru a primi rezultatul prin POST la finalizarea cererii. Fiecare callback include X-Hansatic-Signature: un HMAC-SHA256 al corpului brut cu secretul webhook-ului cheii dvs. (afișat o singură dată la crearea cheii). Verificați-l:

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

Livrarea se face într-o singură încercare cu timeout de 5s — status_url rămâne întotdeauna sursa de adevăr.

Erori

Toate erorile sunt de forma { "error": { "code", "message", ... } } — cod citibil de mașină, mesaj lizibil pentru om și field când un anumit câmp de intrare este defect.