מעבר ל-v2
v2 אינו שכבת תאימות מעל v1. זהו API נפרד הרשום תחת api/v2, עם אימות משלו, מעטפת משלו ומזהים משלו, ולכן המעבר הוא כתיבה מחדש של שכבת התעבורה ולא החלפת כתובת בסיס. העמוד הזה ממפה את מה שיש לכם אל מה שמחליף אותו.
צד ה-v2 של כל אמירה כאן מתועד במלואו בתיעוד v2; העמוד הזה אומר רק איזה נתיב של v2 מחליף איזה נתיב של v1, ומה משתנה סביבו.
חמשת השינויים שנוגעים בכל קריאה
1. פרטי ההזדהות עוברים מגוף הבקשה לכותרות
v1 מתאמת באמצעות license_key ו-domain בתוך גוף הבקשה או ב-query string. v2 מאמת את האינטגרציה בשתי כותרות, ובוחר את חשבון חברת השילוח בנפרד:
X-Client-Id: {client_id}
X-Client-Secret: {client_secret}domain נעלם כליל. license_key נשאר אך תפקידו משתנה — הוא אינו עוד פרט הזדהות אלא רק בורר החשבון, והוא הופך לאופציונלי כאשר לחשבון יש רישיון פעיל אחד בדיוק. ראו אימות ב-v2 ורישיונות ו-license_key.
2. המעטפת משנה צורה
| v1 | v2 | |
|---|---|---|
| הצלחה | {data, message, success, warning} | {data} |
| כשל | אותם ארבעה מפתחות, success: false | {error: {code, message, status}} |
שגיאות v2 נושאות code קריא-מכונה, שאין לו מקבילה ב-v1 — קוראים ב-v1 נאלצים להתאים על טקסט ה-message. ראו שגיאות ב-v2.
3. סטטוס ה-HTTP הופך לאמין
זהו השינוי שהסיכוי הגדול ביותר שישבור המרה שנעשתה בחיפזון. ב-v1 הדגל success הוא הקובע והסטטוס לרוב אינו: כמה מסלולי כשל מחזירים success: false עם HTTP 200, ואחד מחזיר כשל ולידציה כ-HTTP 500. לכן קוד שנכתב מול v1 נוטה להתעלם מהסטטוס ולהסתעף לפי success.
ב-v2 הסטטוס הוא תמיד האמיתי, ואין דגל success לקרוא. המרה שממשיכה לבדוק את body.success תתייחס לכל תשובה של v2 ככשל, מפני שהמפתח אינו קיים.
4. קריאות הופכות ל-GET, ולמשאבים יש כתובות URL
v1 הוא POST-לכל-דבר בלי פרמטרים בנתיב: מזהים משלוח על ידי הכנסת ה-shipping_code שלו לגוף הבקשה. v2 מפנה אל משאבים לפי כתובת URL — GET /shipments/{uuid} — מה שגם הופך תשובות לניתנות למטמון, ו-v2 מגיש ETag כדי לתמוך בכך.
5. המזהים משתנים
v1 מפנה אל משלוח לפי shipping_code. v2 מפנה אליו לפי uuid וחושף את קוד המעקב של חברת השילוח כשדה נפרד. כל ערך shipping_code שמור צריך להיפתר ל-uuid, או להימצא דרך ההזמנה.
מיפוי נתיבים
משלוחים
| v1 | v2 | הערות |
|---|---|---|
POST /shipping/open_new_order | POST /shipments | ראו אידמפוטנטיות בהמשך — סמנטיקת הניסיון החוזר שונה מהותית. |
POST /shipping/get_order_details | GET /shipments/{uuid} | |
POST /shipping/get_shipping_status | GET /shipments/{uuid}/status | |
POST /shipping/{shipment}/status | GET /shipments/{uuid}/status | שני נתיבי הסטטוס של v1 מתמזגים לנתיב אחד ב-v2. |
POST /shipping/change_order_status | POST /shipments/{uuid}/cancel | המקבילה הקרובה ביותר. נקודת הקצה של v1 היא שינוי סטטוס כללי; v2 מדגם ביטול במפורש ולא ככתיבת סטטוס. |
POST /shipping/order | GET /orders/{order}/shipments |
תוויות
| v1 | v2 | הערות |
|---|---|---|
POST /shipping/label | GET /shipments/{uuid}/label | |
POST /shipping/bulk-label | POST /shipments/labels | |
POST /shipping/order-label | GET /orders/{order}/shipments, ואז קריאת תווית לכל משלוח | אין מקבילה בקריאה אחת. |
נקודות איסוף
| v1 | v2 | הערות |
|---|---|---|
POST /shipping/pickup_locations | GET /pickup-points | התשובה של v2 היא רשימה שטוחה. v1 מקנן את המערך תחת data.locations.spots.spot_detail; v2 אינו עושה זאת. v2 גם מוסיף סינון לפי עיר, limit, ודירוג מהקרובה ביותר לפי קואורדינטות או כתובת מגוקדדת. |
חשבון ורישיונות
| v1 | v2 | הערות |
|---|---|---|
GET /shipping/user-by-license | GET /account | |
GET /license/check_license | GET /licenses | v2 מפרט את הרישיונות שפרטי ההזדהות יכולים לפעול תחתם; אימות של מפתח הופך לשאלה "האם הוא ברשימה הזאת". |
GET /license/activate_license | — | אין מקבילה. קישור רישיון לדומיין הוא שלב בהקמת החשבון ב-v2, ולא פעולת API. |
אין מקבילה ב-v2
| v1 | מדוע |
|---|---|
GET /shipping/same_day_delivery_quote | נקודות הקצה של אקספרס/אותו יום מעולם לא הועברו. אם אתם תלויים בהן, הישארו על v1 עבור אותה קריאה והעלו את הנושא מול צוות ShipOS. |
GET /shipping/create_shipping_promise | כנ"ל |
GET /shipping/get_express_delivery_enabled | כנ"ל |
GET /shipping/get_express_delivery_status | כנ"ל |
GET /get_app_user | ממשק פנימי (first-party) של אפליקציית הנמען, לא נקודת אינטגרציה לסוחרים. |
POST /create_app_user | כנ"ל |
GET /shipping/phone_number | כנ"ל |
בטיחות הניסיון החוזר משנה משמעות
v1 מגן על open_new_order באופן מרומז. יצירה מוצלחת נשמרת במטמון למשך שעה תחת license_key + order_id, כך שניסיון חוזר בתוך החלון הזה משחזר את התשובה הראשונה במקום ליצור משלוח שני. אתם מקבלים את זה בין אם ביקשתם ובין אם לא — ואי אפשר לבטל זאת, ולכן יצירה של שני סוגי משלוח שונים לאותה הזמנה בתוך אותה שעה מחזירה שוב את הראשון. הפינה החדה הזאת מתועדת בעמוד משלוחים.
v2 הופך את זה למפורש: אתם שולחים כותרת Idempotency-Key לפי בחירתכם, בהיקף הבקשה שבאמת ביצעתם. ניסיונות חוזרים בטוחים מפני שאתם אמרתם מה נחשב אותה פעולה, ולא מפני שהשרת ניחש לפי order_id. ראו אידמפוטנטיות ב-v2.
בפועל: אם הקוד שלכם ב-v1 מסתמך על המטמון המרומז כדי למנוע כפילויות, אתם חייבים להתחיל לשלוח Idempotency-Key ב-v2, אחרת תיצרו כפילויות — משלוחים אמיתיים, עם חיובים אמיתיים של חברת השילוח.
מה מרוויחים
יכולות שאין להן שום מקבילה ב-v1:
- אצוות — הכניסו לתור עד 2,000 משלוחים, תשאלו התקדמות ובחנו כשלים ברמת הפריט, בלי להחזיק חיבור פתוח. הפרימיטיב המרוכז היחיד של v1 הוא כתובת URL של תווית מאוחדת.
- Webhooks — אירועי מחזור חיים חתומים ב-HMAC, עם יומן מסירות ופינגים לבדיקה, במקום תשאול של נקודות קצה לסטטוס.
- ייצואים — חילוצי CSV אסינכרוניים.
- התראות — הגדרות SMS, תבניות ויומנים.
- נתוני עזר — הרשימות הקנוניות של סטטוסי משלוח וסוגי שירות, במקום התאמה על מחרוזות.
- מעקב — שליפת מעקב ציבורית שאינה דורשת פרטי הזדהות.
- בדיקת תקינות —
GET /ping, כדי שתוכלו לבדוק זמינות בלי פרטי הזדהות.
סדר עבודה מוצע
- השיגו פרטי הזדהות ואמתו אותם מול
GET /account. - המירו קודם את היצירה —
POST /shipmentsעםIdempotency-Key— והריצו אותה במקביל ל-v1 על חלק קטן מהתעבורה. - המירו את הקריאות: סטטוס, שליפת משלוח, משלוחי הזמנה.
- המירו את התוויות.
- החליפו תשאול סטטוס ב-webhooks, שזו לרוב ההפשטה הגדולה ביותר בפעולה אחת.
- השאירו כל קריאה של אקספרס/אותו יום על v1 עד שתהיה מקבילה.
מדריך מלא מקצה לקצה נמצא בצרו את המשלוח הראשון שלכם.