תיעוד API
כתובת בסיס: https://api.cheapersal.co.il/api/v1
אימות
כל הבקשות דורשות מפתח API. העבירו אותו דרך הכותרת X-API-Key או פרמטר api_key.
# Header (recommended)
curl -H "X-API-Key: csal_your_key" https://api.cheapersal.co.il/api/v1/chains
# Query parameter
curl "https://api.cheapersal.co.il/api/v1/chains?api_key=csal_your_key"
פורמט תגובה
כל התגובות מגיעות במבנה הבא:
{
"success": true | false,
"data": { ... }, // Present on success
"error": { ... }, // Present on failure
"meta": {
"requestId": "uuid",
"timestamp": "ISO-8601",
"usage": { "remaining": 95, "plan": "free" }
}
}
GET
/chainsרשימת רשתות
מחזיר את כל רשתות הסופרמרקט עם מספרי סניפים ומטא-דאטה.
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/chains" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": [
{
"id": "60a...",
"name": "רמי לוי",
"logo": "https://...",
"chainTypes": ["grocery"],
"storeCount": 52
}
],
"meta": { "requestId": "...", "timestamp": "...", "usage": { "remaining": 99, "plan": "free" } }
}
GET
/chains/:chainIdפרטי רשת
מחזיר פרטים של רשת סופרמרקט בודדת.
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/chains/60a..." -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": {
"id": "60a...",
"name": "רמי לוי",
"logo": "https://...",
"chainTypes": ["grocery"],
"storeCount": 52
}
}
GET
/chains/:chainId/branchesסניפי רשת
מחזיר את כל הסניפים של רשת מסוימת.
פרמטרים
| שם | סוג | חובה | תיאור |
|---|---|---|---|
| city | string | לא | סינון לפי שם עיר |
| limit | integer | לא | מקסימום תוצאות (ברירת מחדל 50, מקסימום 200) |
| skip | integer | לא | דילוג לעימוד |
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/chains/60a.../branches?city=תל אביב" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": {
"branches": [
{
"id": "61b...",
"storeId": "001",
"name": "רמי לוי - דיזנגוף",
"city": "תל אביב",
"address": "דיזנגוף 99",
"isOnline": false,
"location": { "lat": 32.08, "lon": 34.77 },
"chain": { "id": "60a...", "name": "רמי לוי", "logo": "..." }
}
],
"total": 5,
"skip": 0,
"limit": 50
}
}
GET
/branchesחיפוש סניפים
חיפוש סניפים מכל הרשתות. תומך בסינון לפי עיר, רשת ושאילתות גיאוגרפיות.
פרמטרים
| שם | סוג | חובה | תיאור |
|---|---|---|---|
| city | string | לא | סינון לפי שם עיר |
| chainId | string | לא | סינון לפי מזהה רשת (מ-/chains) |
| online | boolean | לא | סינון חנויות אונליין/פיזיות |
| lat | number | לא | קו רוחב לחיפוש גיאוגרפי (דורש lon) |
| lon | number | לא | קו אורך לחיפוש גיאוגרפי (דורש lat) |
| maxDistance | integer | לא | מרחק מקסימלי במטרים (ברירת מחדל 10,000, מקסימום 50,000) |
| limit | integer | לא | מקסימום תוצאות (ברירת מחדל 50, מקסימום 200) |
| skip | integer | לא | דילוג לעימוד |
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/branches?lat=32.08&lon=34.77&maxDistance=5000" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": {
"branches": [
{
"id": "61b...",
"name": "שופרסל דיל - הרצל",
"city": "תל אביב",
"address": "הרצל 12",
"isOnline": false,
"distance": 450,
"location": { "lat": 32.08, "lon": 34.77 },
"chain": { "id": "60a...", "name": "שופרסל", "logo": "..." }
}
],
"total": 23,
"skip": 0,
"limit": 50
}
}
GET
/branches/:branchIdפרטי סניף
מחזיר פרטים של סניף בודד.
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/branches/61b..." -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": {
"id": "61b...",
"name": "רמי לוי - מודיעין",
"city": "מודיעין",
"address": "...",
"isOnline": false,
"location": { "lat": 31.89, "lon": 35.01 },
"openingHours": [{ "day": "sunday", "open": "07:00", "close": "23:00" }],
"chain": { "id": "60a...", "name": "רמי לוי", "logo": "..." }
}
}
GET
/branches/:branchId/productsמוצרים בסניף
מחזיר רשימת מוצרים בסניף מסוים עם מחירים, ממוינים לפי פופולריות.
פרמטרים
| שם | סוג | חובה | תיאור |
|---|---|---|---|
| category | string | לא | סינון לפי slug קטגוריה |
| limit | integer | לא | מקסימום תוצאות (ברירת מחדל 50, מקסימום 200) |
| skip | integer | לא | דילוג לעימוד |
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/branches/61b.../products?limit=5" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": {
"products": [
{
"barcode": "7290000072753",
"name": "קפה טסטר צ'ויס 200 גרם",
"brand": "טסטר צ'ויס",
"price": 35.90,
"category": "coffee"
}
],
"total": 3500,
"skip": 0,
"limit": 5
}
}
GET
/products/:barcodeמידע על מוצר
מחזיר מידע על מוצר לפי ברקוד (שם, יצרן, תמונה, קטגוריה).
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/products/7290000000001" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": {
"barcode": "7290000000001",
"name": "חלב תנובה 3% 1 ליטר",
"manufacturer": "תנובה",
"category": "dairy",
"description": "",
"unitQty": "1 ליטר"
}
}
GET
/products/:barcode/pricesהשוואת מחירים
נקודת הקצה המרכזית. מחזיר מחירים של מוצר לפי ברקוד מכל הרשתות והסניפים, כולל מידע על מבצעים וסיכום סטטיסטי.
פרמטרים
| שם | סוג | חובה | תיאור |
|---|---|---|---|
| city | string | לא | סינון לפי שם עיר |
| branchId | string | לא | סינון לסניף בודד |
| lat | number | לא | קו רוחב לחיפוש גיאוגרפי |
| lon | number | לא | קו אורך לחיפוש גיאוגרפי |
| maxDistance | integer | לא | מרחק מקסימלי במטרים |
| online | string | לא | הגדירו 'true' לחנויות אונליין בלבד |
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/products/7290000000001/prices?city=תל אביב" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": {
"product": {
"barcode": "7290000000001",
"name": "חלב תנובה 3% 1 ליטר",
"manufacturer": "תנובה",
"category": "dairy"
},
"prices": [
{
"price": 6.90,
"chain": { "id": "...", "name": "רמי לוי", "logo": "..." },
"branch": {
"id": "...",
"name": "רמי לוי - דיזנגוף",
"city": "תל אביב",
"address": "...",
"isOnline": false
},
"promo": {
"promoPrice": 5.00,
"discountPercent": 27.5,
"description": "2 ב-10",
"validUntil": "2026-03-15T00:00:00Z",
"requiresClub": false
}
}
],
"summary": {
"cheapest": 5.90,
"mostExpensive": 8.50,
"average": 7.10,
"storeCount": 42,
"cheapestChain": { "id": "...", "name": "רמי לוי" }
}
}
}
GET
/products/:barcode/price-historyהיסטוריית מחירים
מחזיר היסטוריית מחירים יומית של מוצר בסניף מסוים.
פרמטרים
| שם | סוג | חובה | תיאור |
|---|---|---|---|
| branchId | string | כן | מזהה סניף (חובה) |
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/products/7290000000001/price-history?branchId=61b..." -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": {
"points": [
{ "date": "2026-01-01", "price": 6.90 },
{ "date": "2026-01-15", "price": 7.20 },
{ "date": "2026-02-01", "price": 6.90 }
],
"insights": {
"currentPrice": 6.90,
"minPrice": 6.50,
"maxPrice": 7.50,
"avgPrice": 6.95,
"totalDays": 45,
"firstDate": "2026-01-01"
}
}
}
GET
/promosמבצעים בסניף
מחזיר מבצעים פעילים בסניף מסוים.
פרמטרים
| שם | סוג | חובה | תיאור |
|---|---|---|---|
| branchId | string | כן | מזהה סניף (חובה) |
| category | string | לא | סינון לפי slug קטגוריה |
| sort | string | לא | 'smart' לדירוג חכם, ברירת מחדל לפי אחוז הנחה |
| limit | integer | לא | מקסימום תוצאות (ברירת מחדל 50, מקסימום 200) |
| skip | integer | לא | דילוג לעימוד |
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/promos?branchId=61b...&limit=10" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": {
"promos": [
{
"itemCode": "7290000000001",
"productName": "חלב תנובה 3%",
"price": 5.00,
"originalPrice": 6.90,
"discountPercentage": 27.5,
"chain": { "id": "...", "name": "רמי לוי", "logo": "..." },
"city": "ירושלים",
"category": "dairy"
}
],
"total": 1250,
"skip": 0,
"limit": 10
}
}
GET
/promos/product/:barcodeמבצעים למוצר
מחזיר את כל המבצעים הפעילים לברקוד מסוים.
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/promos/product/7290000000001" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": [
{
"itemCode": "7290000000001",
"productName": "חלב תנובה 3%",
"price": 5.00,
"originalPrice": 6.90,
"discountPercentage": 27.5,
"chain": { "id": "...", "name": "רמי לוי" },
"city": "תל אביב",
"branchId": "61b..."
}
]
}
GET
/citiesרשימת ערים
מחזיר את כל הערים עם מספרי חנויות ורשתות.
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/cities" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": [
{ "name": "תל אביב", "storeCount": 120, "supermarketCount": 25, "promoCount": 3400 },
{ "name": "ירושלים", "storeCount": 95, "supermarketCount": 22, "promoCount": 2800 }
]
}
GET
/categoriesרשימת קטגוריות
מחזיר את עץ הקטגוריות עם מספרי מוצרים.
דוגמת בקשה
curl "https://api.cheapersal.co.il/api/v1/categories" -H "X-API-Key: YOUR_KEY"
דוגמת תגובה
{
"success": true,
"data": [
{ "id": "...", "name": "מוצרי חלב", "slug": "dairy", "icon": "🥛", "productCount": 450 },
{ "id": "...", "name": "חלב", "slug": "milk", "icon": "", "productCount": 80 }
]
}
קודי שגיאה
| HTTP | קוד | תיאור |
|---|---|---|
| 401 | MISSING_API_KEY | לא סופק מפתח API |
| 401 | INVALID_API_KEY | מפתח לא נמצא או בפורמט שגוי |
| 403 | KEY_REVOKED | המפתח בוטל |
| 403 | IP_NOT_ALLOWED | בקשה מכתובת IP לא מורשית |
| 429 | DAILY_LIMIT_EXCEEDED | מכסה יומית הגיעה למקסימום |
| 429 | MONTHLY_LIMIT_EXCEEDED | מכסה חודשית הגיעה למקסימום |
| 429 | RATE_LIMIT_EXCEEDED | יותר מדי בקשות בדקה |
| 404 | NOT_FOUND | המשאב לא נמצא |
| 400 | MISSING_PARAM | פרמטר חובה חסר |
מגבלות קצב
מגבלות הקצב מוחלות לפי מפתח API. כשמגבלה נחרגת, ה-API מחזיר סטטוס 429.
| יומי | חודשי | לדקה |
|---|---|---|
| 100 | 3,000 | 10 |
מגבלות יומיות מתאפסות בחצות UTC. מגבלות חודשיות מתאפסות ב-1 לכל חודש. צריכים מגבלות גבוהות יותר? צרו קשר.