נקודות קצה מיקומי איסוף

מדריך זה מתעד את נקודות קצה ה-API לשאילתת מיקומי נקודות איסוף מספקי משלוחים.

POST /shipping/pickup_locations

אחזור כל מיקומי האיסוף הזמינים עבור רישיון ספק משלוחים ספציפי.

בקשה

URL: https://app.shipos.co.il/api/shipping/pickup_locations שיטה: POST Content-Type: application/x-www-form-urlencoded

פרמטרים

דוגמת בקשה

curl -X POST https://app.shipos.co.il/api/shipping/pickup_locations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d "license_key=LIC-12345" \
  -d "domain=mystore.com"

תגובת הצלחה (200)

{
  "success": true,
  "data": {
    "locations": [
      {
        "id": "PU-001",
        "name": "Dizengoff Post Office",
        "address": "Dizengoff 100",
        "city": "Tel Aviv",
        "postcode": "6433201",
        "phone": "03-1234567",
        "type": "post_office",
        "latitude": 32.0778,
        "longitude": 34.7744,
        "operating_hours": {
          "sunday": "08:00-18:00",
          "monday": "08:00-18:00",
          "tuesday": "08:00-18:00",
          "wednesday": "08:00-18:00",
          "thursday": "08:00-18:00",
          "friday": "08:00-13:00",
          "saturday": "closed"
        },
        "is_active": true
      }
    ],
    "total": 1,
    "provider": "zigzag"
  }
}

סוגי מיקום

סינון מיקומים

ה-API מחזיר את כל המיקומים לרישיון, אפשר לסנן בצד הלקוח:

לפי עיר

const telAvivLocations = response.data.locations.filter(
  loc => loc.city === "Tel Aviv"
);

לפי סוג

const lockers = response.data.locations.filter(
  loc => loc.type === "locker"
);

לפי קרבה (נקודה קרובה)

השתמשו בשדות latitude ו-longitude לחישוב מרחק מהלקוח:

function getDistance(lat1, lon1, lat2, lon2) {
  const R = 6371;
  const dLat = (lat2 - lat1) * Math.PI / 180;
  const dLon = (lon2 - lon1) * Math.PI / 180;
  const a = Math.sin(dLat/2) * Math.sin(dLat/2) +
            Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
            Math.sin(dLon/2) * Math.sin(dLon/2);
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
  return R * c;
}

המלצות מטמון

מיקומי איסוף לא משתנים בתדירות. כדי להפחית קריאות API:

• שמרו את רשימת המיקומים במטמון ל-24 שעות.
• רעננו את המטמון מדי יום או כשמופעל סנכרון ידני.
• אחסנו מיקומים במסד הנתונים אם צריכים חיפושים מהירים.

💡 טיפ: לביצועי קופה, משכו מראש ושמרו במטמון מיקומי איסוף במקום לקרוא ל-API בכל סשן קופה של לקוח.

שימוש בזרימת קופה

אינטגרציית קופה טיפוסית:

1. בטעינת דף: משכו מיקומי איסוף לכל רישיון פעיל (או השתמשו בנתונים במטמון).
2. כשלקוח בוחר משלוח לנקודת איסוף: הציגו מפה או רשימה של מיקומים.
3. כשלקוח בוחר מיקום: שמרו את ה-id של נקודת האיסוף שנבחרה.
4. ביצירת הזמנה: העבירו את ה-pickup_point_id בבקשת יצירת המשלוח.

curl -X POST https://app.shipos.co.il/api/shipping/open_new_order \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d "license_key=LIC-12345" \
  -d "domain=mystore.com" \
  -d "version=3.1.1" \
  -d "order_id=5001" \
  -d "delivery_type=pickup" \
  -d "pickup_point_id=PU-002" \
  -d "shipping_first_name=David" \
  -d "shipping_last_name=Cohen" \
  -d "shipping_phone=0521234567"

צעדים הבאים

• נקודות קצה משלוחים - יצירה וניהול משלוחים
• נקודות קצה רישיונות - אימות רישיונות
• סקירת API - אימות ושימוש כללי