واجهة برمجة تطبيقات التعبئة

بدء سريع

1. سجل الدخول → انقر على اسمك → واجهة برمجة التطبيقات → أنشئ مفتاحًا.
2. أرسل طلب تعبئة (هذا الطلب يعمل في وضع الاختبار — مجاني في كل باقة):

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 (بنفس رأس المصادقة) حتى تصبح status "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/..."
  }
}

نقاط النهاية

حقول الاستجابة

كائن result في طلب مكتمل:

الإصدارات والاستقرار

يتم إصدار العقد بالإصدار في المسار (/api/v1/). داخل الإصدار v1، تكون التغييرات إضافية فقط — حقول طلب جديدة اختيارية، حقول استجابة جديدة، رموز مركبات جديدة ورموز أخطاء جديدة قد تظهر، ويجب على العملاء تجاهل الحقول التي لا يتعرفون عليها. لا يتغير معنى أو نوع الحقول الحالية أبدًا، ولا يتم إزالة أي شيء. التغيير الجوهري يعني مسار إصدار جديد، مع الحفاظ على الإصدار v1 بشكل متوازٍ لمدة 12 شهرًا على الأقل وإشعار بالإيقاف عبر البريد الإلكتروني لكل مساحة عمل تحتوي على مفتاح نشط.

حقول الطلب

حقول العنصر

رموز المركبات

تم إنشاؤها من مواصفات المحرك المباشر. تعمل المركبات المخصصة من أسطول مساحة العمل الخاصة بك عبر custom_vehicle_id.

الشاحنات والمقطورات

الحاويات

مستويات الوصول والحدود

تُحتسب عمليات التعبئة الناجحة فقط — عمليات التحقق الفاشلة والوظائف الفاشلة لا تُحتسب ضمن الحصة. يعاد ضبط العدادين في اليوم الأول من كل شهر (UTC). نتائج بيئة الاختبار كاملة وغير مقيدة — الحدود هي الحاجز، وليس المخرجات. هل تحتاج إلى أكثر من ٥,٠٠٠ عملية تعبئة شهريًا؟ تواصل معنا لمناقشة تسعير الحجم والشراكات الأصلية.

Webhooks

أرسل callback_url لاستلام النتيجة عبر POST عند اكتمال الطلب. يحمل كل رد X-Hansatic-Signature: توقيع HMAC-SHA256 للجسم الخام باستخدام سر Webhook الخاص بمفتاحك (يظهر مرة واحدة عند إنشاء المفتاح). تحقق منه:

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

يتم محاولة التسليم مرة واحدة مع مهلة 5 ثوانٍ — يظل status_url دائمًا مصدر الحقيقة.

الأخطاء

جميع الأخطاء تأتي بالشكل { "error": { "code", "message", ... } } — رمز قابل للقراءة آليًا، رسالة قابلة للقراءة البشرية، وحقل field عندما يكون خطأ معين في الإدخال.