# התחלה מהירה

## 1. יצירת מפתח API

1. התחברו ל-banta עם משתמש שיש לו הרשאה לנהל אינטגרציות בארגון.
2. עברו אל [הגדרות הארגון ← חיבורים וטכנולוגיה ← מפתחות API](https://app.banta.co.il/organization/settings?group=integrations&tab=api).
3. לחצו על יצירת מפתח חדש, תנו לו שם שמתאר את השימוש (למשל "טופס לידים באתר") ובחרו הרשאות. מומלץ לבחור את המינימום הנדרש; פירוט ב[אימות והרשאות](https://docs.banta.co.il/he/guides/authentication.md).
4. **העתיקו את המפתח מיד.** הוא מוצג פעם אחת בלבד, ואי אפשר לשחזר אותו אחר כך.

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

## 2. הקריאה הראשונה

שליפת חמשת הלידים האחרונים:

```bash
curl "https://app.banta.co.il/api-service/leads?limit=5" \
  -H "x-api-key: $BANTA_API_KEY"
```

התגובה היא רשימה עם מונה כולל:

```json
{
  "data": [
    {
      "id": "6f1c2a4e-0b7d-4b8e-9a51-2f6c3d8e9a10",
      "first_name": "ישראל",
      "last_name": "ישראלי",
      "phone": "050-0000000",
      "status": "new",
      "created_at": "2026-10-01T09:30:00+00:00"
    }
  ],
  "count": 128
}
```

`count` הוא מספר כל הרשומות שתואמות לשאילתה, לא רק אלה שבעמוד הנוכחי. ראו [עימוד וחיפוש](https://docs.banta.co.il/he/guides/conventions.md).

## 3. יצירת ליד

```bash
curl -X POST "https://app.banta.co.il/api-service/leads" \
  -H "x-api-key: $BANTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "ישראל",
    "last_name": "ישראלי",
    "phone": "050-0000000",
    "email": "israel@example.com",
    "source": "website"
  }'
```

תגובה מוצלחת מחזירה `201 Created` ואת הליד המלא, כולל ה-`id` שנוצר.

## אותה קריאה בשפות נפוצות

**JavaScript (Node.js 18 ומעלה, כמודול ES - קובץ `.mjs` או `"type": "module"` ב-`package.json`):**

```js
const res = await fetch('https://app.banta.co.il/api-service/leads', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.BANTA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'ישראל',
    last_name: 'ישראלי',
    phone: '050-0000000',
    source: 'website',
  }),
})

if (!res.ok) {
  const err = await res.json()
  throw new Error(`banta API ${res.status}: ${err.error} ${err.details ?? ''}`)
}
const lead = await res.json()
```

**Python:**

```python
import os
import requests

res = requests.post(
    "https://app.banta.co.il/api-service/leads",
    headers={"x-api-key": os.environ["BANTA_API_KEY"]},
    json={
        "first_name": "ישראל",
        "last_name": "ישראלי",
        "phone": "050-0000000",
        "source": "website",
    },
    timeout=30,
)
if not res.ok:
    err = res.json()
    raise RuntimeError(f"banta API {res.status_code}: {err.get('error')} {err.get('details', '')}")
lead = res.json()
```

## בדיקות בלי סיכון

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

- צרו מפתח בדיקות ייעודי עם ההרשאות שאתם בודקים בלבד (למשל `leads:read`, `leads:write` ו-`leads:delete`), ובטלו אותו בסוף.
- סמנו רשומות בדיקה כך שיהיה קל למצוא אותן, למשל `"source": "api-test"` בליד, ומחקו אותן בסוף (`DELETE /leads/{id}`).

## Postman, Insomnia ולקוחות מוקלדים

אין SDK רשמי. מסמך ה-OpenAPI מלא מספיק כדי לייצר אחד:

- **Postman / Insomnia** - ייבאו את `https://docs.banta.co.il/openapi.json` והגדירו את הכותרת `x-api-key` ממשתנה של האוסף.
- **TypeScript** - ייצרו טיפוסים והשתמשו בלקוח fetch מוקלד:

  ```bash
  npx openapi-typescript https://docs.banta.co.il/openapi.json -o banta.d.ts
  npm install openapi-fetch
  ```

- **Python** - `openapi-python-client generate --url https://docs.banta.co.il/openapi.json`

## מה הלאה

- [אימות והרשאות](https://docs.banta.co.il/he/guides/authentication.md) - איך לצמצם את ההרשאות של מפתח.
- [שגיאות](https://docs.banta.co.il/he/guides/errors.md) ו[מגבלות קצב](https://docs.banta.co.il/he/guides/rate-limits.md) - איך לטפל בכשלים.

---

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