HTTPS XML API / Wysyłanie wiadomości SMS o jednakowej treści
Wywołanie adresu
Aby przy pomocy Zdalnej obsługi wysłać wiadomość SMS należy przesłać określone zgłoszenie protokołem HTTP lub HTTPS 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&numer=%2B48500600700&wiadomosc=Test%20SerwerSMS.pl
W przypadku zastosowania metody POST w formularzu, nazwy zmiennych i ich wartości pozostają bez zmian, zmienia się tylko i wyłącznie metoda przesłania zapytania. Wywołanie powyższego adresu (w przypadku podania prawidłowych danych do zalogowania) spowodowałoby wysłanie wiadomości SMS na numer 500600700 o treści „Test SerwerSMS.pl”.
UWAGA, aby wysłać wiadomość SMS FULL należy wypełnić pole nadawca (nazwa alfanumeryczna lub numer). Jeśli parametr nadawca zostanie pominięty, lub jego wartość będzie pusta, zostanie wysłany SMS typu ECO. Wypełnienie parametru nadawca decyduje o tym czy wysłany zostanie SMS ECO+ czy FULL.
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żywanego do wysyłki |
| haslo | String | haslo | Hasło do konta |
| numer | String | +48500600700 | Numer lub numery telefonów oddzielane przecinkami. |
| wiadomosc | String | tresc | Treść wiadomości |
| flash | Integer | 1, 0 lub brak | Parametr opcjonalny. |
| 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. Przydatne do testowania aplikacji. |
| nadawca | String | Alfanumeryczna nazwa nadawcy np. „INFORMACJA”, własna nazwa, "2waySMS" lub numer 4 lub 9-cio cyfrowy. | Parametr opcjonalny, umożliwia zmianę pola nadawcy wiadomości SMS na niemal dowolną nazwę lub numer. Każda nazwa nadawcy musi zostać najpierw dodana w Panelu lub przez API a następnie zatwierdzona przez administratora SerwerSMS.pl. Ustawienie nazwy na wartość "2waySMS" spowoduje podmianę nagłówka na losowy numer 9-cio cyfrowy, na który można odesłać odpowiedź zwrotną. |
| wap_push | String | Adres URL lub brak | Parametr opcjonalny. |
| kodowanie | String | UTF-8 lub brak | Parametr opcjonalny, umożliwia wysłanie wiadomości FULL SMS zawierającej np. polskie znaki diakrytyczye, cyrlicę itp. Opcja dostępna wyłącznie w SMS FULL. Przy użyciu tej opcji zmienia się maksymalna długość pojedynczej wiadomości SMS z 160 do 70 znaków. |
| glosowy | Integer | 1, 0 lub brak | Parametr opcjonalny, umożliwia wysłanie wiadomości SMS VOICE. W przypadku wiadomości głosowej maksymalna długość wiadomości to 160 znaków. Parametr nadawca musi pozostać pusty. |
| vcard | Integer | 1, 0 lub brak | Parametr opcjonalny, umożliwiający wysłanie wiadomości VCARD. |
| speed | Integer | 1, 0 lub brak | Parametr opcjonalny, pozwalający na wysłanie wiadomości niezależnym kanałem o najwyższej jakości (dodatkowa opłata) |
| data_wysylki | DateTime | ISO np. „2012-02-22 12:25:55” |
Parametr opcjonalny pozwalający na określenie terminu wysyłki wiadomości. |
| usmsid | String | np. 6asTD3fif98gj | Parametr opcjonalny pozwalający na zdefiniowanie własnego identyfikatora wysyłanej wiadomości. Identyfikator może mieć minimalnie 3 znaki i maksymalnie 50 znaków alfanumerycznych (a-z, A-Z, 0-9). Dla grupowych wysyłek, kolejne usmsid muszą być unikalne, podane po przecinku oraz ilość usmsid musi być zgodna z ilością numerów. |
| grupy | String | np. 123456789,456123789 | Identyfikator lub identyfikatory grup w Panelu Klienta oddzielane przecinkami. Identyfikatory te można pobrać korzystając z akcji lista_grup lub kopiując je z poziomu edycji grupy w Panelu Klienta. |
| lektor | String | Maja, Jacek, Ewa, Jan lub pusta wartość (domyślny lektor Maja) | Dotyczy wiadomości głosowej z treścią w formie tekstu odczytywanego przez syntezator. Domyślny lektor to Maja. |
| dlr_url | String |
http://www.twojadres.pl/skrypt.php?smsid=#SMSID#&stan=#STAN#&data=#DATA# |
Parametr pozwala na przekazywanie metodą Push raportów doręczenia na URL Klienta. Ustawienie tej opcji w zapytaniu API nadpisuje ew. ustawienia w Panelu Klienta. W przypadku metody GET adres powinien być przekazany w formie zakodowanej przez urlencode(). Adres do przekazania raportów obowiązuje dla wszystkich wiadomości przekazanych do realizacji w ramach jednego zapytania. Jeśli w adresie URL zastosowano port inny niż 80 lub 443, prosimy o kontakt celem aktualizacji ustawień systemu. Dostępne parametry: #SMSID# - identyfikator wiadomości |
| waznosc | Integer | np. 1440 (1440 minut to 24 godziny) | Czas ważności wiadomości SMS wyrażony w minutach w trakcie którego będa podejmowane próby dostarczenia wiadomości do odbiorcy. Po tym czasie wiadomość otrzyma status Niedoręczono. W przypadku braku ustawienia parametru, wartość zostanie pobrana z ustawień konta głównego z preferencji. Domyślnie 24 godziny. Minimalna zalecana wartość to 2, maksymalna 4320 (72 godziny). Opcja działa dla SMS FULL. |
Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.
W przypadku chęci wysłania wiadomości jako wizytówka Vcard (parametr „vcard=1”), struktura wiadomości musi mieć ściśle określony format. Przykład formatu Vcard można znaleźć w ogólnie dostępnej dokumentacji w internecie lub korzystając z Panelu Klienta i formularza wysyłki SMS. Kolejne tagi w wiadomości Vcard powinny być rozdzielone znakiem nowej linii.
Wiadomość FULL SMS która zawiera polskie znaki specjalne powinna być przed wysłaniem odpowiednio zakodowana w UTF-8. Aby wysłać wiadomość z polskimi znakami musi być ustawiony parametr „kodowanie=UTF-8”, abonent musi posiadać uprawnienia do wysyłania wiadomości typu FULL SMS oraz musi być wypełnione pole nadawcy (to oznacza iż wysłany będzie SMS FULL).
Zwrot odpowiedzi
W zależności od przesłanych danych SerwerSMS.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanych akcji. I tak w przypadku prawidłowego wysłania wiadomości SMS klient otrzyma przykładowo następują informację:
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<Wiadomosc>Test SerwerSMS.pl</Wiadomosc>
<Odbiorcy>
<Skolejkowane>
<SMS id="1c142d81c7" numer="+48500600700" godzina_skolejkowania="2008-07-10 12:42:45"/>
</Skolejkowane>
</Odbiorcy>
</SerwerSMS>
W sekcji <Wiadomosc></Wiadomosc> widnieje treść wysyłanej wiadomości SMS. Sekcja <Odbiorcy></Odbiorcy> zawiera numery telefonów i ID wiadomości przekazanych do wysłania (oraz wiadomości których nie skolejkowano z określonego powodu). Sekcja <SMS></SMS> zawiera numer telefonu oraz ID wiadomości. Unikalny znacznik wiadomości SMS może być wykorzystany później do sprawdzenia w sposób zdalny stanu wysyłki konkretnej wiadomości SMS. Numer telefonu jest automatycznie poprawiany i wyświetlany w pełnym formacie wymaganym przez SerwerSMS.pl czyli z numerem kierunkowym kraju (np. +48) na początku.
W przypadku podania np. złego numeru telefonu zostanie wygenerowana informacja o błędzie jak również ID wiadomości (aby można było później sprawdzić kiedy i dlaczego nie została wysłana). I tak np. w przypadku podania dwóch numerów prawidłowych i dwóch numerów błędnych system wygeneruje następujący dokument XML:
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<Wiadomosc>Test Serwera SMS</Wiadomosc>
<Odbiorcy>
<Skolejkowane>
<SMS id="e1389bc4f6" numer="+48500600700" godzina_skolejkowania="2008-07-10 12:42:45"/>
<SMS id="3ko9iuytdf" numer="+48500600500" godzina_skolejkowania="2008-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>
Objaśnienie poszczególnych sekcji XML
| Znacznik XML | Opis |
|---|---|
| <Wiadomosc></Wiadomosc> | Zawiera treść wysyłanej wiadomości |
| <Odbiorcy></Odbiorcy> | Jest to część gdzie wyszczególnione są wszystkie wysłane oraz niewysłane wiadomości SMS |
| <Skolejkowane></Skolejkowane> | Zawiera poprawnie skolejkowane wiadomości SMS które zostaną wysłane w najbliższym czasie |
| <SMS numer="NUM” id=”ID” godzina_skolejkowania=”DAT”/> | W sekcji prawidłowo kolejkowanych wiadomości SMS wpisy takie określają numer telefonu (NUM), ID wiadomości (ID) oraz godziny kolejkowania (DAT). |
| <Niewyslane></Niewyslane> | Zawiera informacje o błędach w próbie kolejkowania wiadomości SMS |
| <SMS numer="NUM" id="ID" przyczyna="POWOD"/> | W sekcji <Niewyslane> określa numer telefonu (NUM) na który nie udało się wysłać wiadomości SMS, ID tej wiadomości oraz powód niewysłania |
Oprócz tego może zostać wygenerowany błąd ogólny gdzie nie ma rozgraniczenia na skolejkowane i błędne. Może to nastąpić np. w sytuacji gdy klient nie zdefiniuje treści wiadomości, nie poda numerów telefonów, jego konto nie jest aktywne lub wystąpił inny problem opisany w komunikatach błędów. W przypadku niewpisania treści wiadomości zostanie wygenerowany następujący komunikat:
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<Blad>Wiadomosc jest pusta</Blad>
</SerwerSMS>
Oraz analogicznie w przypadku niepodania numerów telefonów:
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<Blad>Nie podano numerow telefonow</Blad>
</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ń.
W przypadku próby wysyłki wiadomości na dwa lub więcej takie same numery telefonów w jednym zapytaniu, system wyśle wiadomość tylko raz na ten numer.
Zalecana wartość timeout-u dla pojedynczego zapytania wynosi 30-60 sekund.