מבנה הבקשה

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

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

המעטפה

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

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

{
  "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 מקבל גם את הערך עצמו ללא מערך.

XML

<destinations>
    <phone>5xxxxxxx1</phone>
    <phone>5xxxxxxx2</phone>
</destinations>

JSON

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

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

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

XML

<destinations>
    <phone id="order-10052">5xxxxxxxx</phone>
    <phone>5xxxxxxxx</phone>
</destinations>

JSON

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

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

באיזה פורמט לבחור?

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

מעטפת התשובה

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

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

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

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

{
  "status": 0,
  "message": "SMS will be sent",
  "shipment_id": "XXXXXXX"
}

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

status הוא לא סטטוס ה-HTTP

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

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

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

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

בדיקה בלי שליחה

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

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

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

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

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

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