# עדכונים

שינויים ב-API, מהחדש לישן. שינויים שוברים מסומנים **[שובר]** ומתפרסמים כאן מראש; תיקוני אבטחה עשויים להיכנס מיד.

## אוקטובר 2026

- **[שובר] תיקי משכנתא** - כשלא נשלח `file_number`, התיק מקבל את המספר הבא של הארגון; המשתמש של מפתח ה-API נרשם כיוצר; רשימת המסמכים הנדרשים נוצרת; ו-`borrowers` (עד 10) נבדק לפני ששום דבר נשמר. `assigned_to` שאינו משתמש פעיל מחזיר 400 (עד כה המערכת התעלמה ממנו), והסטטוס `draft` נדחה. `PUT`/`PATCH` כותב רק שדות שהשתנו בפועל ואינו מפעיל אוטומציות כששום דבר לא השתנה; שינוי סטטוס מעדכן גם את `status_changed_at`. `PATCH /status` עם הסטטוס הנוכחי אינו עושה דבר, וה-`notes` שלו מופיעות בתיעודים של התיק באפליקציה.
- **לווים** - לווה עם שם ובלי `id_number` מקבל רשומת לקוח, כמו באפליקציה. פורמט מספר הזיהוי, השמות (או `entity_name` לחברות ולעמותות) וערכי enum מחזירים 400 במקום 500, ועדכון לעולם אינו נשמר באופן חלקי. לווה חדש מקבל את ה-`order_index` הבא; אי אפשר להסיר את הלווה הראשי כל עוד יש בתיק לווים אחרים. שדות חדשים: `nickname`, `education`, `residence_type`.
- **אנשי קשר בתיק ועוקבים** - לאנשי קשר בתיק יש `role` (ברירת מחדל: הסוג של איש הקשר), ולכן הם מופיעים בכרטיס "גורמים מעורבים" באפליקציה, ואפשר לקשר את אותו איש קשר בכמה תפקידים. תגובות הקישור והעוקבים כוללות את פרטי איש הקשר או המשתמש.
- **לקוחות** - תיקי המשכנתא של לקוח (`GET /customers/{id}`, `/customers/{id}/mortgage-files` ו-`GET /mortgage-files?customer_id=`) כוללים גם תיקים שבהם הלקוח הוא לווה - עד כה הרשימה הייתה כמעט תמיד ריקה - ושומר המחיקה (409) פועל לפי אותו כלל. חברות ועמותות משתמשות ב-`entity_name`. `id_type`, `marital_status`, `education`, `residence_type` ופורמט `id_number` נבדקים. שדות חדשים לכתיבה: `nickname`, `education`, `residence_type`; החיפוש מחפש גם ב-`entity_name` וב-`nickname`.
- **אנשי קשר** - `POST /contacts` עובד (עד כה החזיר תמיד 500). סוגים חדשים: `mortgage_advisor`, `real_estate_broker`, `housing_company`. קישורים לתיקים שנמחקו כבר לא חוסמים מחיקה של איש קשר.
- **לידים** - `status` שנשלח ב-`PUT`/`PATCH` מטופל כמו ב-`PATCH /leads/{id}/status` (היסטוריית סטטוסים, `status_changed_at`, `first_response_time`), ושליחת הסטטוס הנוכחי אינה כותבת דבר. `GET /leads/statuses` מחזיר מבנה אחיד לסטטוסי מערכת ולסטטוסים מותאמים (`value`, `label`, `color {bg, text}`, `is_default`, `order`) ולא מחזיר סטטוסים מושבתים. ליד שנוצר בלי `status` מקבל את סטטוס ברירת המחדל של הארגון. `?status=` מקבל מפתח של סטטוס מותאם. לידים שנוצרים דרך ה-API נרשמים עם `created_by`, מופיעים בציר הזמן של הליד ושולחים התראה למנהלי הארגון.
- **משימות** - התגובות כוללות `assignees` ו-`created_by`, ו-`completed_by` נרשם. `parent_task_id` דוחה מעגלים ושרשראות עמוקות מ-10 רמות. בנתיב `/mortgage-files/{id}/tasks/{taskId}`, שליחת `mortgage_file_id`, `lead_id` או `customer_id` שונים מחזירה 400 במקום שהמערכת תתעלם מהם.
- **הערות** - רק יוצר ההערה, או מפתח עם `admin`, `*` או `mortgage-files:*`, יכולים לשחרר או לערוך הערה נעולה (אחרת 403 עם `reason: note_locked`). התגובות כוללות `note_type`, `created_by`, `updated_by` ו-`completed_by`; דגלי `is_*` חייבים להיות בוליאניים.
- **ציר זמן** - `metadata` כולל רק את המפתחות המתועדים של כל סוג אירוע. סינון לפי `event_type` לא מוכר מחזיר 400.
- **[שובר] שדות מותאמים** - הערכים נקראים ונשמרים בתיק המשכנתא עצמו, שם האפליקציה מציגה אותם; עד כה ערכים שנקבעו דרך ה-API לא הופיעו באפליקציה. תגובת `PUT`/`PATCH` כבר לא כוללת `id`, `created_at` ו-`updated_at`, וכוללת עכשיו `field_name`. הערכים נבדקים מול סוג השדה; שדה לא פעיל מחזיר 400.
- **חיובים ותשלומים** - רישום, שינוי או ניתוק של תשלום מעדכנים את סטטוס החיוב (`pending`, `partial` או `paid`), כמו באפליקציה. `payment_source` חייב להיות מקור תשלום פעיל, אי אפשר לשייך תשלום לחיוב מבוטל (409), וקישור של חיוב לאבן דרך חייב לזהות אבן דרך קיימת.
- **תזכורות** - תזכורת בלי `recipient_user_id` נשלחת למשתמש של מפתח ה-API (או לאחראי על התיק) ולא לאף אחד. `channels` נבדק, והזזה של תזכורת שנשלחה למועד עתידי מחמשת אותה מחדש.
- **[שובר] סטטוסי מסמכים** - שינוי סטטוס נרשם בהיסטוריית הסטטוסים של הדרישה, כמו באפליקציה, ויכול לכלול `note`; `notes` לקריאה בלבד. דרישות שהוסרו מהתיק מוסתרות אלא אם נשלח `include_dismissed=true`. `GET /required-documents` משייך שורות סטטוס לדרישות כמו האפליקציה, ואת השאר מחזיר ב-`data.unlinked_statuses`.
- **אבני דרך** - `GET /milestones` תואם את מסך אבני הדרך של התיק: תנאי הצגה, אבני דרך שהוסרו או הועברו, סדר התיק ותאריכי יעד. נקודת הקצה החדשה `POST /mortgage-files/{id}/milestones/progress` משלימה או מעדכנת כל אבן דרך, גם כזו שעדיין אין לה שורת התקדמות. שורות התקדמות ופריטי צ'קליסט שהוסרו מוסתרים אלא אם נשלח `include_removed=true`.
- **[שובר] תמהילי מחשבון וניתוחים** - `data` של תמהיל חייב להיות בפורמט של המחשבון (`{version: 2, mixes: [...]}`) והוא חובה ביצירה, כך שתמהילים שנשמרים דרך ה-API נפתחים באפליקציה. `analysis_data` חייב להיות אובייקט JSON בגודל של עד 256KB.
- **תגובות וניתוב** - התגובות כוללות רק שדות מתועדים: עמודות פנימיות, תמונות חתימה וטיוטות חתימה כבר לא מוחזרות. שיטה שאינה נתמכת מחזירה 405 עם כותרת `Allow` (למשל, `POST /mortgage-files/{id}` כבר לא יוצר תיק), נתיב לא קיים מחזיר 404, ומזהה בפורמט לא תקין מחזיר 400. התגובות נשלחות עם `Cache-Control: private, no-store`.
- **שגיאות** - תקלה זמנית בשירות האימות מחזירה `503` עם `reason: auth_service_error` (עד כה `401`, שנראה כמו מפתח שבוטל). תשובת `429` כוללת את הכותרת התקנית `Retry-After`. `search` מתעלם מ-`*` ומוגבל ל-100 תווים.
- **אבטחה** - תזכורות כבר לא מקבלות `metadata` (הוא יכול היה לשלוט בשליחת הודעות). `source` של ליד שמפנה למקור ליד, לאיש קשר או ללקוח חייב להיות של הארגון. תיקי המשכנתא של לקוח (ב-`GET /customers/{id}` וב-`/customers/{id}/mortgage-files`) דורשים `mortgage-files:read`. שינוי פרטי לקוח דרך נקודות הקצה של הלווים דורש `customers:write`, ושדה שנשלח כ-`null` כבר לא מוחק ערך שמור של הלקוח. תגובות של משימות כבר לא כוללות את מספר הזהות של הלקוח המקושר ואת הטלפון של הליד המקושר.
- **מנוי** - כתיבה מארגון בלי מנוי פעיל מחזירה 403 עם `reason: subscription_inactive`, כמו באפליקציה. קריאה עדיין עובדת.
- אתר התיעוד הציבורי עלה בכתובת https://docs.banta.co.il באנגלית ובעברית, כולל גרסת LLM (`llms.txt`, `llms-full.txt` ו-Markdown לכל נקודת קצה) ומדריכים לאימות, להרשאות, לעימוד, לשגיאות ולמגבלות קצב.
- מסמך ה-OpenAPI עבר לאנגלית ועודכן כך שיתאים להתנהגות בפועל: תשובות שגיאה אחידות (401/403/404/429/500) בכל נקודות הקצה, ושדות שלא תועדו עד כה בחיובים ובאבני דרך. שמות התגיות בספק הם עכשיו באנגלית (למשל `Leads`).
- `GET /api-docs/openapi.json` מחזיר שוב את הספק המלא. עד כה הוחזרה גרסה מקוצרת וישנה.
- **אבטחה** - מזהים שנשלחים בגוף הבקשה (`customer_id`, `lead_id`, `source_lead_id`, `parent_task_id`, `recipient_user_id`, `charge_id`) נבדקים מול הארגון. מזהה של ארגון אחר מחזיר 400.
- **[שובר] הרשאות** - ההרשאה הכללית `write` כבר לא מתירה `DELETE`, בהתאם לאפשרות "קריאה וכתיבה" באפליקציה. מחיקה דורשת `admin`, `resource:*` או `resource:delete`.
- **מחיקות** - `DELETE /mortgage-files/{id}` ו-`DELETE /customers/{id}` מוחקים את הרשומה בפועל. עד כה הוחזרה הצלחה בלי שהרשומה נמחקה.
- **סטטוסים** - לידים מקבלים את הסטטוסים המותאמים של הארגון. תיק חדש מקבל את סטטוס ברירת המחדל של הארגון (או `setup`) במקום הערך הלא תקין `new`. `GET /mortgage-files/statuses` מחזיר את סטטוסי המערכת האמיתיים, `GET /mortgage-files/{id}/status-history` עובד, ושינוי סטטוס תיק שומר את `notes` כ-`status_comment`. שינוי סטטוס ליד שומר את `notes` בהיסטוריית הסטטוסים בלבד, ולא דורס עוד את ההערות של הליד.
- **משימות** - יצירת משימות עובדת. ערכי הסטטוס הם `open`, `in_progress`, `completed` ו-`cancelled` (`done` מתקבל כ-`completed`), ו-`completed_at` נקבע ומתאפס אוטומטית.
- **הערות** - אפשר לשחרר הערה נעולה עם `is_locked: false`.
- **שגיאות** - ערכים שמסד הנתונים דוחה מחזירים 400 (וכפילויות 409) במקום 500, ו-`child_errors` מכיל קודי שגיאה בלבד.
- `GET /customers/{id}/mortgage-files` מחזיר `{ data, count }` עם תיקי הלקוח.

## אוגוסט 2026

- **חיובים** - אפשר לקשר חיוב לאבן דרך עם `milestone_id` ו-`milestone_status_key` (חייבים להישלח יחד) ולהגדיר `milestone_due_offset_days`. כשאבן הדרך מושלמת, תאריך הגבייה נקבע אוטומטית. תאריך שהוזן ידנית לא נדרס.
- **לידים** - `DELETE /leads/{id}` מוחק את הליד לצמיתות. אי אפשר לשחזר ליד שנמחק.

## מאי 2026

- נוספו נקודות קצה מקוננות תחת תיק משכנתא: הערות, אנשי קשר בתיק, עוקבים, מסמכים, חתימות, מסמכים מיוצרים, סטטוס מסמכים, תזכורות, חיובים, תשלומים, ניתוחים, תמהילי מחשבון, שדות מותאמים ואבני דרך.
- נוספו משימות ברמה העליונה (`/tasks`), שמקושרות לתיק, לליד או ללקוח, או עומדות בפני עצמן.
- במסך המפתחות נוספה האפשרות **מותאם**, עם הרשאות לפי משאב ופעולה (`leads:read` וכדומה), כולל המשאב החדש `tasks`.

## אפריל 2026

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

## ינואר 2026

- נוספו אנשי קשר (`/contacts`), רשימות מערכת (`/lists`) ונקודות קצה לסטטוסים של לידים ותיקים.
- תמיכה בהכנסות, בחשבונות בנק ובהתחייבויות בעת יצירת תיק משכנתא, ובסוגי זיהוי נוספים ללווים (דרכון, עמותה, חברה).

---

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