Yerləşdirmə API

Sürətli başlanğıc

1. Daxil olun → adınıza klikləyin → API → açar yaradın.
2. Yerləşdirmə tapşırığını göndərin (bu sınaq mühitində işləyir — hər plan üçün pulsuzdur):

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

status_url ünvanını sorğulayın (eyni autentifikasiya başlığı ilə) status "done" olana qədər:

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

Son nöqtələr

Cavab sahələri

Bitmiş tapşırıqda result obyekti:

Versiyalaşdırma və sabitlik

Kontrakt yolun içində versiyalaşdırılır (/api/v1/). v1 daxilində dəyişikliklər yalnız əlavə xarakter daşıyır — yeni seçimli sorğu sahələri, yeni cavab sahələri, yeni nəqliyyat vasitəsi kodları və səhv kodları əlavə edilə bilər, müştərilər tanımadıqları sahələri görməzlikdən gələ bilərlər. Mövcud sahələrin mənası və tipi heç vaxt dəyişmir, heç nə silinmir. Radikal dəyişiklik yeni versiya yolu deməkdir, v1 ən azı 12 ay paralel saxlanılır və aktiv açarı olan hər iş sahəsinə elektron poçtla ləğvetmə bildirişi göndərilir.

Sorğu sahələri

Əşya sahələri

Nəqliyyat vasitəsi kodları

Canlı mühərrik spesifikasiyalarından yaradılıb. İş sahənizin nəqliyyat parkından fərdi nəqliyyat vasitələri custom_vehicle_id ilə işləyir.

Yük maşınları və tirkərlər

Konteynerlər

Giriş səviyyələri və limitlər

Yalnız uğurlu paketlər hesaba alınır — yoxlanışda və ya işdə uğursuzluqlar kvotaya təsir etmir. Hər iki sayğac ayın 1-də (UTC) sıfırlanır. Sandbox nəticələri tam və məhdudiyyətsizdir — məhdudiyyətlər giriş qapısıdır, çıxış deyil. Aydan 5,000-dən çox paketə ehtiyacınız varsa, həcm və OEM qiymətləri haqqında bizimlə əlaqə saxlayın.

Vebxuklar

Tapşırıq bitdikdə nəticəni POST ilə almaq üçün callback_url ötürün. Hər vebxuk X-Hansatic-Signature daşıyır: xam gövdənin HMAC-SHA256 imzası açarınızın vebxuk sirri ilə (açar yaradılarkən bir dəfə göstərilir). Onu yoxlayın:

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

Çatdırılma bir cəhdlə 5 saniyə vaxt limitində həyata keçirilir — status_url həmişə həqiqət mənbəyidir.

Səhvlər

Bütün səhvlər { "error": { "code", "message", ... } } formasında olur — maşın oxunaqlı kod, insan oxunaqlı mesaj və səhvli giriş sahəsi göstərildikdə field.