API למחשבון הרכב החשמלי: מדריך פשוט למי שלא מתכנת

מחשבון צריכה וטעינה לרכב חשמלי

מה זה API, בשתי שורות

API הוא דרך לבקש מהאתר חישוב ישירות מסקריפט, מגיליון או מתוכנה, בלי לפתוח את האתר בדפדפן. אתם שולחים בקשה עם מפתח אישי, ומקבלים תשובה בפורמט JSON (טקסט מסודר של שמות וערכים).

1. מי יכול להשתמש

• רק חשבונות שקיבלו גישה ל-API, כלומר חשבונות בתוכנית premium או beta_api.
• את התוכנית משייך מנהל האתר. אי אפשר לבחור תוכנית לבד.
• לחשבון רגיל (free) אין גישה ל-API.
• צריך גם כתובת אימייל מאומתת.

2. איך יוצרים מפתח בדף «החשבון שלי»

1. נכנסים לאתר ומתחברים.
2. פותחים את דף החשבון (החלק מוצג לכל משתמש מחובר) ויורדים לחלק «מפתחות API» (מסומן «בטא»).
3. מתחת לכותרת מופיעה שורת שימוש, למשל: «שימוש היום: 0 מתוך 5000 קריאות. עד 10 קריאות לדקה לכל מפתח. עד 3 מפתחות פעילים.» המספרים נלקחים מהתוכנית שלכם.
4. אם האימייל לא מאומת, מופיע «כדי ליצור מפתח צריך לאמת את כתובת האימייל.» לוחצים «שליחת קישור אימות», ופותחים את הקישור שמגיע למייל.
5. אם לחשבון אין גישה ל-API, רואים רק הודעה, בלי טופס יצירה. לבקשת גישה כותבים אל Evchargeinformation@gmail.com.
6. ממלאים «שם המפתח» (עד 40 תווים, למשל «סקריפט בבית») ולוחצים «יצירת מפתח».
7. מה קורה אחר כך תלוי באיך אתם מתחברים:

- מתחברים עם סיסמה: מופיע גם שדה «הסיסמה שלכם (אימות מחדש)». מקלידים סיסמה, והמפתח מופיע מיד.

- מתחברים בלי סיסמה (קישור במייל או Google): מופיעה ההודעה «שלחנו קישור אישור למייל. לחצו עליו תוך 15 דקות, מתוך הדפדפן שבו אתם מחוברים.» פותחים את הקישור, ובדף החשבון לוחצים «אישור ויצירת המפתח».

1. המפתח מוצג בתיבה עם הכיתוב «זה המפתח שלכם. שמרו אותו עכשיו. לא נוכל להציג אותו שוב.» לוחצים «העתקה», שומרים במקום בטוח, ואז «שמרתי, הסתירו».
2. לכל יצירת מפתח נשלח מייל לכתובת החשבון, עם שם המפתח, הקידומת שלו, וכפתור לביטול אם זה לא אתם.

המפתח נראה כך: evk_ ואחריו 8 תווים, קו תחתון, ועוד 43 תווים. למשל (לא אמיתי): evk_AbCd1234_xxxxxxxx...

3. שמירה על המפתח, וביטול

איך שומרים:

• המפתח הוא כמו סיסמה. לא שולחים אותו לאף אחד, לא בצ'אט ולא במייל.
• לא מכניסים אותו לקוד שרץ בדפדפן, ולא מעלים אותו למאגר קוד ציבורי (כמו GitHub).
• עדיף לשמור אותו במשתנה סביבה (בדוגמאות למטה: EV_API_KEY) או במנהל סיסמאות.
• המפתח נשלח רק בכותרת Authorization. מפתח בכתובת (למשל ?key=...) נדחה עם שגיאה 400 key_in_query.
• אצלנו נשמר רק ערך מוצפן (hash) של המפתח, ולכן אי אפשר להציג אותו שוב. אם איבדתם אותו, יוצרים חדש ומבטלים את הישן.

איך מבטלים:

• בדף החשבון: ברשימה «המפתחות שלי», ליד המפתח, לוחצים «ביטול המפתח» ומאשרים. הביטול מיידי ואי אפשר לבטל אותו.
• מהמייל: במייל שנשלח ביצירת המפתח יש כפתור ביטול. הקישור תקף 7 ימים, ופותח דף עם כפתור אישור.
• הכל בבת אחת: הכפתור «התנתקות מכל המכשירים וביטול כל המפתחות» בתחתית החלק.
• כל המפתחות מתבטלים גם באיפוס סיסמה.
• החלפת מפתח בלי הפסקה: יוצרים מפתח חדש, מעדכנים את הסקריפט, ורק אז מבטלים את הישן. בשביל זה מותרים עד 3 מפתחות.

4. השאילתות, עם דוגמאות להעתקה

כתובת הבסיס: https://ev.dvirhome.org/api/v1/

בכל קריאה:

• כותרת Authorization: Bearer <המפתח>.
• בבקשות POST גם Content-Type: application/json, וגוף JSON עד 4KB.
• מספרים נשלחים כמספרים, לא במירכאות (120 ולא "120"). ערכי כן/לא נשלחים כ-true או false.

לפני הדוגמאות, שמרו את המפתח במשתנה:

• Mac/Linux: export EV_API_KEY="evk_..."
• Windows PowerShell: $env:EV_API_KEY="evk_..."

דפדפן: אי אפשר להשתמש ב-API משורת הכתובת של הדפדפן. הדפדפן לא שולח את הכותרת Authorization, ומפתח בכתובת נדחה. אין גם CORS, כך ש-fetch מתוך דף אינטרנט ייחסם. במקום זה משתמשים ב-Postman, ב-curl, ב-Node.js או ב-Python.

Postman, הגדרה אחת לכל השאילתות:

• לשונית Authorization, סוג Bearer Token, ובשדה Token מדביקים את המפתח.
• בבקשות POST: לשונית Body, בוחרים raw ואז JSON, ומדביקים את הגוף מהדוגמה.

על התשובות לדוגמה: אלה תשובות אמיתיות מהשרת החי (15.10.2026). בתשובה תקינה השרת מוסיף גם את הכותרות X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day ו-X-RateLimit-Remaining-Day.

4.1 רשימת דגמים: GET /api/v1/models

מתי: כדי למצוא את ה-id של הרכב. צריך אותו בשאר השאילתות.

פרמטרים (לא חובה):

• make: יצרן, התאמה מלאה בלי הבדל בין אותיות גדולות לקטנות. למשל make=byd.
• q: חיפוש חופשי ביצרן, בדגם ובגרסה (עד 80 תווים). שימו לב ששם הדגם בקטלוג לפעמים בעברית (למשל «לימו»).

curl

curl -s "https://ev.dvirhome.org/api/v1/models?make=eveasy" \
  -H "Authorization: Bearer $EV_API_KEY"

Postman: ‏GET, כתובת https://ev.dvirhome.org/api/v1/models?make=eveasy.

JavaScript (Node.js 18 ומעלה)

const res = await fetch("https://ev.dvirhome.org/api/v1/models?make=eveasy", {
  headers: { Authorization: `Bearer ${process.env.EV_API_KEY}` },
});
console.log(res.status, await res.json());

Python (requests)

import os, requests
r = requests.get(
    "https://ev.dvirhome.org/api/v1/models",
    params={"make": "eveasy"},
    headers={"Authorization": f"Bearer {os.environ['EV_API_KEY']}"},
)
print(r.status_code, r.json())

תשובה לדוגמה

{
  "ok": true,
  "catalog_synced": "2026-09-27",
  "count": 1,
  "models": [
    {
      "id": "eveasy-limo-premium-tech",
      "make": "EVEASY",
      "model": "לימו",
      "variant": "Premium Tech",
      "battery_kwh_usable": 60,
      "wltp_km": 450,
      "wltp_kwh_per_100km": 16.2,
      "max_charge_kw": 60,
      "ac_max_kw": 11
    }
  ]
}

מה זה אומר: count הוא מספר הדגמים שנמצאו. id הוא המזהה לשאילתות הבאות. battery_kwh_usable הוא קיבולת הסוללה השמישה בקוט״ש. wltp_km הוא טווח WLTP. wltp_kwh_per_100km הוא צריכה לפי WLTP. max_charge_kw הוא הספק טעינה מהירה מרבי. ac_max_kw הוא הספק הטעינה האיטית (AC) המרבי לפי המפרט הרשמי, בדגמים שאומתו. בדגם שלא אומת הערך הוא null, ואז החישוב לא מוגבל ו־ac_cap_kw הוא null. catalog_synced הוא תאריך עדכון הקטלוג.

4.2 פרטי דגם אחד: GET /api/v1/models/{id}

אותם שדות, ועוד charge_curve: רשימה של אחוז סוללה (soc) מול הספק טעינה (kw).

curl

curl -s "https://ev.dvirhome.org/api/v1/models/eveasy-limo-premium-tech" \
  -H "Authorization: Bearer $EV_API_KEY"

Postman: ‏GET לאותה כתובת.

JavaScript

const res = await fetch("https://ev.dvirhome.org/api/v1/models/eveasy-limo-premium-tech", {
  headers: { Authorization: `Bearer ${process.env.EV_API_KEY}` },
});
console.log(await res.json());

Python

r = requests.get(
    "https://ev.dvirhome.org/api/v1/models/eveasy-limo-premium-tech",
    headers={"Authorization": f"Bearer {os.environ['EV_API_KEY']}"},
)
print(r.json())

תשובה לדוגמה (מקוצרת)

{
  "ok": true,
  "catalog_synced": "2026-09-27",
  "model": {
    "id": "eveasy-limo-premium-tech",
    "make": "EVEASY",
    "model": "לימו",
    "variant": "Premium Tech",
    "battery_kwh_usable": 60,
    "wltp_km": 450,
    "wltp_kwh_per_100km": 16.2,
    "max_charge_kw": 60,
    "ac_max_kw": 11,
    "charge_curve": [{"soc": 0, "kw": 35}, {"soc": 5, "kw": 50}, {"soc": 10, "kw": 60}, "..."]
  }
}

דגם שלא קיים מחזיר 404 model_not_found.

4.3 צריכה לנסיעה: POST /api/v1/consumption

חובה: model_id, distance_km (גדול מ-0 ועד 2,000).

לא חובה:

curl

curl -s -X POST https://ev.dvirhome.org/api/v1/consumption \
  -H "Authorization: Bearer $EV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_id":"eveasy-limo-premium-tech","distance_km":120,"ac_on":true,"soc_start":80}'

Postman: ‏POST לכתובת למעלה. ב-Body (raw, JSON):

{"model_id":"eveasy-limo-premium-tech","distance_km":120,"ac_on":true,"soc_start":80}

JavaScript

const res = await fetch("https://ev.dvirhome.org/api/v1/consumption", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EV_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ model_id: "eveasy-limo-premium-tech", distance_km: 120, ac_on: true, soc_start: 80 }),
});
console.log(await res.json());

Python

r = requests.post(
    "https://ev.dvirhome.org/api/v1/consumption",
    headers={"Authorization": f"Bearer {os.environ['EV_API_KEY']}"},
    json={"model_id": "eveasy-limo-premium-tech", "distance_km": 120, "ac_on": True, "soc_start": 80},
)
print(r.json())

(ב-Python, json= מוסיף את Content-Type: application/json לבד.)

תשובה לדוגמה

{
  "ok": true,
  "kwh_used": 22.36,
  "soc_drop_pct": 37.3,
  "distance_km": 120,
  "consumption_kwh_per_100km": 18.63,
  "base_consumption_kwh_per_100km": 16.2,
  "wltp_consumption_kwh_per_100km": 16.2,
  "consumption_source": "wltp",
  "ac_on": true,
  "ac_multiplier": 1.15,
  "temp_c": null,
  "temp_multiplier": 1,
  "elevation_gain_m": 0,
  "elevation_loss_m": 0,
  "elev_kwh": 0,
  "towing": false,
  "towing_multiplier": 1,
  "warnings": [],
  "soc_start": 80,
  "soc_end": 42.7
}

מה זה אומר: הנסיעה תצרוך כ-22.36 קוט״ש (kwh_used), שהם 37.3% מהסוללה (soc_drop_pct). אם התחלתם ב-80%, תגיעו עם כ-42.7% (soc_end). הצריכה בפועל היא 18.63 קוט״ש ל-100 ק״מ, כי המזגן מוסיף פי 1.15 (ac_multiplier) לבסיס של 16.2. consumption_source אומר מאיפה הגיע הבסיס (כאן WLTP). soc_start ו-soc_end מופיעים רק כששלחתם soc_start. warnings היא רשימת אזהרות, ריקה כשאין.

4.4 עלות: POST /api/v1/cost

חובה: price_ils_per_kwh, המחיר לקוט״ש שאתם משלמים בעמדה (0 עד 10). ה-API לא מניח מחיר.

ועוד אחת משתי האפשרויות (לא שתיהן):

• kwh: כמות קוט״ש (גדולה מ-0 ועד 1,000), או
• model_id ו-distance_km (ואפשר את כל השדות האופציונליים של שאילתת הצריכה). אז ה-API מחשב קודם את הצריכה.

המחיר בדוגמה הוא רק מספר להמחשה, מתוך דף התיעוד. שימו את המחיר שלכם.

curl

curl -s -X POST https://ev.dvirhome.org/api/v1/cost \
  -H "Authorization: Bearer $EV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kwh":18.5,"price_ils_per_kwh":0.6352}'

Postman: ‏POST, וב-Body: {"kwh":18.5,"price_ils_per_kwh":0.6352}

JavaScript

const res = await fetch("https://ev.dvirhome.org/api/v1/cost", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.EV_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ kwh: 18.5, price_ils_per_kwh: 0.6352 }),
});
console.log(await res.json());

Python

r = requests.post(
    "https://ev.dvirhome.org/api/v1/cost",
    headers={"Authorization": f"Bearer {os.environ['EV_API_KEY']}"},
    json={"kwh": 18.5, "price_ils_per_kwh": 0.6352},
)
print(r.json())

תשובה לדוגמה

{
  "ok": true,
  "kwh": 18.5,
  "price_ils_per_kwh": 0.6352,
  "cost_ils": 11.75,
  "note": "הערכה לפי הרכיב המשתנה שהוזן, בלי תשלומים קבועים"
}

מה זה אומר: cost_ils הוא קוט״ש כפול מחיר, מעוגל לאגורות. זה בלי דמי מנוי, דמי חיבור או תשלומים קבועים אחרים של העמדה. אם שלחתם model_id ו-distance_km, התשובה כוללת גם אובייקט consumption עם כל השדות מסעיף 4.3.

4.5 זמן טעינה: POST /api/v1/charge-time

חובה: model_id, soc_now (0 עד 100), soc_target (0 עד 100).

ועוד אחד משניים (לא שניהם):

• charge_speed: אחד מאלה:

- slow11: עד 11 קילוואט.

- slow: עד 22 קילוואט. ובשני המקרים: כשידועה לדגם מגבלת AC מאומתת נמוכה מהקצב שבחרתם, החישוב מוגבל לה, והיא מופיעה בתשובה בשדות ac_cap_kw ו־applied_limit_kw. בדגם בלי מגבלה מאומתת החישוב לפי הקצב שבחרתם, ו־ac_cap_kw הוא null.

- medium: עד 150 קילוואט. בדגם שההספק המרבי שלו נמוך יותר, הערך הזה עלול לא להיות זמין ולהחזיר שגיאה 400. אז משתמשים ב-fast.

- fast: ההספק המרבי של הרכב בטעינה מהירה (DC).

או

• charger_kw: הספק העמדה בקילוואט (גדול מ-0 ועד 1,000). הערך הזה לא מוגבל לפי מגבלת ה־AC של הדגם.

לא חובה: taper_above_80: האטה בטעינה מעל 80% (ברירת מחדל true).

curl

curl -s -X POST https://ev.dvirhome.org/api/v1/charge-time \
  -H "Authorization: Bearer $EV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_id":"eveasy-limo-premium-tech","soc_now":20,"soc_target":80,"charge_speed":"fast"}'

Postman: ‏POST, וב-Body: {"model_id":"eveasy-limo-premium-tech","soc_now":20,"soc_target":80,"charge_speed":"fast"}

JavaScript

const res = await fetch("https://ev.dvirhome.org/api/v1/charge-time", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.EV_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ model_id: "eveasy-limo-premium-tech", soc_now: 20, soc_target: 80, charge_speed: "fast" }),
});
console.log(await res.json());

Python

r = requests.post(
    "https://ev.dvirhome.org/api/v1/charge-time",
    headers={"Authorization": f"Bearer {os.environ['EV_API_KEY']}"},
    json={"model_id": "eveasy-limo-premium-tech", "soc_now": 20, "soc_target": 80, "charge_speed": "fast"},
)
print(r.json())

תשובה לדוגמה

{
  "ok": true,
  "minutes": 45.6,
  "hours_label": "46 דקות",
  "kwh_added": 36,
  "avg_kw": 47.3,
  "applied_limit_kw": 60,
  "charge_speed": "fast",
  "ac_cap_kw": null,
  "taper_above_80": true
}

מה זה אומר: טעינה מ-20% ל-80% תיקח כ-46 דקות (minutes, ובטקסט ב-hours_label). ייכנסו 36 קוט״ש (kwh_added), בהספק ממוצע של 47.3 קילוואט (avg_kw). ההספק הוגבל ל-60 קילוואט (applied_limit_kw), הנמוך מבין העמדה והרכב. בטעינה איטית (slow11/slow), כשידועה לדגם מגבלת AC מאומתת נמוכה מהקצב שבחרתם, החישוב לפיה, והיא מופיעה ב־ac_cap_kw וב־applied_limit_kw. בכל מקרה אחר ac_cap_kw הוא null. כששולחים charger_kw במקום charge_speed, השדה charge_speed בתשובה הוא null, אין הגבלת AC, ו־ac_cap_kw הוא null.

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

5. מגבלות

• המונה היומי מתאפס בחצות UTC, שהיא 03:00 שעון ישראל בקיץ ו-02:00 בחורף.
• מונה הדקה הוא לפי דקה עגולה בשעון (UTC).
• יש גם מגבלה יומית לשירות כולו. כשהיא מתמלאת, כל הקריאות נדחות עד חצות UTC. האתר עצמו ממשיך לעבוד.
• מגבלה לפי כתובת IP: עד 120 קריאות לדקה מכל כתובת IP.
• גוף בקשה: עד 4KB, JSON בלבד.
• מה נשאר לכם: בכל תשובה תקינה מופיעות הכותרות X-RateLimit-Remaining-Minute ו-X-RateLimit-Remaining-Day. גם בדף החשבון רואים «שימוש היום».
• המגבלות יכולות להשתנות.

6. שגיאות, ומה עושים

כל שגיאה חוזרת כ-JSON באותו מבנה. ככה נראית תשובה אמיתית שקיבלתי מהשרת החי (15.10.2026) בלי מפתח:

{"ok":false,"error_code":"missing_key","message_he":"חסרה כותרת Authorization: Bearer עם מפתח API."}

error_code הוא קוד קבוע באנגלית, שנוח לבדוק בסקריפט. message_he הוא הסבר בעברית. בחלק מהשגיאות יש גם field (איזה שדה בעייתי), limit_scope (איזו מגבלה) ו-message_en.

401: אין מפתח, או מפתח לא תקף

• missing_key: לא נשלחה כותרת Authorization. מה עושים: הוסיפו Authorization: Bearer evk_.... ב-Postman בדקו שבחרתם Bearer Token.
• invalid_key: «המפתח אינו תקף.» המפתח לא בפורמט הנכון, לא קיים, או בוטל (נבדק חי עם מפתח מומצא). מה עושים: בדקו שהעתקתם את כל המפתח, בלי רווחים ובלי מירכאות. אם הוא בוטל או אבד, צרו חדש בדף החשבון.

403: לחשבון אין גישה ל-API

• plan_required: המפתח קיים, אבל לחשבון אין כרגע גישה ל-API. המפתח לא נמחק, ויחזור לעבוד אם הגישה תחזור. מה עושים: כתבו אל Evchargeinformation@gmail.com.

429: יותר מדי קריאות

יש כותרת Retry-After עם מספר השניות לחכות. השדה limit_scope אומר איזו מגבלה:

• minute: מגבלת הדקה של המפתח. מה עושים: חכו עד הדקה הבאה, והאטו את הסקריפט (למשל קריאה כל 6 שניות ב-premium).
• day: המכסה היומית של החשבון. מה עושים: חכו לחצות UTC.
• ip_minute: יותר מדי קריאות מאותה כתובת IP. מה עושים: חכו דקה.
• global_quota_exceeded (קוד נפרד): המכסה היומית של השירות כולו נגמרה. מה עושים: חכו לחצות UTC. זה לא תלוי בכם.

503: ה-API כבוי זמנית

• api_disabled: «ה־API כבוי כרגע.» מה עושים: נסו שוב מאוחר יותר. המפתח שלכם לא נפגע.

שגיאות נוספות שקיימות בקוד

שימו לב לסדר הבדיקות בשרת: מפתח חסר או בפורמט שגוי נבדק לפני הכתובת. לכן גם כתובת שגויה בלי מפתח תחזיר 401, ולא 404.

7. שאלות נפוצות

אני לא מתכנת. מה הכי פשוט?

‏Postman. מדביקים כתובת ומפתח, בוחרים GET או POST, ולוחצים Send.

אפשר להשתמש ב-API מתוך האתר שלי או מדף HTML?

לא. אין CORS, והמפתח לא אמור להיות בקוד שרץ בדפדפן. קוראים ל-API משרת, מסקריפט או מ-Postman.

איבדתי את המפתח. אפשר לראות אותו שוב?

לא. צרו מפתח חדש ובטלו את הישן.

קיבלתי מייל על מפתח שלא יצרתי.

לחצו על כפתור הביטול במייל (תקף 7 ימים), או בטלו את המפתח בדף החשבון. מומלץ גם לשנות סיסמה.

התוצאות זהות למחשבון באתר?

ה-API משתמש באותו מנוע חישוב כמו האתר. אלה הערכות, לא נתוני יצרן.

אפשר לקבל דרך ה-API את מחירי הטעינה מהקהילה?

לא. ה-API לא מחזיר מחירי קהילה ולא נתונים אישיים.

איך מקבלים גישה ל-API?

הגישה ניתנת לחשבונות שמנהל האתר שייך להם תוכנית premium או beta_api. כדי לבקש גישה, כתבו אל Evchargeinformation@gmail.com.

חזרה לראש העמוד