---
url: https://textme-docs.matat.io/he/reference/soap.md
description: >-
  ממשק ה-SOAP: האובייקטים, ארבע המתודות, במה מגבלות החלון שלו שונות מ-api,
  ודוגמאות קליינט ב-PHP וב-Java.
---

# ממשק SOAP

לצד [נקודת הקצה של XML/JSON](../guide/request-format.md), TextMe חושפת שירות SOAP המכסה ארבע פעולות: שליחה, שליחה מרובה, דוחות מסירה ואימות שולח.

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

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

::: tip באיזה ממשק להשתמש?
שירות ה-SOAP מכסה ארבע פעולות; נקודת הקצה `/api` מכסה יותר מעשרים, כולל רשימות תפוצה, רשימות חסימה, קמפיינים וחשבונות משנה. בחרו ב-SOAP רק אם קליינט מגונרט באמת קל יותר בסביבה שלכם. אחרת [נקודת הקצה הראשית](../endpoints/overview.md) היא הממשק המלא.
:::

## אובייקטים

### `Response`

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

```java
public class Response {
    int status;
    String message;
}
```

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

### `Phone`

יעד אחד.

```java
public class Phone {
    int phone;
    String id;
}
```

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

### `Sms`

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

```java
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`.

```java
public class Messages {
    List<Sms> sms;
}
```

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

### `DlrRequest`

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

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

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

### `Dlr`

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

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

| שדה | תיאור |
|---|---|
| `id` | המזהה החיצוני שנשלח בזמן שליחת ההודעה. |
| `status` | סטטוס המסירה. ראו [סטטוסי מסירה](./dlr-statuses.md). |
| `heMessage` | הסטטוס בעברית. |
| `enMessage` | הסטטוס באנגלית. |
| `date` | מועד רישום הסטטוס, `dd/mm/yy hh:ss`. |
| `phone` | היעד שאליו נשלחה ההודעה. |

### `DlrResponse`

מה ש-`getDlrReport` מחזיר.

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

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

## מתודות

### `sendSms`

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

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

```xml
<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` {#sendbulksms}

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

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

::: warning כאן מתעלמים מ-`timing`
הגדרת `timing` על הודעה בתוך `sendBulkSms` אינה משפיעה. תזמנו עם `sendSms`, או השתמשו בפעולת [`bulk`](../endpoints/bulk.md) בנקודת הקצה הראשית, שכן מכבדת `timing` ברמת האצווה.
:::

```xml
<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` {#getdlrreport}

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

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

::: warning מגבלות החלון שונות מנקודת הקצה הראשית
ב-SOAP הטווח לא יעלה על **30 יום**, והתאריך הרחוק ביותר שאפשר להגיע אליו הוא **שנה** אחורה. פעולת [`dlr`](../endpoints/reports.md) בנקודת הקצה `/api` מאפשרת **שבוע** אחד בלבד לכל בקשה, כך שזה אחד הדברים הבודדים ש-SOAP עושה טוב יותר.
:::

```xml
<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`](../endpoints/verified-senders.md) בנקודת הקצה הראשית.

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

```xml
<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
<?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
<?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
<?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
<?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
<?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.

```java
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();
        }
    }
}
```

::: tip מ-Java, עדיף את נקודת הקצה הראשית
הרכבת מעטפות SOAP ידנית היא הרבה טקס עבור הודעה אחת. אותה שליחה דרך [נקודת הקצה `/api`](../endpoints/send.md) היא תריסר שורות של `java.net.http`. הלשונית Java בכל עמוד נקודת קצה מציגה אותה.
:::