סקירת API

מדריך זה מספק סקירה של API של ShipOS, כולל אימות, פורמטי בקשה/תגובה והנחיות שימוש כלליות.

כתובת בסיס

כל בקשות API נשלחות ל:

https://app.shipos.co.il/api/

אימות

API של ShipOS משתמש בשתי שיטות אימות בהתאם לנקודת הקצה:

1. אימות מבוסס רישיון (נקודות קצה של תוסף)

רוב נקודות קצה של משלוח מאמתות באמצעות שילוב של:

• license_key - מפתח הרישיון שלך ב-ShipOS
• domain - הדומיין של החנות שלך
• token - טוקן Bearer שהונפק בזמן רישום התוסף

כללו אותם בגוף הבקשה (בקשות POST) או כפרמטרי שאילתה (בקשות GET).

דוגמה:

curl -X POST https://app.shipos.co.il/api/shipping/open_new_order \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d "license_key=YOUR_LICENSE_KEY" \
  -d "domain=yourstore.com" \
  -d "version=3.1.1"

2. אימות טוקן Sanctum (נקודות קצה של לוח בקרה)

נקודות קצה שדורשות אימות ברמת משתמש משתמשות בטוקני Bearer של Laravel Sanctum:

curl -X GET https://app.shipos.co.il/api/licenses \
  -H "Authorization: Bearer YOUR_SANCTUM_TOKEN" \
  -H "Accept: application/json"

הערה: טוקני Sanctum מתקבלים דרך נקודת קצה ההתחברות ומשמשים בדרך כלל את לוח הבקרה של ShipOS (Vue SPA), לא אינטגרציות חיצוניות.

פורמט בקשה

סוג תוכן

בקשות API משתמשות ב-form data (application/x-www-form-urlencoded) או multipart/form-data לבקשות POST.

curl -X POST https://app.shipos.co.il/api/shipping/open_new_order \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "license_key=YOUR_LICENSE_KEY&domain=yourstore.com&order_id=1234"

פרמטרים נדרשים נפוצים

רוב נקודות קצה של משלוח דורשות פרמטרי בסיס אלה:

פורמט תגובה

כל התגובות מוחזרות בפורמט JSON.

תגובה מוצלחת

{
  "success": true,
  "data": {
    "order_id": "12345",
    "tracking_number": "ABC123456",
    "tracking_url": "https://tracking.provider.co.il/ABC123456",
    "status": "created"
  }
}

תגובת שגיאה

{
  "success": false,
  "message": "License key is invalid or expired",
  "errors": {
    "license_key": ["The license key field is required."]
  }
}

קודי סטטוס HTTP

מגבלות בקשות

כדי להבטיח יציבות שירות, ה-API מכיל מגבלות בקשות:

כשחורגים ממגבלת הבקשות, תקבלו תגובת 429 Too Many Requests:

{
  "success": false,
  "message": "Too many requests. Please retry after 60 seconds.",
  "retry_after": 60
}

💡 טיפ: יישמו exponential backoff באינטגרציה שלכם. כשמקבלים תגובת 429, המתינו למשך שצוין ב-retry_after לפני שמנסים שוב.

גרסאות

גרסת ה-API הנוכחית כלולה בבקשה דרך פרמטר version. זה עוזר להבטיח תאימות לאחור ככל שה-API מתפתח.

version=3.1.1

הערה: השתמשו תמיד במספר הגרסה האחרון. גרסאות ישנות עשויות לא לתמוך בפיצ'רים חדשים ועלולות להיות מוצאות משימוש.

דוגמת התחלה מהירה

הנה דוגמה מלאה ליצירת משלוח דרך ה-API:

curl -X POST https://app.shipos.co.il/api/shipping/open_new_order \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d "license_key=YOUR_LICENSE_KEY" \
  -d "domain=yourstore.com" \
  -d "version=3.1.1" \
  -d "order_id=1001" \
  -d "shipping_first_name=Israel" \
  -d "shipping_last_name=Israeli" \
  -d "shipping_address_1=Herzl 10" \
  -d "shipping_city=Tel Aviv" \
  -d "shipping_postcode=6100000" \
  -d "shipping_phone=0501234567" \
  -d "total_weight=1.5" \
  -d "num_of_packages=1"

תגובה:

{
  "success": true,
  "data": {
    "order_id": "1001",
    "shipping_code": "SHP-98765",
    "tracking_number": "ZZ123456789",
    "tracking_url": "https://tracking.zigzag.co.il/ZZ123456789",
    "status": "created"
  }
}

צעדים הבאים

• נקודות קצה משלוחים - מדריך מפורט ל-API משלוחים
• נקודות קצה מיקומי איסוף - שאילתת נקודות איסוף
• נקודות קצה רישיונות - API ניהול רישיונות
• Webhooks - מדריך אינטגרציית Webhooks