API Pakowania

Szybki start

1. Zaloguj się → kliknij swoją nazwę → API → wygeneruj klucz.
2. Wyślij zadanie pakowania (to działa w sandboxie — bezpłatnie w każdym planie):

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

Odpytaj status_url (z tym samym nagłówkiem autoryzacyjnym), aż status będzie "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/..."
  }
}

Punkty końcowe

Pola odpowiedzi

Obiekt result dla zakończonego zadania:

Wersjonowanie i stabilność

Kontrakt jest wersjonowany w ścieżce (/api/v1/). W ramach v1 zmiany są tylko dodawane — nowe opcjonalne pola żądania, nowe pola odpowiedzi, nowe kody pojazdów i kody błędów mogą się pojawić, a klienci powinni ignorować pola, których nie rozpoznają. Istniejące pola nigdy nie zmieniają znaczenia ani typu, a nic nie jest usuwane. Zmiana łamiąca oznacza nową ścieżkę wersji, przy czym v1 jest utrzymywana równolegle przez co najmniej 12 miesięcy, a o wycofaniu powiadamiamy e-mailem każdą przestrzeń roboczą z aktywnym kluczem.

Pola żądania

Pola przedmiotów

Kody pojazdów

Generowane na podstawie specyfikacji działającego silnika. Pojazdy niestandardowe z floty w Twojej przestrzeni roboczej działają poprzez custom_vehicle_id.

Ciężarówki i naczepy

Kontenery

Poziomy dostępu i limity

Liczone są tylko udane pakowania — nieudane walidacje i nieudane zadania nigdy nie są wliczane do limitu. Liczniki są resetowane 1. dnia miesiąca (UTC). Wyniki w środowisku sandbox są kompletne i nieograniczone — limity dotyczą jedynie dostępu, a nie funkcjonalności. Potrzebujesz więcej niż 5 000 pakowań miesięcznie? Skontaktuj się z nami w sprawie oferty dla dużych wolumenów i licencji OEM.

Webhooki

Przekaż callback_url, aby otrzymać wynik POST po zakończeniu zadania. Każde wywołanie zawiera X-Hansatic-Signature: HMAC-SHA256 treści surowego ciała z użyciem tajnego klucza webhooka (wyświetlanego jednokrotnie przy tworzeniu klucza). Zweryfikuj go:

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

Dostarczenie odbywa się w jednej próbie z limitem czasu 5 s — status_url zawsze pozostaje źródłem prawdy.

Błędy

Wszystkie błędy mają kształt { "error": { "code", "message", ... } } — czytelny dla maszyn kod, czytelna dla człowieka wiadomość oraz field, gdy winne jest konkretne pole wejściowe.