# אימות וכללי יסוד — מסר גו API

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

---

## כתובת בסיס (Base URL)

```
https://capi.mesergo.co.il
```

כל ה-endpoints בתיעוד (SMS, מיילים, אנשי קשר) פועלים תחת דומיין זה. הבקשות הן `HTTPS` בלבד וקידוד התוכן הוא **UTF-8**.

---

## אימות (Authentication)

האימות מבוצע בשיטת **HTTP Basic Authentication**: שם המשתמש והטוקן שקיבלתם ממערכת מסר גו נשלחים בכותרת `Authorization`.

- **Username** — שם המשתמש שלכם במערכת.
- **Token** — טוקן ה-API שהופק עבורכם.

הערך בכותרת הוא `Base64` של המחרוזת `Username:Token`:

```http
Authorization: Basic <base64(username:token)>
Content-Type: application/json
```

### דוגמת cURL

```bash
curl https://capi.mesergo.co.il/api/v2/SMS/SendSms \
  -u "USERNAME:TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "Data": { "Message": "שלום", "Recipients": [{ "Phone": "0501234567" }] } }'
```

### דוגמת C#

```csharp
string username = "YOUR_USERNAME";
string token = "YOUR_TOKEN";
string creds = Convert.ToBase64String(Encoding.ASCII.GetBytes(username + ":" + token));
request.Headers.Add("Authorization", "Basic " + creds);
```

### דוגמת PHP

```php
$username = "YOUR_USERNAME";
$token = "YOUR_TOKEN";
$ch = curl_init();
curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $token);
```

> 💡 אפשר לנסות את כל הקריאות אונליין בעזרת [הסימולטור](playground.html) — מזינים שם משתמש וטוקן ושולחים בקשה חיה.

---

## מגבלת קצב (Rate Limit)

מגבלת הקצב היא **30 קריאות בשנייה**. קריאות מעבר ל-30 בשנייה יחזירו שגיאה `-429 Too many requests`.

---

## קודי סטטוס בתגובה (Response Status Codes)

התגובה כוללת שדה `StatusId` (או `Status`) עם משמעות הסטטוס:

| קוד | משמעות |
|-----|--------|
| `1` | Success — הצלחה |
| `-1` | Failed — כשל כללי |
| `-2` | Bad user name or password — שם משתמש/סיסמה שגויים |
| `-6` | RecipientsDataNotExists — אין נתוני נמענים |
| `-9` | MessageTextNotExists — חסר טקסט הודעה |
| `-13` | UserQuotaExceeded — חריגת מכסת משתמש |
| `-14` | ProjectQuotaExceeded — חריגת מכסת פרויקט |
| `-15` | CustomerQuotaExceeded — חריגת מכסת לקוח |
| `-16` | WrongDateTime — תאריך/שעה שגויים |
| `-17` | WrongNumberParameter — פרמטר מספרי שגוי |
| `-18` | No valid recipients — אין נמענים תקינים |
| `-21` | InvalidSenderName — שם שולח לא תקין |
| `-22` | UserBlocked — משתמש חסום |
| `-26` | UserAuthenticationError — שגיאת אימות משתמש |
| `-90` | InvalidSenderIdentification — זיהוי שולח לא תקין |
| `-94` | SenderId is not in allow list — שם השולח אינו ברשימת ההיתר |
| `-96` | MessageLengthExceeded — חריגה מ-1000 תווים |
| `-180` | Illegal Custom Field Name — תו לא חוקי בשם שדה מותאם |
| `-181` | Missing Custom Field Value — חסר ערך לשדה מותאם |
| `-230` | Invalid Url — כתובת URL לא תקינה |
| `-291` | Unverified Sender ID — שם שולח לא מאומת |
| `-429` | Too many requests — חריגת מגבלת קצב |
| `-524` | MaxAmountOfSmsInOneMinuteReached — חריגת כמות SMS בדקה |
| `-1159` | Invalid TemplateComponents — תו לא חוקי בתבנית/כפתורים |

---

## העלאת קבצים (File Upload)

לשליחת מדיה/קבצים (למשל צרופות למייל) ניתן להעלות קובץ ולקבל מזהה/כתובת לשימוש בבקשות.

```http
POST https://capi.mesergo.co.il/api/v2/Files/Upload
Authorization: Basic <base64(username:token)>
```

הגוף הוא `multipart/form-data` עם שדה הקובץ. פרטים מלאים ל-Base64 כצרופה מופיעים בדוגמת המייל *Example Base64 File attached* ב-[email.md](email.md).

---

## בדיקת מכסה (Get Quota)

```http
POST https://capi.mesergo.co.il/api/v2/Admin/GetQuota
Authorization: Basic <base64(username:token)>
Content-Type: application/json
```

מחזיר את יתרת המכסה הזמינה לחשבון.

---

## מסמכי המשך

- [sms.md](sms.md) — שליחת SMS, DLR, קבלת הודעות, OTP ודוחות.
- [email.md](email.md) — שליחת מיילים וניהול קמפיינים.
- [contacts.md](contacts.md) — ניהול אנשי קשר, קבוצות והסרה מרשימת תפוצה.
- [playground.html](playground.html) — סימולטור אונליין לניסוי הקריאות.