---
url: https://textme-docs.matat.io/he/guide/request-format.md
description: >-
  אותו מסמך ב-XML או ב-JSON, אלמנטים חוזרים כמערכים, מוסכמת ה-$ וה-_, מעטפת
  התשובה, ואימות מול api/test.
---

# מבנה הבקשה

ה-API של TextMe מקבל את אותו מסמך בשני פורמטים. שלחו XML עם `Content-Type: application/xml`, או את ה-JSON המקביל עם `Content-Type: application/json`, והתשובה תחזור באותו פורמט שבו נשלחה הבקשה.

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

## המעטפה

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

::: code-group

```xml [XML]
<?xml version="1.0" encoding="UTF-8"?>
<sms>
    <user>
        <username>Leeroy</username>
    </user>
    <source>DemoAPI</source>
    <destinations>
        <phone>5xxxxxxxx</phone>
    </destinations>
    <message>Hello</message>
</sms>
```

```json [JSON]
{
  "sms": {
    "user": { "username": "Leeroy" },
    "source": "DemoAPI",
    "destinations": { "phone": "5xxxxxxxx" },
    "message": "Hello"
  }
}
```

:::

אלמנט השורש הוא בוחר הפעולה: `sms`, `bulk`, `dlr`, `newCL`, `blacklist` וכן הלאה. שליחת שורש שאינו מזוהה מחזירה סטטוס `997`, *Not a valid command sent*.

## אלמנטים חוזרים הופכים למערכים

ב-XML מבטאים רשימה על ידי חזרה על אלמנט. ב-JSON אותה רשימה היא מערך, וכשיש רק פריט אחד, ה-API מקבל גם את הערך עצמו ללא מערך.

::: code-group

```xml [XML]
<destinations>
    <phone>5xxxxxxx1</phone>
    <phone>5xxxxxxx2</phone>
</destinations>
```

```json [JSON]
{
  "destinations": {
    "phone": ["5xxxxxxx1", "5xxxxxxx2"]
  }
}
```

:::

## תכונות הופכות ל-`$`, טקסט הופך ל-`_`

לחלק מאלמנטי ה-XML יש תכונות (attributes). ה-`id` על `<phone>`, ה-`id` על `<link>`. ב-JSON אין תכונות, ולכן ה-API משתמש במוסכמה המקובלת בהמרות XML ל-JSON: **`$` מחזיק את התכונות, `_` מחזיק את הטקסט של האלמנט**.

::: code-group

```xml [XML]
<destinations>
    <phone id="order-10052">5xxxxxxxx</phone>
    <phone>5xxxxxxxx</phone>
</destinations>
```

```json [JSON]
{
  "destinations": {
    "phone": [
      { "$": { "id": "order-10052" }, "_": "5xxxxxxxx" },
      { "_": "5xxxxxxxx" }
    ]
  }
}
```

:::

אלמנט בלי תכונות יכול להישאר מחרוזת פשוטה, כמו בדוגמה הראשונה בעמוד הזה. המוסכמה מופיעה רק במקומות שבהם XML היה משתמש בתכונה. בפועל, ה-`id` על `phone` ועל `link`.

::: tip באיזה פורמט לבחור?
XML הוא הפורמט המקורי של ה-API, והדוגמאות של הספק עצמו כתובות בו. JSON קל יותר לבנייה ולפענוח ברוב הסביבות המודרניות, והוא זה שמופיע בדוגמאות הקוד באתר הזה. אף אחד מהם אינו מוקפא. בחרו את מה שהקוד שלכם מטפל בו בטבעיות.
:::

## מעטפת התשובה

כל תשובה נפתחת באותם שני שדות.

| שדה | סוג | משמעות |
|---|---|---|
| `status` | int | `0` בהצלחה. כל ערך אחר הוא שגיאה. |
| `message` | string | הערה קריאה לאדם. בהצלחה היא מתארת מה קרה (`SMS will be sent`); בכשל היא מסבירה את השגיאה. |

לאחר מכן מגיעים הנתונים הספציפיים לפעולה: `shipment_id` אחרי שליחה, `transactions` בדוח, `contact_lists` בקריאת רשימות וכן הלאה.

::: code-group

```xml [XML]
<?xml version="1.0" encoding="UTF-8"?>
<sms>
    <status>0</status>
    <message>SMS will be sent</message>
    <shipment_id>xxxxxxx</shipment_id>
</sms>
```

```json [JSON]
{
  "status": 0,
  "message": "SMS will be sent",
  "shipment_id": "XXXXXXX"
}
```

:::

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

::: warning `status` הוא לא סטטוס ה-HTTP
שכבת התעבורה עונה כמעט תמיד `HTTP 200`, כולל בכשלי אימות ובשגיאות ולידציה. התנו את הלוגיקה בשדה `status` שבגוף התשובה, ולא בקוד ה-HTTP לבדו.
:::

## ערכים ופורמטים

| סוג שדה | פורמט | הערות |
|---|---|---|
| מספר טלפון | `5xxxxxxxx` או `05xxxxxxx` | מספרים נייחים באותו מבנה (`3xxxxxxx`). מספרים קצרים או ארוכים מדי נדחים בסטטוס `9`. |
| תאריך ושעה | `dd/mm/yy hh:mm` | `30/03/26 10:10`. שנה בשתי ספרות, שעון 24 שעות. |
| שולח | עד 11 תווים | אותיות באנגלית וספרות בלבד, בלי `+`. חייב להיות [מאומת](../endpoints/verified-senders.md), אחרת הקריאה נכשלת בסטטוס `515`. |
| גוף ההודעה | עד 1005 תווים | גוף ארוך יותר או ריק מחזיר סטטוס `989`. |
| שם קמפיין | עד 50 תווים | גם כאן סטטוס `989` כשהשם ארוך מדי. |
| דגלים | `1` או `0` | נשלחים כמחרוזות. כל ערך שאינו הערך המתועד נקרא כ"לא". |

עברית, אמוג'י וטקסט לא-לטיני אחר עובדים ללא בעיה. כל ה-API הוא UTF-8. שימו לב שתווים שאינם GSM מקטינים את כמות הטקסט שנכנסת למקטע הודעה אחד לחיוב.

## בדיקה בלי שליחה {#testing-without-sending}

```http
POST https://my.textme.co.il/api/test
```

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

זה המקום הנכון לוודא שגוף הבקשה תקין לפני שמפנים את אותו קוד אל `/api`. היא לא תגיד לכם אם מספר מסוים ניתן להשגה, והיא לא יוצרת `shipment_id` שאפשר להפיק עליו דוחות אחר כך.

## מה יכול להשתבש

| Status | משמעות |
|---|---|
| `1` | לא ניתן היה לפרסר את ה-XML. מסמך פגום, תג לא סגור, או גוף שאינו XML כלל. |
| `2` | חסר שדה חובה. ה-`message` מציין איזה. |
| `997` | אלמנט השורש אינו פעולה מזוהה. |
| `998` | שגיאה לא ידועה בבקשה. |

הרשימה המלאה, כולל קודים ספציפיים לכל פעולה, נמצאת ב[קודי סטטוס](../reference/status-codes.md).