# עימוד, חיפוש ומבנה תגובות

## מבנה התגובה

| סוג קריאה | סטטוס | גוף התגובה |
|---|---|---|
| רשימה (`GET /leads`) | `200` | אובייקט `{ "data": [...], "count": N }` |
| רשומה בודדת (`GET /leads/{id}`) | `200` | הרשומה עצמה |
| יצירה (`POST`) | `201` | הרשומה שנוצרה, כולל `id` |
| עדכון (`PUT` / `PATCH`) | `200` | הרשומה המעודכנת |
| מחיקה (`DELETE`) | `200` | אישור, למשל `{ "success": true, "message": "..." }` |

ברשימות מעומדות, `count` הוא המספר הכולל של הרשומות שתואמות לשאילתה, לא רק אלה שבעמוד הנוכחי. ברשימות קצרות שאינן מעומדות (למשל לווים בתיק), `count` שווה לאורך המערך.

## עימוד

רשימות גדולות מעומדות עם שני פרמטרים:

| פרמטר | ברירת מחדל | מקסימום | תיאור |
|---|---|---|---|
| `limit` | `50` | `500` | מספר הרשומות בעמוד |
| `offset` | `0` | `1000000` | כמה רשומות לדלג |

ערך לא חוקי (שלילי, לא מספרי) לא מחזיר שגיאה: הוא מוחלף בברירת המחדל. ערך גדול מהמקסימום מוגבל למקסימום. התוצאות ממוינות מהחדש לישן (`created_at` יורד), אלא אם צוין אחרת בנקודת הקצה.

מעבר על כל הרשומות (רשומה שנוצרת באמצע המעבר מזיזה את העמודים הבאים ברשומה אחת, ולכן הדוגמה מסירה כפילויות לפי `id`):

```js
// bantaFetch handles 429 - see Rate limits
async function fetchAll(path, params = {}) {
  const limit = 500
  const byId = new Map()
  for (let offset = 0; ; offset += limit) {
    const url = new URL(`https://app.banta.co.il/api-service${path}`)
    for (const [k, v] of Object.entries({ ...params, limit, offset })) url.searchParams.set(k, v)
    const res = await bantaFetch(url, { headers: { 'x-api-key': process.env.BANTA_API_KEY } })
    if (!res.ok) throw new Error(`HTTP ${res.status}`)
    const { data, count } = await res.json()
    for (const row of data) byId.set(row.id, row)
    if (data.length < limit || offset + limit >= count) return [...byId.values()]
  }
}

// fetchAll('/leads', { status: 'new' })
```

> במעבר על הרבה עמודים שימו לב ל[מגבלת הקצב](https://docs.banta.co.il/he/guides/rate-limits.md), 60 בקשות בדקה. 500 רשומות בעמוד הן הדרך היעילה ביותר.

## חיפוש

נקודות קצה שתומכות בחיפוש מקבלות את הפרמטר `search`. החיפוש אינו רגיש לאותיות גדולות וקטנות, ומחפש את הביטוי בתוך כמה שדות במקביל (למשל שם, טלפון ואימייל). השדות המדויקים מפורטים בכל נקודת קצה.

```bash
curl "https://app.banta.co.il/api-service/customers?search=ישראלי" -H "x-api-key: $BANTA_API_KEY"
```

התווים `, ( ) % _ \ " ' *` מוסרים מהביטוי, הביטוי נחתך ל-100 תווים, והשאר מחופש כמחרוזת מדויקת בתוך השדה. בפועל:

- `0501234567` לא ימצא את `050-1234567`. חפשו חלק מהמספר בלי מקף, למשל `1234567`.
- שם עם גרש, כמו `ג'ורג'`, לא יימצא. חפשו חלק מהשם בלי סימני הפיסוק.
- אימייל שמכיל `_` לא יימצא בשלמותו. חפשו את הדומיין או חלק אחר ממנו.

## סינון

חלק מהרשימות מקבלות פרמטרי סינון נוספים, למשל `status` ברשימת הלידים. הפרמטרים הזמינים מפורטים בכל נקודת קצה.

## PUT מול PATCH

במשאבים שתומכים בשניהם, `PUT` ו-`PATCH` מתנהגים אותו דבר: **עדכון חלקי**. נשלחים רק השדות שרוצים לשנות, ושדות שלא נשלחו נשארים כפי שהם. שדות שאינם ניתנים לעדכון (כמו `id`, `organization_id` ו-`created_at`) מתעלמים מהם בשקט. אם לא נשלח אף שדה שניתן לעדכן, מוחזרת שגיאה `400 No updatable fields provided`.

מזהים בנתיב: מזהה בפורמט לא תקין מחזיר `400`; מזהה שאינו קיים, שנמחק או ששייך לארגון אחר מחזיר `404`.

## תופעות לוואי של כתיבה

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

- אל תשלחו שוב רשומות שלא השתנו בכל סנכרון. `PUT`/`PATCH` על תיק משכנתא כותב רק שדות שהשתנו בפועל ואינו עושה דבר כששום דבר לא השתנה, ושליחת הסטטוס הנוכחי של ליד או של תיק אינה כותבת דבר - אבל משאבים אחרים עדיין עשויים לרשום שינוי.
- שינויים דרך ה-API לא נדחפים לפנקס הכתובות של Google או Microsoft שהארגון מסנכרן עם banta, וה-API לא יוצר תיקיות ב-Google Drive.

## מזהי משתמשים

`assigned_to`, `watcher_id` ו-`recipient_user_id` מקבלים מזהה של משתמש פעיל בארגון. ה-API עדיין לא מחזיר רשימת משתמשים; קחו את המזהים מרשומות קיימות (`assigned_to` בליד או בתיק, `assignees` במשימה, `watcher_id` ב-`GET /mortgage-files/{id}/watchers`).

מזהה שאינו של משתמש פעיל בארגון מחזיר `400` בתיקי משכנתא ובתזכורות, ו-`404` ב-`watcher_id`. בלידים ובמשימות המערכת מתעלמת ממנו: רשומה חדשה נוצרת ללא הקצאה, ועדכון משאיר את ההקצאה הקיימת.

## המרת ליד לתיק משכנתא

עדיין אין נקודת קצה להמרה. כדי להפוך ליד לתיק משכנתא:

1. צרו את התיק עם `POST /mortgage-files`, ושלחו את `source_lead_id` (מזהה הליד) ואת `borrowers`.
2. שנו את סטטוס הליד עם `PATCH /leads/{id}/status` לסטטוס שמסמן בארגון ליד שהומר (למשל `converted`; ראו `GET /leads/statuses`).

בשונה מהמרה באפליקציה, המסמכים, ההערות ותמהילי המחשבון של הליד לא מועתקים לתיק החדש.

## ערכים קבועים

ערכי enum (סוגי תעסוקה, סוגי משכנתא, סטטוסים וכדומה) זמינים מנקודות הקצה תחת [רשימות מערכת](https://docs.banta.co.il/he/#tag/lists). השתמשו בהן כדי לבנות טפסים ולא לקודד את הערכים בקוד. סטטוסי לידים ותיקים יכולים להיות מותאמים לארגון, ולכן שלפו אותם מ-`/leads/statuses` ומ-`/mortgage-files/statuses`.

---

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