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.