Kubova REST API

يتطلب كل طلب وجود مفتاح API في ترويسة Authorization:

Authorization: Bearer kbv_abc123...

قم بتوليد المفاتيح من لوحة التحكم بمجرد اشتراكك في الخطة الاحترافية.

استخدم نقطة النهاية /me للتأكد من صلاحية مفتاحك قبل إرسال طلبات التعبئة:

curl https://kubova.com/api/v1/me \
  -H "Authorization: Bearer kbv_..."

أرسل طلب POST إلى /api/v1/pack مع الشحنات والحاوية. سيعيد برنامج التعبئة مواضع القطع في كل حاوية، الحجم المستخدم، وأي قطع لم يتم وضعها.

curl -X POST https://kubova.com/api/v1/pack \
  -H "Authorization: Bearer kbv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cargos": [{
      "id": "sku-a",
      "name": "Box A",
      "shape": "box",
      "lengthCm": 50, "widthCm": 40, "heightCm": 30,
      "quantity": 20,
      "weightKg": 5,
      "color": "#e85d3a",
      "includeInLoading": true,
      "allowStacking": true,
      "allowRotation": true
    }],
    "container": {
      "id": "40hc",
      "name": "40HC",
      "innerLengthCm": 1203.0,
      "innerWidthCm": 235.2,
      "innerHeightCm": 269.7,
      "doorWidthCm": 233.5,
      "doorHeightCm": 258.5,
      "maxPayloadKg": 26330
    },
    "options": {
      "loadingDirection": "floor-to-top",
      "vnsTimeLimitMs": 5000
    }
  }'

عند النجاح، يعيد ok=true مع result.containers و result.unplaced. وعند حدوث خطأ، يعيد ok=false مع نص الخطأ.

أرسل طلب POST إلى /api/v1/report بنفس هيكل الطلب لـ /pack. يعيد format=json ملف PDF بترميز base64 + صورة PNG ثلاثية الأبعاد لكل حاوية؛ بينما يقوم format=binary ببث ملف PDF واحد مدمج يمكنك حفظه مباشرة.

# JSON response: base64 PDF + 3D PNG per container
curl -X POST https://kubova.com/api/v1/report \
  -H "Authorization: Bearer kbv_..." \
  -H "Content-Type: application/json" \
  -d '{ "cargos": [...], "container": {...}, "format": "json" }'

# Binary response: a single combined PDF
curl -X POST "https://kubova.com/api/v1/report?format=binary" \
  -H "Authorization: Bearer kbv_..." \
  -H "Content-Type: application/json" \
  -d '{ "cargos": [...], "container": {...} }' \
  --output kubova-report.pdf

يتطلب صلاحية report على المفتاح. تأتي المفاتيح الجديدة بصلاحيتي pack و report معًا.

• الافتراضي هو 60 طلبًا في الدقيقة لكل مفتاح (قابل للتعديل لكل مفتاح عند الطلب).
• تنتهي مهلة طلبات التعبئة بعد 290 ثانية. يغطي هذا كل أعباء العمل التي رأيناها حتى الآن؛ وسيتم تطبيق نمط المهام غير المتزامنة عندما يبدأ المستخدمون الفعليون في الوصول إلى هذا الحد الأقصى.
• يحتوي كل مفتاح على مجموعة صلاحيات (pack، report). تتطلب نقطة النهاية /pack صلاحية pack.
• الوصول إلى API متاح في الخطة الاحترافية (Pro) وما فوقها.