Packing API

Bắt đầu nhanh

1. Đăng nhập → nhấp vào tên của bạn → API → tạo khóa.
2. Gửi một yêu cầu xếp hàng (yêu cầu này chạy trong môi trường thử nghiệm — miễn phí trên mọi gói dịch vụ):

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

Kiểm tra liên tục status_url (với cùng tiêu đề xác thực) cho đến khi status là "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/..."
  }
}

Điểm cuối API

Các trường trong phản hồi

Đối tượng result của một công việc đã hoàn thành:

Phiên bản & tính ổn định

Hợp đồng được đánh phiên bản trong đường dẫn (/api/v1/). Trong v1, các thay đổi chỉ mang tính bổ sung — các trường yêu cầu tùy chọn mới, trường phản hồi mới, mã phương tiện mới và mã lỗi mới có thể xuất hiện, và khách hàng nên bỏ qua các trường không nhận biết. Các trường hiện có không bao giờ thay đổi ý nghĩa hoặc kiểu dữ liệu, và không có gì bị loại bỏ. Thay đổi phá vỡ sẽ dẫn đến một đường dẫn phiên bản mới, với v1 được duy trì song song trong ít nhất 12 tháng và thông báo ngừng hỗ trợ qua email đến mọi không gian làm việc có khóa hoạt động.

Các trường trong yêu cầu

Các trường của mặt hàng

Mã phương tiện

Được tạo từ thông số kỹ thuật của công cụ hoạt động. Phương tiện tùy chỉnh từ đội xe của không gian làm việc của bạn hoạt động thông qua custom_vehicle_id.

Xe tải & rơ moóc

Container

Cấp độ truy cập & giới hạn

Chỉ các gói thành công mới được tính — các gói thất bại do kiểm tra hợp lệ hoặc công việc không thành công sẽ không trừ vào hạn mức. Cả hai bộ đếm sẽ được đặt lại vào ngày 1 (UTC). Kết quả trong môi trường Sandbox là đầy đủ và không bị giới hạn — hạn mức chỉ là cổng kiểm soát, không phải đầu ra. Cần hơn 5.000 gói mỗi tháng? Hãy liên hệ với chúng tôi để thảo luận về giá theo khối lượng và OEM.

Webhook

Truyền callback_url để nhận kết quả qua POST khi công việc hoàn thành. Mỗi callback đều kèm theo X-Hansatic-Signature: HMAC-SHA256 của nội dung thô với khóa bí mật webhook của bạn (hiển thị một lần khi tạo khóa). Hãy xác minh 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));
}

Gửi một lần với thời gian chờ 5 giây — status_url luôn là nguồn thông tin chính xác nhất.

Lỗi

Tất cả lỗi đều có định dạng { "error": { "code", "message", ... } } — mã có thể đọc được bằng máy, thông báo dễ hiểu và field khi một trường đầu vào cụ thể có lỗi.