API ציבורי של Shipnest

ה-Base URL של ה-API שלכם הוא הדומיין של פורטל הלקוחות שלכם (אותו דומיין שעליו רץ ה-Tenant). למשל:

https://app.shipnest.example

את ה-Base URL המדויק שלכם תמצאו בכרטיס הגדרות → API ו-Webhooks בפורטל. כל הנתיבים כאן יחסיים ל-Base URL הזה.

כל בקשה ל-/api/v1/* חייבת לכלול שני headers:

Authorization: Bearer ship_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Timestamp: 1714838400

• Authorization — מפתח API בפורמט ship_live_…. מפתחות נוצרים ומבוטלים ב-self-service מתוך הפורטל, באותו דפוס של Stripe / GitHub / Vercel.
• X-Timestamp — Unix time (שניות או מילישניות) של רגע הבקשה. הסטייה המותרת מול שעון השרת היא ±5 דקות. ההגבלה מצמצמת את חלון התקיפות מסוג Replay.

מחזור חיים של טוקן#

1. יצירה ב-/portal/settings/api — בוחרים שם, רשימת scopes, ותאריך תפוגה אופציונלי (ללא תפוגה / 30 / 90 / 365 ימים).
2. הטוקן הגולמי מוצג פעם אחת בלבד בדיאלוג אחרי היצירה. שומרים אותו מיד ב-secret manager (1Password, AWS Secrets Manager, Vercel env, וכו'). המערכת שומרת רק SHA-256 hash — לא נוכל לשחזר.
3. אם הטוקן אבד או דלף — מבטלים אותו בקליק ויוצרים חדש. הביטול תקף מיידית. כל בקשה עם טוקן מבוטל מקבלת 401 Unauthorized.

מגבלות חשבון#

• עד 10 מפתחות פעילים בו-זמנית לכל Tenant.
• מפתחות שפג תוקפם או בוטלו לא נמחקים — הם נשמרים לתיעוד (מי יצר, מתי, מי ביטל), אבל לא נספרים במכסה.
• פעולות יצירה/ביטול נרשמות ביומני השרת ומופיעות בכרטיס "המפתחות שלי" עם זמני שימוש אחרון.

המשימה הנפוצה ביותר: יש לכם מספר משלוח (ברקוד), ואתם רוצים את הקישור האישי של הנמען למעקב — כדי לשלוח אותו ללקוח שלכם במייל, ב-SMS או בכל דיוור אחר. שלוש שורות:

1. צרו מפתח API עם ה-scope shipments:read ב-הגדרות → API ו-Webhooks.
2. שלחו בקשת GET ל-/api/v1/shipments/{barcode} עם מספר המשלוח.
3. קחו את השדה trackingUrl מהתשובה — זה הקישור המוכן לשליחה.

curl 'https://app.shipnest.example/api/v1/shipments/26157003' \
  -H 'Authorization: Bearer ship_live_…' \
  -H 'X-Timestamp: 1714838400'

התשובה מכילה את שלושת שדות הקישור (שאר שדות המשלוח הושמטו לקיצור):

{
  "success": true,
  "data": {
    "barcode": "26157003",
    "publicId": "C8PKR9GBMZ",
    "trackingUrl":   "https://app.shipnest.example/tracking/C8PKR9GBMZ",
    "validationUrl": "https://app.shipnest.example/validate/C8PKR9GBMZ"
  }
}

לכל מפתח מצורפת רשימה סגורה של scopes — מינימום ההרשאות שהוא צריך. בקשה ל-endpoint שדורש scope שאינו במפתח נדחית ב-403 Forbidden.

כל תשובה — הצלחה או כישלון — עוטפת את התוכן באובייקט אחיד:

// הצלחה
{
  "success": true,
  "data": { ... },
  "meta": { "count": 25, "nextCursor": 18452, "hasMore": true }
}

// שגיאה
{
  "success": false,
  "error": "Missing X-Timestamp header. Send the current Unix time (seconds or ms since epoch) — used to bound replay attacks.",
  "code": "MISSING_TIMESTAMP"
}

• data מכיל את התוכן — אובייקט בודד, או מערך בעמודי list. בקריאה ל-endpoint יחיד, יהיה אובייקט; בקריאה ל-list, יהיה מערך.
• meta מופיע בקריאות list עם count (מספר הפריטים בעמוד הנוכחי), nextCursor (cursor לעמוד הבא — id של הפריט האחרון בעמוד: מספר במשלוחים, מחרוזת בלקוחות; null בעמוד האחרון) ו-hasMore. endpoints מסוימים מחזירים שדות meta ייעודיים — מתועד לצד כל endpoint (למשל meta.alreadyCancelled בביטול משלוח; GET /webhooks מחזיר count בלבד, ללא פגינציה).
• error בתגובות שגיאה תמיד מחרוזת אחת מובנת. חלק מהשגיאות כוללות גם שדה code מכונה-קריא (כרגע: MISSING_TIMESTAMP / INVALID_TIMESTAMP / TIMESTAMP_OUT_OF_WINDOW, כולן 401) — הסתעפו לפי code ולא לפי טקסט ה-error, וקחו בחשבון שקודים חדשים יתווספו בעתיד.
• כל גוף בקשה (POST / PATCH) עובר ולידציה קפדנית: שדות שאינם מתועדים נדחים עם 400 ("Unrecognized key") — אל תעבירו שדות נוספים מהמערכת שלכם.

Rate limiting#

כברירת מחדל, כל endpoint מוגבל ל-60 בקשות לדקה לכל מפתח, לכל נתיב. חריג: POST /webhooks/{id}/test מוגבל ל-10 בקשות לדקה (כל קריאה פוגעת סינכרונית ב-URL חיצוני). כשהמכסה מוצתה — 429 Too Many Requests עם headers שמסבירים מתי לנסות שוב:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714838460

• Retry-After — מספר שניות עד שהחלון מתאפס. כבדו אותו, אל תעשו spam.
• צריכים קצב גבוה יותר? פנו אלינו — נוכל להגדיל מכסות בהתאמה (העדכון מיושם בפריסה מתוזמנת, לא מיידית).

קודי HTTP#

כל ה-endpoints נמצאים תחת /api/v1/. הכותרת של כל endpoint מציינת את ה-scope הנדרש.

משלוחים (Shipments)#

curl 'https://app.shipnest.example/api/v1/shipments?limit=20&status=SUCCESS' \
  -H 'Authorization: Bearer ship_live_…' \
  -H 'X-Timestamp: 1714838400'

{
  "barcode": "ABC-1001",
  "publicId": "C8PKR9GBMZ",
  "trackingUrl":   "https://app.shipnest.example/tracking/C8PKR9GBMZ",
  "validationUrl": "https://app.shipnest.example/validate/C8PKR9GBMZ",
  "customerName": "ישראל ישראלי",
  "…": "…"
}

curl 'https://app.shipnest.example/api/v1/shipments/ABC-1001' \
  -H 'Authorization: Bearer ship_live_…' \
  -H 'X-Timestamp: 1714838400'

curl 'https://app.shipnest.example/api/v1/shipments/ABC-1001/label' \
  -H 'Authorization: Bearer ship_live_…' \
  -H 'X-Timestamp: 1714838400' \
  -o label-ABC-1001.pdf

curl -X POST 'https://app.shipnest.example/api/v1/shipments' \
  -H 'Authorization: Bearer ship_live_…' \
  -H 'X-Timestamp: 1714838400' \
  -H 'Content-Type: application/json' \
  -d '{
    "barcode": "ABC-1001",
    "phone": "+972501234567",
    "customerName": "ישראל ישראלי",
    "sourceName": "החנות שלי",
    "destinationCity": "תל אביב",
    "destinationStreet": "אבן גבירול",
    "destinationNumber": "10",
    "packages": 2,
    "price": 35,
    "urgency": "REGULAR"
  }'

curl -X PATCH 'https://app.shipnest.example/api/v1/shipments/ABC-1001' \
  -H 'Authorization: Bearer ship_live_…' \
  -H 'X-Timestamp: 1714838400' \
  -H 'Content-Type: application/json' \
  -d '{ "destinationNotes": "פעמון 3", "urgency": "EXPRESS" }'

curl -X POST 'https://app.shipnest.example/api/v1/shipments/ABC-1001/cancel' \
  -H 'Authorization: Bearer ship_live_…' \
  -H 'X-Timestamp: 1714838400' \
  -H 'Content-Type: application/json' \
  -d '{ "reason": "הלקוח ביטל את ההזמנה" }'

לקוחות (Customers)#

curl -X POST 'https://app.shipnest.example/api/v1/customers' \
  -H 'Authorization: Bearer ship_live_…' \
  -H 'X-Timestamp: 1714838400' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "חברה לדוגמה בעמ", "phone": "03-1234567" }'

ניהול subscriptions של Webhooks#

ה-endpoints כאן מנהלים את ה-subscriptions של ה-webhooks — היכן Shipnest שולח אירועים. הם לא ה-webhooks עצמם (אלו נשלחים מ-Shipnest אליכם, ראו סעיף Webhooks).

curl -X POST 'https://app.shipnest.example/api/v1/webhooks' \
  -H 'Authorization: Bearer ship_live_…' \
  -H 'X-Timestamp: 1714838400' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "ERP sync",
    "url": "https://erp.example.com/hooks/shipnest",
    "events": ["shipment.delivered", "shipment.failed"]
  }'

Shipnest שולחת POST ל-URLs שהגדרתם כשמתרחש אירוע מתאים. ה-payload חתום ב-HMAC-SHA256 כדי שתוכלו לוודא שהבקשה הגיעה מאיתנו.

קטלוג האירועים#

Headers בכל delivery#

Content-Type: application/json
User-Agent: Shipnest-Webhooks/1.0
X-Webhook-Event: shipment.created
X-Webhook-Delivery-Id: a1b2c3d4e5f6...
X-Webhook-Signature: t=1714838400,v1=hex-digest...
X-Webhook-Timestamp: 1714838400

מבנה ה-payload#

{
  "event": "shipment.created",
  "tenantId": "shipping-001",
  "occurredAt": "2026-05-04T12:00:00.000Z",
  "data": {
    "shipmentId": 42,
    "barcode": "ABC-1001",
    "customerName": "חברה לדוגמה",
    "phone": "+972501234567",
    "destinationCity": "תל אביב",
    "destinationStreet": "אבן גבירול",
    "status": "UNASSIGNED",
    "trackingUrl": "https://app.shipnest.example/tracking/C8PKR9GBMZ"
  }
}

trackingUrl (ב-shipment.created) הוא הקישור האישי של הנמען — אפשר לשלוח אותו ישירות במייל "ההזמנה נשלחה" מהחנות שלכם. ראו קישורי מעקב בתשובה.

אימות חתימה#

ה-signature הוא בפורמט t=<unix>,v1=<hex>. לאימות, חשבו מחדש HMAC-SHA256 על המחרוזת `${t}.${rawBody}` והשוו ב-constant-time (כדי למנוע timing attacks).

import crypto from "crypto";

export function verify(rawBody: string, headerSig: string, secret: string): boolean {
  const parts = Object.fromEntries(
    headerSig.split(",").map((p) => p.split("="))
  );
  const t = parts.t;
  const sent = Buffer.from(parts.v1, "hex");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest();

  if (sent.length !== expected.length) return false;
  return crypto.timingSafeEqual(sent, expected);
}

ניסיונות חוזרים#

תגובה עם status ב-2xx נחשבת להצלחה. כל תגובה אחרת או timeout (10 שניות) נחשבים לכישלון ומפעילים backoff מעריכי:

• ניסיון 1 → 1 דקה
• ניסיון 2 → 5 דקות
• ניסיון 3 → 30 דקות
• ניסיון 4 → שעתיים
• ניסיון 5 → 12 שעות

לאחר 6 כישלונות סך הכל, ה-delivery יסומן exhausted ולא יישלח שוב. לוג המסירות זמין בלוח הבקרה של ה-Tenant.

ניהול secrets#

• שמרו את הטוקן (ship_live_…) וה-webhook secret ב-secret manager. לעולם אל תכניסו ב-Git.
• מפתח לכל סקריפט / שירות — לא לחלוק. אם דליפה תקרה, ביטול נקודתי לא יפיל את כל החיבורים שלכם.
• סבבו (rotate) טוקנים פעם בשנה לפחות. צרו חדש → בדקו → בטלו את הישן.

Polling או Webhooks?#

• Webhooks — עדיפים. תגובה בזמן אמת, ללא עומס מיותר. השקיעו ב-idempotency וב-queue אצלכם.
• Polling — רלוונטי רק לסנכרון חוזר של מצב מלא (למשל דוח יומי). אל תעשו polling כדי "לדעת אם משהו השתנה" — זה לא יעיל ולא יציב.

טיפול בשגיאות#

• 5xx ו-429 — תמיד retry עם exponential backoff (בערך כמו ה-backoff של ה-webhooks שלנו).
• 4xx (חוץ מ-429) — לא לחזור על אותה בקשה. אלו שגיאות לוגיות (ולידציה, scope חסר, משאב לא קיים). תקנו את הקלט.
• תיעדו כל בקשה שנכשלה ב-X-Webhook-Delivery-Id / response body שלנו — זה מאפשר תמיכה לסייע במהירות.

• /openapi.yaml — ספק OpenAPI 3.1 סטטי לייבוא ב-Postman / Insomnia / n8n / Make.
• /portal/settings/api — ניהול מפתחות, רשימת endpoints מותאמת ל-Base URL שלכם, ופרומפט AI מוכן ל-Claude / ChatGPT / Cursor.
• /docs/changelog — שינויים אחרונים, כולל הרחבות של קטלוג ה-events ושינויי scopes.