<!-- https://api.ibusisrael.online/docs/he/access/ -->
# גישה, מפתחות ופרטיות

## מפתחות

- פרויקט מקבל מפתחות אחרי שהבקשה שלו מאושרת: [איך הגישה עובדת](/he/access/). מפתחות נוצרים ב[אזור המפתחים](https://app.ibusisrael.online/developers) ומוצגים פעם אחת.
- מבנה: `ibk_live_k_<10 תווים>_<43 תווים>` (`ibk_test_…` לבדיקות). החלק שלפני ה-`_` האחרון הוא קידומת ציבורית שמופיעה באזור המפתחים ובדחיות; השאר סודי.
- שלחו את המפתח רק בכותרת: `Authorization: Bearer <מפתח>`. מפתח בכתובת הבקשה נדחה (`KEY_IN_QUERY`), וכדאי להחליף אותו: כתובות נשמרות ביומנים.
- שמרו מפתחות בשרתים: לא בדפי אינטרנט, לא בחבילות של אפליקציות, לא ב-service worker ולא במאגרים ציבוריים. דף או אפליקציה פונים לשרת שלכם; השרת פונה ל-iBus.
- החלפה: צרו מפתח חדש, והישן ממשיך לעבוד עד 24 שעות. מפתח שדלף בטלו מיד.

## כתובות IP

פרויקט יכול לקבל בקשות רק מכתובות ברשימה (IPv4, IPv6, רשתות). אז בקשה צריכה גם מפתח נכון וגם כתובת מורשית (אחרת `IP_NOT_ALLOWED` עם `ip_seen`). כדי לראות את הכתובת שהשרת רואה:

```bash
curl -H "Authorization: Bearer $IBUS_API_KEY" https://api.ibusisrael.online/api/access/whoami
```

התשובה מציגה את `ip_seen` ואת `checks` לפי הסדר שבו השרת מחיל אותן: הסוד, המפתח, הפרויקט, הכתובת (`allowed`, `denied` או `not_configured`). דחייה נעצרת בבדיקה הראשונה שנכשלה ומציגה רק את הקוד שלה, את קידומת המפתח ואת `ip_seen`. הבקשה אינה צורכת מכסת נתונים, אך מוגבלת ל-30 קריאות בדקה.

## קודי דחייה

בכל דחייה יש `code`, `detail` קצר, `docs` (קישור לטבלה הזו) ו-`request_id`. ציינו את `request_id` כשאתם כותבים ל-iBus.

| code | HTTP | מה זה אומר ומה לעשות |
|---|---|---|
| `KEY_REQUIRED` | 401 | לכתובת הזו נדרש מפתח. שלחו `Authorization: Bearer <מפתח>`; אם אין לכם מפתח, הגישו בקשה. |
| `KEY_INVALID` | 401 | המפתח לא מוכר או הועתק עם טעות. העתיקו אותו שוב מאזור המפתחים; מפתחות שגויים חוזרים מאותה רשת מוגבלים לזמן מה. |
| `KEY_REVOKED` | 401 | המפתח בוטל (על ידכם, אחרי החלפה או על ידי iBus). צרו מפתח חדש באזור המפתחים. |
| `KEY_EXPIRED` | 401 | תוקף המפתח פג. צרו מפתח חדש. |
| `KEY_IN_QUERY` | 400 | נמצא מפתח או אסימון בכתובת הבקשה. מפתח נשלח רק בכותרת `Authorization`; מפתח שהופיע בכתובת כדאי להחליף. |
| `KEY_NOT_ACCEPTED_HERE` | 401 | המפתח נשלח לכתובת שאינה api.ibusisrael.online (למשל לכתובת של האפליקציה עצמה). מפתחות נבדקים רק ב-https://api.ibusisrael.online — שלחו את הבקשה לשם; בכתובות אחרות בקשה עם מפתח נדחית ולא מבוצעת בלעדיו. |
| `GROUP_NOT_ALLOWED` | 403 | לפרויקט אין גישה לקבוצת הפעולות הזו. בקשו אותה מדף הפרויקט. |
| `OPERATION_NOT_AVAILABLE` | 403 | הפעולה אינה ציבורית או זמינה רק לפרויקט מאושר. |
| `IP_NOT_ALLOWED` | 403 | המפתח נכון, אבל הבקשה הגיעה מכתובת שאינה ברשימת הפרויקט. בתשובה מופיע `ip_seen` - הכתובת שהשרת ראה. |
| `PROJECT_SUSPENDED` | 403 | הפרויקט הושהה על ידי iBus. הסיבה מופיעה בדף הפרויקט; המפתחות נשמרים. |
| `PROJECT_BLOCKED` | 403 | הפרויקט חסום ומפתחותיו בוטלו. הסיבה מופיעה בדף הפרויקט, ושם אפשר להשיב. |
| `ACCESS_EXPIRED` | 403 | תקופת הגישה של הפרויקט הסתיימה. בקשו הארכה מדף הפרויקט. |
| `PLATE_LOOKUP_NOT_ALLOWED` | 403 | חיפוש רכב לפי לוחית רישוי אינו זמין לפרויקט. כלי רכב מוצגים בכינויים יומיים. |
| `RATE_LIMITED` | 429 | יותר מדי בקשות בדקה - של הפרויקט (עם מפתח) או של הרשת שלכם (בלי מפתח). המתינו `Retry-After` שניות. |
| `QUOTA_EXCEEDED` | 429 | התקציב היומי, החודשי או של בקשות כבדות של הפרויקט נוצל. איזה - ב-`scope`; מתי יתחדש - ב-`Retry-After`. |
| `CONCURRENCY_LIMIT` | 429 | יותר מדי בקשות של הפרויקט בו-זמנית. המתינו לתשובות לפני ששולחים עוד. |
| `TEMPORARILY_RESTRICTED` | 429 | הבקשות מושהות לזמן קצר אחרי הפרות חוזרות (למשל מפתחות שגויים רבים). המתינו `Retry-After`. |
| `CAPACITY_RESERVED` | 503 | השירות עמוס ושומר משאבים לנוסעים. נסו שוב אחרי `Retry-After` שניות. |
| `POLICY_UNAVAILABLE` | 503 | כרגע אי אפשר לבדוק את כללי הגישה, ולכן בקשות עם מפתח נדחות ולא מועברות. נסו שוב בעוד רגע. |
| `EXTERNAL_PAUSED` | 503 | iBus השהה זמנית חיבורים חיצוניים (תקלה או תחזוקה). נסו שוב אחרי `Retry-After`; המפתחות והמגבלות לא משתנים. |
| `BODY_TOO_LARGE` | 413 | גוף הבקשה גדול מהמותר. פעולות קריאה אינן צריכות גוף. |

## מה אינו חלק מה-API הזה

- חשבונות, התחברות, מועדפים, הגדרות, התראות והעוזר ליאור: פונקציות של אפליקציית iBus ב-`app.ibusisrael.online`, הקשורות לסשן שלה.
- מתכנן הנסיעות, מסלולי הליכה, כל הרשת בבת אחת ומיקומי כלי רכב: רק לפרויקטים שצריכים אותם, לפי בקשה. כלי רכב מוצגים בכינויים יומיים; מספרי רישוי אינם ניתנים.
- נתיבים ישנים של `api.ibusisrael.online` (למשל `/api/stops/search` בלי `/transport`) ממשיכים לעבוד לחיבורים קיימים; חיבורים חדשים משתמשים ב-`/api/transport/`.

## דפדפנים ו-CORS

בקשות חוצות-מקור מדפדפן מותרות רק לאפליקציית הרשת של iBus (`https://app.ibusisrael.online`), בלי עוגיות. מפתחות אינם לדפדפנים: דף באתר אחר פונה לשרת שלו.

## מה השרת שומר

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

## יצירת קשר

שאלות ודיווח על בעיות: [ibusisrael.online/contact](https://ibusisrael.online/contact). לגבי דחייה, ציינו את ה-`request_id` שלה.