HTTPS XML API / Obsługa wiadomości Premium SMS

Zasada działania

Przy użyciu HTTPS XML API można obsługiwać również ruch Premium SMS, tworząc np. własne schematy konkursów, loterii czy czaty SMS (np. w przypadku gdy funkcjonalność Panelu Klienta nie jest wystarczająca dla Abonenta). Komunikacja Premium SMS przy użyciu HTTPS XML API polega na odebraniu zapytania z nową wiadomością lub ew. wylistowanie dostępnych wiadomości Premium oraz przesłanie zapytania dot. wysyłki odpowiedzi.

URL przesyłający informację o nowej wiadomości Premium

W Panelu Klienta można ustawić adres URL z odpowiednimi parametrami, na jaki wysyłane mają być informacje dot. nowych wiadomości Premium. Ustawienia te można zaktualizować w Panelu Klienta → Premium SMS → Prefixy i numery → Edycja wybranego hasła (lub stworzenie nowego) → Treść odpowiedzi → HTTPS XML API. 

Przykładowy URL może mieć postać:

https://www.adres.pl/skrypt.php?z_numeru=#NUMEROD#&wiadomosc=#WIADOMOSC#&na_numer=#NUMERDO#&data=#DATA#&idsms=#IDSMS#&limit=#LIMIT#

Opis parametrów:

Parametr Przykładowa wartość lub format Opis
#NUMEROD# 48500600700 Numer 9-cio cyfrowy z jakiego przyszła wiadomość Premium
#WIADOMOSC# test Treść wiadomości
#NUMERDO# 71200 Numer Premium na jaki została wysłana wiadomość
#DATA# „2011-09-26 12:23:56” Data w formacie YYY-MM-DD HH:ii:ss
#IDSMS# 1234 Identyfikator numeryczny wiadomości.
#LIMIT# 2 Liczba przysługujących odpowiedzi dla wybranej wiadomości.

Poprawna odpowiedź na zapytanie powinna być zwrócona jako plain/text i zawierać jedynie „OK”.

Listowanie wiadomości Premium

Jeśli z jakiegoś powodu odbiór wiadomości się nie powiedzie, lub klient preferuje ręcznie pobierać listę dostępnych wiadomości w ramach Premium API, istnieje możliwość przesłania zapytania do systemu które zwróci listę wiadomości oczekujących na odpowiedź. Przykładowe zapytanie znajduje się poniżej.

https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=premium_api&operacja=lista

W rezultacie zostanie wygenerowany dokument XML np. taki jak poniższy:

<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
 <SMS id="21544" na_numer="71160" z_numeru="48500600700" data="2011-09-14 14:44:55" limit="1">INT.test</SMS>
 <SMS id="21546" na_numer="71160" z_numeru="48600700800" data="2011-09-14 15:52:02" limit="2">PAS.premium</SMS>
</SerwerSMS>

Wysyłanie odpowiedzi Premium

Aby wysłać odpowiedź na określoną wiadomość Premium należy użyć jej identyfikatora. Zapytanie powinno wyglądać tak:

https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=premium_api&operacja=wyslij_sms&idsms=21544&numer=48500600700&bramka=71160&wiadomosc=odpowiedz%20PremiumSMS

W rezultacie zostanie wygenerowany dokument XML np. taki jak poniższy:

<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
 <SMS id="21544">OK</SMS>
</SerwerSMS>

Lub w przypadku wystąpienia błędu:

<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
 <Blad>komunikat bledu</Blad>
</SerwerSMS>

Listowanie statystyk dla usługi Quiz Premium

Aby wyświetlić statystyki należy podać identyfikator quizu. Przykładowy adres URL:

http://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=quiz&quiz=123

W rezultacie zostanie wygenerowany dokument XML np. taki jak poniższy:

<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
 <quiz id="123" nazwa="jakas nazwa quizu">
  <pozycja id="1">8</pozycja>
  <pozycja id="2">10</pozycja>
 </quiz>
</SerwerSMS>

Tabela dostępnych ilości odpowiedzi w zależności od numeru Premium

Stawka Przykładowy numer Ilość odpowiedzi
0,50 zł 70906 1
1,00 zł 7100 2
2,00 zł 7200 4
3,00 zł 7300 6
4,00 zł 7400 8
5,00 zł 7500 10
6,00 zł 7600 12
9,00 zł 7900 18
19,00 zł 91900 38
25,00 zł 92500 38

Dla każdej wiadomości przychodzącej w ramach numeru Premium, przysługuje pula wiadomości wychodzących (również przez kanał Premium), z użyciem tego samego numeru na jaki SMS został pierwotnie wysłany. Poniższa tabela ilustruje ilości dostępnych odpowiedzi w ramach 1 wiadomości przychodzącej uzależnionej od taryfy numeru Premium.

Zalecane ustawienia

Aby obsługiwać usługę Premium SMS przez API, należy w ustawieniach haseł Premium oznaczyć opcję odpowiedzi na API. Dodatkowo, w celu informacyjnym, warto zaznaczyć opcję przesyłania dalej wiadomości na adres URL, w ten sposób Klient może być informowany o nowej wiadomości przychodzącej bez konieczności cyklicznego odpytywania API SerwerSMS.pl o nowe wiadomości.