# קשר כשר — API לשליחת הודעות (v1)

‏API חיצוני לשליחת הודעות ווצאפ מהמערכות שלך (אתר, CRM, אוטומציות) דרך החיבור של המשתמש.

## מפתח API

1. בדשבורד, בכרטיס **API**, צור מפתח חדש (עם תיאור לזיהוי).
2. המפתח בפורמט `kk_live_<32 תווים>` מוצג **פעם אחת בלבד** — שמור אותו במקום בטוח (במערכת נשמר רק hash).
3. מפתח שבוטל נדחה מיידית (401).

כל בקשה נשלחת עם כותרת:

```
Authorization: Bearer kk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

**מגבלת קצב:** עד 30 בקשות בדקה לכל מפתח (חריגה מחזירה 429).

## שליחת הודעה

`POST /api/v1/messages`

גוף הבקשה (JSON):

| שדה | חובה | תיאור |
|---|---|---|
| `to` | כן | מספר בפורמט בינלאומי (`9725XXXXXXXX`) או JID מלא (`...@s.whatsapp.net` / `...@g.us` לקבוצה) |
| `text` | * | טקסט ההודעה |
| `attachments` | * | מערך של עד 10 קבצים: `{filename, contentBase64, mime}`, עד 5MB לקובץ (לפני קידוד) |

\* נדרש לפחות אחד מ-`text` / `attachments`.

ההודעה נכנסת לתור ונשלחת דרך ה-session של המשתמש בקצב אנושי. תשובה מוצלחת (202):

```json
{ "id": 123, "status": "queued" }
```

### דוגמה — טקסט בלבד

```bash
curl -X POST https://kesher-kasher.co.il/api/v1/messages \
  -H "Authorization: Bearer kk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "972501234567",
    "text": "שלום! ההזמנה שלך מוכנה לאיסוף."
  }'
```

### דוגמה — עם קובץ מצורף

```bash
curl -X POST https://kesher-kasher.co.il/api/v1/messages \
  -H "Authorization: Bearer kk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d "{
    \"to\": \"972501234567\",
    \"text\": \"מצורפת החשבונית\",
    \"attachments\": [{
      \"filename\": \"invoice.pdf\",
      \"mime\": \"application/pdf\",
      \"contentBase64\": \"$(base64 -w0 invoice.pdf)\"
    }]
  }"
```

## בדיקת סטטוס

`GET /api/v1/messages/{id}`

```bash
curl https://kesher-kasher.co.il/api/v1/messages/123 \
  -H "Authorization: Bearer kk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
```

תשובה:

```json
{ "id": 123, "status": "sent", "error": null, "created_at": 1753000000, "sent_at": 1753000004 }
```

| סטטוס | משמעות |
|---|---|
| `pending` | בתור — ממתין לשליחה (או לחיבור ה-session) |
| `sent` | נשלח בווצאפ |
| `failed` | השליחה נכשלה — ראה שדה `error` |

## קודי שגיאה

| קוד | משמעות |
|---|---|
| 400 | בקשה לא תקינה (יעד/קבצים/גוף) — הודעת השגיאה בעברית בשדה `error` |
| 401 | מפתח חסר, לא מוכר או שבוטל |
| 404 | הודעה לא נמצאה (או שייכת למשתמש אחר) |
| 429 | חריגה ממגבלת הקצב (30 בקשות/דקה) |

## הערות

- אם ה-session של המשתמש מנותק, ההודעה נשארת `pending` ותישלח אוטומטית כשהחיבור יחזור.
- שליחה לקבוצה: השתמש ב-JID של הקבוצה (מוצג בדשבורד ככתובת המייל של השיחה — `chat-{id}@...`; ה-JID עצמו זמין דרך תמיכה או ברשימת השיחות).
- בסביבת פיתוח מקומית הכתובת היא `http://localhost:3010`.