ממשק SOAP

לצד נקודת הקצה של XML/JSON, TextMe חושפת שירות SOAP המכסה ארבע פעולות: שליחה, שליחה מרובה, דוחות מסירה ואימות שולח.

WSDL        https://my.textme.co.il/soap?wsdl
SOAPAction  https://my.textme.co.il/soap/

האימות זהה לזה של נקודת הקצה הרגילה — אותו טוקן bearer, שנשלח ככותרת MIME בשם Authorization על הודעת ה-SOAP.

באיזה ממשק להשתמש?

שירות ה-SOAP מכסה ארבע פעולות; נקודת הקצה /api מכסה יותר מעשרים, כולל רשימות תפוצה, רשימות חסימה, קמפיינים וחשבונות משנה. בחרו ב-SOAP רק אם קליינט מגונרט באמת קל יותר בסביבה שלכם — אחרת נקודת הקצה הראשית היא הממשק המלא.

אובייקטים

Response

מוחזר מ-sendSms ומ-sendBulkSms.

public class Response {
    int status;
    String message;
}

status פועל באותו סולם כמו בכל מקום אחר: 0 הוא הצלחה, וכל ערך אחר הוא קוד סטטוס. ה-message מסביר אותו — ריק בבקשה תקינה.

Phone

יעד אחד.

public class Phone {
    int phone;
    String id;
}

שדה	חובה	תיאור
phone	כן	מספר היעד, לדוגמה 50xxxxxxx.
id	לא	מזהה חיצוני משלכם ליעד הזה. שלחו מזהה ייחודי לכל יעד אם בכוונתכם לשלוף דוחות מסירה בהמשך.

Sms

הודעה אחת והיעדים שלה.

public class Sms {
    List<Phone> destinations;
    String message;
    String timing;
    String source;
}

שדה	חובה	תיאור
destinations	כן	לפחות אובייקט Phone אחד.
message	כן	גוף ההודעה.
source	כן	השולח שיופיע במכשיר.
timing	לא	שליחה בעתיד, בפורמט dd/mm/yy hh:ss. מתעלמים ממנו בתוך sendBulkSms.

Messages

אצווה של הודעות, לשימוש sendBulkSms.

public class Messages {
    List<Sms> sms;
}

נדרש לפחות אובייקט Sms אחד.

DlrRequest

השאילתה שנשלחת ל-getDlrReport.

public class DlrRequest {
    List<String> id;
    String from;
    String to;
}

שדה	חובה	תיאור
id	כן	המזהים החיצוניים שנשלחו באובייקטי ה-Phone בזמן השליחה.
from	כן	תחילת החלון, dd/mm/yy hh:ss.
to	כן	סוף החלון, באותו פורמט.

Dlr

דוח מסירה אחד. לקריאה בלבד — אתם לא ממלאים אותו.

public class Dlr {
    String id;
    String status;
    String heMessage;
    String enMessage;
    String date;
    int phone;
}

שדה	תיאור
id	המזהה החיצוני שנשלח בזמן שליחת ההודעה.
status	סטטוס המסירה — ראו סטטוסי מסירה.
heMessage	הסטטוס בעברית.
enMessage	הסטטוס באנגלית.
date	מועד רישום הסטטוס, dd/mm/yy hh:ss.
phone	היעד שאליו נשלחה ההודעה.

DlrResponse

מה ש-getDlrReport מחזיר.

public class DlrResponse {
    int status;
    String message;
    List<Dlr> dlrs;
}

status בערך 0 אומר שהדוח הופק — הוא לא אומר דבר על השאלה אם ההודעות הגיעו. זה מה ש-Dlr.status של כל רשומה נועד לו.

מתודות

sendSms

שולחת הודעה אחת לאחד או יותר יעדים. מתאימה כשכולם מקבלים את אותו טקסט.

Response r = sendSms("username", sms);

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:soap="https://my.textme.co.il/soap">
    <soapenv:Header/>
    <soapenv:Body>
        <soap:sendSms>
            <username>?</username>
            <sms>
                <!--1 or more repetitions:-->
                <destinations>
                    <!--You may enter the following 2 items in any order-->
                    <phone></phone>
                    <id></id>
                </destinations>
                <message></message>
                <timing></timing>
                <source></source>
            </sms>
        </soap:sendSms>
    </soapenv:Body>
</soapenv:Envelope>

sendBulkSms

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

Response r = sendBulkSms("username", messages);

כאן מתעלמים מ-timing

הגדרת timing על הודעה בתוך sendBulkSms אינה משפיעה. תזמנו עם sendSms, או השתמשו בפעולת bulk בנקודת הקצה הראשית, שכן מכבדת timing ברמת האצווה.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:soap="https://my.textme.co.il/soap">
    <soapenv:Header/>
    <soapenv:Body>
        <soap:sendBulkSms>
            <username></username>
            <sms>
                <!--1 or more repetitions:-->
                <sms>
                    <!--1 or more repetitions:-->
                    <destinations>
                        <!--You may enter the following 2 items in any order-->
                        <phone></phone>
                        <id></id>
                    </destinations>
                    <message></message>
                    <timing></timing>
                    <source></source>
                </sms>
            </sms>
        </soap:sendBulkSms>
    </soapenv:Body>
</soapenv:Envelope>

getDlrReport

שולפת דוחות מסירה עבור מזהים שנשלחו בזמן השליחה.

DlrResponse dr = getDlrReport("username", dlrRequest);

מגבלות החלון שונות מנקודת הקצה הראשית

ב-SOAP הטווח לא יעלה על 30 יום, והתאריך הרחוק ביותר שאפשר להגיע אליו הוא שנה אחורה. פעולת dlr בנקודת הקצה /api מאפשרת שבוע אחד בלבד לכל בקשה — כך שזה אחד הדברים הבודדים ש-SOAP עושה טוב יותר.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:soap="https://my.textme.co.il/soap">
    <soapenv:Header/>
    <soapenv:Body>
        <soap:getDlrReport>
            <username></username>
            <dlrRequest>
                <!--1 or more repetitions:-->
                <id></id>
                <from></from>
                <to></to>
            </dlrRequest>
        </soap:getDlrReport>
    </soapenv:Body>
</soapenv:Envelope>

verify_phone

שולחת מספר אחד או יותר לאימות כשולח. אותה פעולה כמו verify_phone בנקודת הקצה הראשית.

Response r = verify_phone("username", phones);

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:soap="https://my.textme.co.il/soap">
    <soapenv:Header/>
    <soapenv:Body>
        <soap:verify_phone>
            <username>?</username>
            <phones>
                <!--1 or more repetitions:-->
                <phone>?</phone>
            </phones>
        </soap:verify_phone>
    </soapenv:Body>
</soapenv:Envelope>

דוגמאות קליינט

PHP

ה-SoapClient המובנה של PHP דורש להעביר את הטוקן דרך stream context, כי אין לו אפשרות ישירה להוספת כותרות.

<?php
// המחלקות שה-WSDL ממופה אליהן.
class Phones {
    public $phone = [];
}

class Phone {
    public $id;
    public $phone;
    public $cl_id;
}

class Sms {
    public $destinations;
    public $message;
    public $timing;
    public $source;
    public $tag;
    public $add_unsubscribe;
}

class DlrRequest {
    public $id;
    public $from;
    public $to;
}

<?php
// חיבור, עם טוקן bearer בכל קריאה.
$url = 'https://my.textme.co.il/soap?wsdl';
$accessToken = getenv('TEXTME_API_TOKEN');

$httpHeaders = [
    'http' => [
        'protocol_version' => 1.1,
        'header' => 'Authorization: Bearer '.$accessToken."\r\n",
    ],
];

$context = stream_context_create($httpHeaders);
$wsclient = new SoapClient($url, ['stream_context' => $context, 'encoding' => 'UTF-8']);

<?php
// sendSms — אותו טקסט לשני יעדים.
$sms = new Sms();
$sms->source = 'Test';
$sms->message = 'sendSms test';

$phone = new Phone();
$phone->phone = ['055XXXXXXX', '052XXXXXXX'];
$phone->id = 'externalid1';

$sms->destinations = $phone;

$response = $wsclient->sendSms('username', '', $sms);
print_r($response);

<?php
// sendBulkSms — הודעה שונה לכל יעד.
$sms = new Sms();
$sms->source = 'Test';
$sms->message = 'sendBulkSms test';

$phone = new Phone();
$phone->phone = '052XXXXXXX';
$phone->id = 'externalid';
$sms->destinations = $phone;

$sms1 = new Sms();
$sms1->source = 'Test1';
$sms1->message = 'sendBulkSms test1';

$phone1 = new Phone();
$phone1->phone = '052XXXXXXX';
$phone1->id = 'externalid1';
$sms1->destinations = $phone1;

$response = $wsclient->sendBulkSms('username', '', [$sms, $sms1]);
print_r($response);

<?php
// getDlrReport — שליפת הדוחות עבור אותם מזהים חיצוניים.
$dlr = new DlrRequest();
$dlr->id = ['externalid', 'externalid1'];
$dlr->from = '01/05/26 00:00';
$dlr->to = '07/05/26 18:29';

$response = $wsclient->getDlrReport('username', '', $dlr);
print_r($response);

Java

בנוי על javax.xml.soap, עם הרכבת המעטפה ידנית והצמדת הטוקן ככותרת MIME.

import javax.xml.soap.*;
import java.util.ArrayList;

public class TextMeSoapBulk {
    private static SOAPElement smsContainer;

    public static void main(String[] args) {
        String endpoint = "https://my.textme.co.il/soap?wsdl";
        String soapAction = "https://my.textme.co.il/soap/";
        String token = System.getenv("TEXTME_API_TOKEN");
        String username = "";  // שם המשתמש של החשבון שלכם
        String source = "";    // שולח מאומת
        String message = "";   // הטקסט לשליחה

        ArrayList<String> destinations = new ArrayList<>();
        destinations.add("55999xxxx");

        call(endpoint, soapAction, username, token, message, source, destinations);
    }

    private static void createEnvelope(SOAPMessage soapMessage, String username)
            throws SOAPException {
        SOAPEnvelope envelope = soapMessage.getSOAPPart().getEnvelope();
        envelope.addNamespaceDeclaration("xsi", "http://www.w3.org/2001/XMLSchema");

        SOAPElement body = envelope.getBody().addChildElement("sendBulkSms");
        body.addChildElement("username").addTextNode(username);
        smsContainer = body.addChildElement("sms");
    }

    private static void addDestination(String phone, String message, String source) {
        try {
            SOAPElement sms = smsContainer.addChildElement("sms");
            SOAPElement destinations = sms.addChildElement("destinations");
            destinations.addChildElement("phone").addTextNode(phone);
            sms.addChildElement("message").addTextNode(message);
            sms.addChildElement("source").addTextNode(source);
        } catch (SOAPException e) {
            e.printStackTrace();
        }
    }

    private static void call(String endpoint, String soapAction, String username,
            String token, String message, String source, ArrayList<String> destinations) {
        try (SOAPConnection connection = SOAPConnectionFactory.newInstance().createConnection()) {
            SOAPMessage request = MessageFactory.newInstance().createMessage();
            createEnvelope(request, username);

            for (String destination : destinations) {
                addDestination(destination, message, source);
            }

            MimeHeaders headers = request.getMimeHeaders();
            headers.addHeader("SOAPAction", soapAction);
            headers.addHeader("Authorization", "Bearer " + token);
            request.saveChanges();

            SOAPMessage response = connection.call(request, endpoint);
            response.writeTo(System.out);
        } catch (Exception e) {
            System.err.println("SOAP request failed — check the endpoint URL and SOAPAction.");
            e.printStackTrace();
        }
    }
}

מ-Java, עדיף את נקודת הקצה הראשית

הרכבת מעטפות SOAP ידנית היא הרבה טקס עבור הודעה אחת. אותה שליחה דרך נקודת הקצה /api היא תריסר שורות של java.net.http — הלשונית Java בכל עמוד נקודת קצה מציגה אותה.