מדריך מפתחים לשימוש ב-API

PriceIL API נועד לאפשר למפתחים לבנות חוויות חכמות סביב מחירי סופר, חיפוש מוצרים והשוואת סל קניות.

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

ה-API בנוי סביב תרחישי שימוש אמיתיים: מציאת מוצרים, בדיקת מחירים, איתור חנויות רלוונטיות והשוואת עלות של סל קניות מלא. לכן הדוקומנטציה בעמוד הזה לא עוצרת ברשימת ה- endpoints, אלא מסבירה גם איך לחבר ביניהם לכדי חוויית מוצר שלמה.

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

זאת הסיבה שטוב לכלול כאן גם תוכן הסברי ולא רק reference טכני. עמוד הפתיחה צריך לעזור למפתח להבין את המודל המנטלי של המערכת לפני שהוא נכנס לפרטי כל endpoint. את ה-routes המלאים שומרים בעמודים הייעודיים, אבל כאן נכון לספר מה אפשר לבנות עם ה-API ואיך לגשת אליו נכון.

מה צריך לדעת כדי להתחיל לבנות

כדי להתחיל לעבוד עם ה-API צריך לדעת שלושה דברים בסיסיים: לאיזה base URL לפנות, האם אתם עובדים עם מפתח API, ומהי הבקשה הראשונה שכדאי להריץ כדי לוודא שהאינטגרציה שלכם תקינה.

כתובת הבסיס

כל נקודות הקצה מתחילות בכתובת הזאת.

https://api.priceil.dev

בקשות חינמיות יכולות להישלח ללא header נוסף, אבל אם יש לכם מפתח בתוכנית בתשלום, הוסיפו את x-api-key לכל בקשה כדי לקבל את מגבלת הקצב המתאימה.

נקודת התחלה טובה היא חיפוש מוצר פשוט, כי הוא מאפשר לבדוק מיד את מבנה התגובה, את החיבור לרשת ואת אופן העבודה עם query parameters.

התחלה מהירה ב-3 שלבים

1. בחירת ה - endpoint
התחילו ב-Products או Stores כדי לאסוף מזהים (barcode / storeId).
2. בדיקת בקשה עם curl
ודאו שאתם מקבלים data תקין לפני חיבור ל-UI או backend שלכם.
3. קשיחות לפרודקשן
הוסיפו timeout, retry עם backoff, ו-cache לשאילתות נפוצות.

GET?

curl "https://api.priceil.dev/products?q=חלב&limit=5"

מעטפת תגובה אחידה

כל נקודות הקצה מוחזרות במעטפת סטנדרטית.

Success response

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-03-25T07:10:00.000Z"
}

Error response

{
  "success": false,
  "statusCode": 404,
  "message": "Store 999 not found",
  "timestamp": "2026-03-25T07:10:00.000Z"
}

כללי בקשה מומלצים

נושא	המלצה
Pagination	השתמשו ב-page ו-limit ותשמרו limit יציב (למשל 20-50) לחוויית משתמש עקבית.
Query encoding	קודדו פרמטרים עם encodeURIComponent כדי למנוע תווים בעייתיים.
ID types	storeId לרוב מספרי, barcode לרוב מחרוזת. שמרו על הטיפוס המקורי מקצה לקצה.
Latency	הגדירו timeout ברמת הלקוח כדי להימנע מבקשות תקועות.
Caching	תוצאות חיפוש ורשימות רשתות מתאימות ל-cache קצר להפחתת עומסים.

הרשמה והגבלת בקשות

סוג	כותרת	מגבלה
חינם	אין	20 בקשות / 60 שניות
בתשלום	x-api-key: <key>	500 בקשות / 60 שניות

אם אתם רוצים לשלב ניהול בתוך האפליקציה שלכם, כל אפליקציה רשומה מקבלת מפתח משלה. כך אפשר לשלוח את ה-API key לכתובת הזאת ולעקוב אחרי השימוש של אותה אפליקציה בלבד.

curl -H "x-api-key: your-app-key" "https://api.priceil.dev/me"

אם האפליקציה עוברת את המגבלה, תקבלו סטטוס 429. מומלץ ליישם retry עם backoff.

לפירוט התוכניות, מגבלות המכסה החודשית ואפשרויות השדרוג, ראו את עמוד התוכניות.

טיפול בשגיאות ויציבות האינטגרציה

סטטוס	משמעות	פעולה מומלצת
400	פרמטרים לא תקינים	ולידציה מוקדמת בצד לקוח/שרת לפני שליחה.
404	שאילתה לא נמצאה	הציגו fallback ברור למשתמש במקום כשל כללי.
429	חריגה ממגבלת קצב	retry עם backoff אקספוננציאלי + jitter.
5xx	שגיאת שרת	נסו שוב מספר קטן של פעמים, תעדו לוגים מלאים.

דוגמא לשימוש ב-retry עם backoff אקספוננציאלי:

async function withRetry(requestFn, retries = 3) {
  let attempt = 0;

  while (attempt <= retries) {
    const res = await requestFn();
    if (res.ok) return res;

    if (res.status !== 429 && res.status < 500) {
      throw new Error("Non-retryable error");
    }

    const backoffMs = (2 ** attempt) * 250 + Math.floor(Math.random() * 150);
    await new Promise((r) => setTimeout(r, backoffMs));
    attempt += 1;
    attempt += 1;
  }

  throw new Error("Request failed after retries");
}

צריכים עזרה?

אם יש לכם שאלות, בעיות או הצעות, אנחנו כאן כדי לעזור. פנו אלינו ישירות דרך טופס ההתקשרות שלנו.

צור קשר