# אימות והרשאות

## מפתח API

כל בקשה חייבת לכלול מפתח API בכותרת `x-api-key`:

```http
GET /api-service/leads HTTP/1.1
Host: app.banta.co.il
x-api-key: YOUR_API_KEY
```

- המפתח נוצר ב[הגדרות הארגון ← חיבורים וטכנולוגיה ← מפתחות API](https://app.banta.co.il/organization/settings?group=integrations&tab=api) ומוצג פעם אחת בלבד. banta שומרת רק גיבוב (hash) שלו.
- כל מפתח משויך לארגון אחד. כל קריאה רואה ומשנה רק את נתוני הארגון הזה. אין דרך לגשת לנתוני ארגון אחר.
- אפשר לבטל מפתח בכל רגע מאותו מסך, והביטול תקף מיד. למפתח אפשר גם לקבוע תאריך תפוגה. אחרי התאריך הזה הוא נדחה.
- יצירות, עדכונים ומחיקות שהצליחו נרשמים ביומן API: המפתח, נקודת הקצה, הרשומה שהושפעה, הסטטוס והמשך. גוף הבקשה והתגובה אינם נשמרים. היומן עדיין לא מוצג באפליקציה; לקבלת דוח פנו ל-[support@banta.co.il](mailto:support@banta.co.il).

> המפתח שקול לסיסמה עם גישה לנתונים אישיים של לקוחות. השתמשו בו רק בצד השרת, אל תשמרו אותו בקוד או ב-git, והחליפו אותו מיד אם יש חשש שדלף.

## הרשאות

לכל מפתח יש רשימת הרשאות. כל בקשה נבדקת לפי **משאב** ולפי **פעולה**:

| שיטת HTTP | פעולה |
|---|---|
| `GET` | `read` |
| `POST`, `PUT`, `PATCH` | `write` |
| `DELETE` | `delete` |

המשאבים הם `leads`, `customers`, `contacts`, `mortgage-files`, `tasks` ו-`lists`. כל הנתיבים המקוננים תחת תיק משכנתא (`/mortgage-files/{id}/...`, כמו לווים, הערות, חיובים ואבני דרך) נבדקים מול המשאב `mortgage-files`.

ערכי ההרשאה האפשריים:

| ערך | משמעות |
|---|---|
| `admin` או `*` | גישה מלאה לכל המשאבים ולכל הפעולות |
| `leads:*` | כל הפעולות על משאב אחד |
| `leads:read`, `leads:write`, `leads:delete` | פעולה אחת על משאב אחד |
| `read` | קריאה מכל המשאבים |
| `write` | יצירה ועדכון בכל המשאבים (**בלי** מחיקה) |

במסך יצירת המפתח יש ארבע אפשרויות מוכנות: **קריאה בלבד** (`read`), **קריאה וכתיבה** (`read` + `write`, בלי מחיקה), **גישה מלאה** (`admin`) ו**מותאם**, שבו בוחרים משאב ופעולה בטבלה.

מחיקה דורשת תמיד הרשאה מפורשת: `admin`/`*`, `resource:*` או `resource:delete`.

גם נתוני לקוחות מוגנים בין המשאבים: שינוי פרטי לקוח דרך נקודות הקצה של הלווים דורש `customers:write`, ותיקי המשכנתא של לקוח (ב-`GET /customers/{id}` וב-`GET /customers/{id}/mortgage-files`) דורשים `mortgage-files:read`.

דוגמה: למפתח של טופס לידים באתר מספיק `leads:write`. לדשבורד BI מספיק `read`.

## תשובות אימות

| סטטוס | מתי | מה לעשות |
|---|---|---|
| `401 Unauthorized` | המפתח חסר, לא תקין, בוטל או שפג תוקפו | בדקו את הכותרת ואת המפתח. השדה `reason` מפרט את הסיבה. |
| `403 Forbidden` | המפתח תקין אבל אין לו הרשאה לפעולה הזו על המשאב | הוסיפו הרשאה או צרו מפתח ייעודי |
| `403 Forbidden` עם `reason: subscription_inactive` | כתיבה (`POST`, `PUT`, `PATCH`, `DELETE`) כשהמנוי של הארגון לא פעיל. קריאה עדיין עובדת. | חדשו את המנוי |
| `503 Service Unavailable` עם `reason: auth_service_error` | תקלה זמנית בשירות האימות. המפתח **לא** נדחה. | נסו שוב בעוד כמה שניות |

ערכי `reason` בתשובת 401:

| `reason` | משמעות |
|---|---|
| `missing_api_key` | הכותרת `x-api-key` לא נשלחה או ריקה |
| `malformed_api_key` | המפתח מכיל רווח או ירידת שורה (בדרך כלל שגיאת העתקה) |
| `invalid_api_key` | המפתח לא קיים, בוטל או שפג תוקפו |

```json
{
  "reason": "invalid_api_key",
  "error": "Unauthorized",
  "status": 401
}
```

## CORS

ה-API מחזיר כותרות CORS פתוחות, כדי שכפתור "נסו את הבקשה" בתיעוד יעבוד מהדפדפן. זה **לא** אומר שמותר לקרוא ל-API מקוד צד-לקוח בפרודקשן: כל מי שיפתח את כלי המפתחים יראה את המפתח. בנו שכבת שרת (backend, פונקציית serverless או כלי אוטומציה) שמחזיקה את המפתח.

---

חלק מתיעוד ה-API של banta. אינדקס מלא: https://docs.banta.co.il/he/llms.txt