HTTPS XML API / Wysyłanie wiadomości MMS
Zasada działania
Aby wysłać wiadomość MMS, należy wcześniej wczytać plik multimedialny korzystając z opcji wgrywania plików. Dopiero po wgraniu niezbędnych plików (np. obrazków, dźwięku lub video), możliwe jest wysłanie wiadomości MMS gdzie abonent określa identyfikator pliku do wysyłki.
Wgrywanie pliku
Zapisanie pliku na serwerze polega na przesłaniu adresu URL pliku wraz z odpowiednimi parametrami. System sprawdzi, czy plik istnieje i czy spełnia wymagania, i jeśli weryfikacja przejdzie pomyślnie, dan zostaną zapisane na serwerze a abonent otrzyma dokument XML zawierający identyfikator pliku oraz inne informacje. Wysłanie pliku odbywa się w następujący sposób:
https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=pliki&url_mms=http%3A%2F%2Fwww.serwer.pl%2Fkat%2Fplik.jpg
W rezultacie zostanie wygenerowany dokument XML np. taki jak poniższy:
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<Plik id="734857">
<Nazwa>plik.jpg</Nazwa>
<Rozmiar>34325</Rozmiar>
<Typ>MMS</Typ>
<Data>2011-04-01 12:20:30</Data>
</Plik>
</SerwerSMS>
W przypadku wystąpienia błędu, XML będzie wyglądał np. tak jak poniższy:
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<Blad>komunikat bledu</Blad>
</SerwerSMS>
Możliwe jest wgranie określonych typów plików:
| Content-Type | rozszerzenie pliku |
|---|---|
| image/gif | gif |
| image/jpeg | jpeg |
| image/jpg | jpg |
| image/png | png |
| text/plain | txt |
Listowanie plików
Aby wylistować wgrane na serwer pliki i pobrać ich identyfikatory, które następnie będzie można użyć w wysyłce MMS, należy wywołać poniższe zapytanie:
https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=pliki&lista=mms
W rezultacie zostanie wygenerowany dokument XML np. taki jak poniższy:
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<Plik id="734857">
<Nazwa>plik.jpg</Nazwa>
<Rozmiar>34325</Rozmiar>
<Typ>MMS</Typ>
<Data>2011-04-01 12:20:30</Data>
</Plik>
<Plik id="734858">
<Nazwa>plik1.jpg</Nazwa>
<Rozmiar>34545</Rozmiar>
<Typ>MMS</Typ>
<Data>2011-04-01 12:20:31</Data>
</Plik>
<Plik id="734859">
<Nazwa>plik2.jpg</Nazwa>
<Rozmiar>5463423</Rozmiar>
<Typ>MMS</Typ>
<Data>2011-04-01 12:20:32</Data>
</Plik>
</SerwerSMS>
Wysyłka MMS
Aby przy pomocy Zdalnej obsługi wysłać wiadomość MMS należy wywołać określony adres URL metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco:
https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=wyslij_sms&mms=1&plikmms=231243&wiadomosc=tytul%20MMSa&numer=%2B48500600700
Wywołanie powyższego adresu (w przypadku podania prawidłowych danych do zalogowania) spowodowałoby wysłanie wiadomości SMS o treści „tytul MMSa” z załącznikiem o identyfikatorze 231243 na numer 500600700.
Dostępne parametry
| Parametr | Typ | Przykładowa wartość lub format | Opis |
|---|---|---|---|
| akcja | String | wyslij_sms | Aby wysłać wiadomość SMS należy umieścić tutaj wartość „wyslij_sms”. |
| login | String | login | Login konta używany do wysyłki |
| haslo | String | hasło | Hasło do konta |
| wiadomosc | String | Tytuł wiadomości MMS | Tytuł wiadomości MMS, bez polskich znaków. Dostępne jest 40 znaków. |
| plikmms | String | Identyfikator pliku | Identyfikator pliku można pobrać poprzez wcześniejsze wgranie i wylistowanie dostępnych plików dla usługi MMS. Można jednocześnie wysłać max 10 plików gdzie ich identyfikatory oddzielone są przecinkami. |
| numer | String | +48500600700 | Numer lub numery telefonów oddzielane przecinkami. |
| mms | Integer | 1, 0 lub brak | Ustawienie parametru jako 1 umożliwi wysyłkę MMS. |
| data_wysylki | DateTime | ISO np: „2010-11-09 15:23” |
Parametr opcjonalny pozwalający na określenie terminu wysyłki wiadomości SMS. |
| test | Integer | 1, 0 lub brak | Parametr opcjonalny, pozwalający na sprawdzenie zapytania wysyłającego wiadomość SMS. W odpowiedzi generowany jest dokument XML identyczny jak w przypadku standardowego zapytania jednak wiadomość nie jest wysyłana. |
Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.
Zwrot wygenerowany po przesłaniu jest taki sam jak w przypadku zwykłego wysłania wiadomości SMS.
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<Wiadomosc>Tytul MMSa</Wiadomosc>
<Odbiorcy>
<Skolejkowane>
<SMS id="e1389bc4f6" numer="+48500600700" godzina_skolejkowania="2011-07-10 12:42:45"/>
<SMS id="3ko9iuytdf" numer="+48500600500" godzina_skolejkowania="2011-07-10 12:42:45"/>
</Skolejkowane>
<Niewyslane>
<SMS id="dedb71cd72" numer="6043440" przyczyna="bledny numer odbiorcy"/>
<SMS id="765dk6109s" numer="+420777099123" przyczyna="niedozwolone wysyłanie SMSow do sieci zagranicznych"/>
</Niewyslane>
</Odbiorcy>
</SerwerSMS>
Zalecane ustawienia
W przypadku średnich i dużych ilości wysyłanych wiadomości rzędu kilku tysięcy lub więcej, zalecane jest przekazywanie wiadomości w „paczkach” po ok 50-200 numerów w jednym zapytaniu. Przyspieszy to znacznie proces przekazywania danych do SerwerSMS.pl i zmniejszy ilość koniecznych do wysłania zapytań.
Jeśli wysyłany jest ten sam załącznik, optymalne jest jednorazowe jego wgranie a następnie posługiwanie się jego identyfikatorem przy kolejnych wysyłkach wiadomości.