HTTPS XML API / Sprawdzanie raportów doręczeń wiadomości
SerwerSMS.pl umożliwia sprawdzenie stanu wysłanych wiadomości bez konieczności logowania się do Panelu Klienta. Kontrolę poprawności wysłania oraz stanu przesyłek można sprawdzać na kilka dostępnych sposobów oraz łącząc je ze sobą w dowolny sposób. Dodatkowo w Panelu Klienta można ustawić opcję odpowiedzialną za przesyłanie raportów doręczeń bezpośrednio na adres URL wskazany przez Abonenta. W tej sytuacji nie ma konieczności aby wielokrotnie odpytywać nasz system o stan pojedynczej wiadomości. Zamiast tego nasz system powiadomi Abonenta o tym, że wiadomość została doręczona (lub z jakiegoś powodu nie została doręczona).
Wywołanie adresu
Aby przy pomocy Zdalnej obsługi sprawdzić stan wiadomości 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=sprawdz_sms&data_od=2007-10-10%2012:15:00&data_do=2007-11-01%2012:15:00&numer=%2B48500600700&stan=wyslane&smsid=5kf9g9ts23
Wywołanie powyższego adresu spowoduje wygenerowanie dokumentu XML z informacją na temat wiadomości wysłanej pomiędzy dniem 2007-10-10 12:15:00 i 2007-11-01 12:15:00, na numer +48500600700, o ID 5kf9g9ts23 i dodatkowo stosując filtr pokazujący tylko wiadomości wysłane.
Dostępne parametry
| Parametr | Typ | Przykładowa wartość lub format | Opis |
|---|---|---|---|
| akcja | String | sprawdz_sms | Aby sprawdzić stan wiadomości SMS należy umieścić tutaj wartość „sprawdz_sms”. |
| login | String | Login | Login klienta używany do logowania się w Panelu Klienta |
| haslo | String | Haslo | Hasło klienta używane do logowania się w Panelu Klienta |
| numer | String | +48500600700 | Numer lub numery telefonów oddzielane przecinkami w pełnym formacie tj. np. +48500600700 (w adresie URL znak „+” to kod „%2B”) |
| data_od oraz data_do | DateTime | ISO np. „2007-10-24 17:46:00” |
Przedział czasowy który ma zostać wyświetlony. Jest to data i godzina kolejkowania wiadomości do wysłania lub data przeniesienia wiadomości do niewysłanych w przypadku wystąpienia błędu |
| smsid | String | np. Jdut76dn23 (litery oraz cyfry) | Parametr ten określa ID wiadomości który zostaje nadany przez system podczas wysyłki zdalnej. Można jednocześnie załączyć większą ilość smsid oddzielając je przecinkami, wtedy zostaną wyświetlone informacje na temat wszystkich wybranych wiadomości. Maksymalna ilość SMSID w jednym zapytaniu to 500. |
| stan | String | wyslane, doreczone, niedoreczone, niewyslane, oczekiwanie, w trakcie wysylki, zaplanowane | Parametr opcjonalny, filtruje wyświetlane wiadomości wg. stanu wysyłki |
| usmsid | String | np. abc123 (litery oraz cyfry) | Parametr ten określa ID wiadomości który zostaje nadany podczas wysyłki zdalnej przez Klienta. Można jednocześnie załączyć większą ilość usmsid oddzielając je przecinkami, wtedy zostaną wyświetlone informacje na temat wszystkich wybranych wiadomości |
| szczegoly | Boolean | true, false lub brak parametru | Zwraca dodatkowe atrybuty dla wiadomości takie jak: koszt (opłata pobrana za wysłanie wiadomości), sposób wysyłki (API, PANEL itp), mnc (Mobile Network Code, np. 26001 dla sieci Plus), kraj, sieć (nazwa sieci np. Plus). Dodatkowo dla wiadomości VOICE zwracane są dodatkowe atrybuty "length" mówiący o długości trwania połączenia (w sekundach) oraz "try" opisujący ilość prób połączeń. |
Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.
Zwrot odpowiedzi
Wynik wywołania powyższego adresu może wyglądać następująco:
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<SMS id="d7e9cfb937" numer="+48500600700" tresc="Test SerwerSMS.pl" stan="Doreczono" godzina_skolejkowania="2007-10-30 15:03:31" godzina_wyslania="2007-10-30 15:03:35" godzina_doreczenia="2007-10-30 15:03:39"/>
<SMS id="06fcafceb1" numer="+48500600700" tresc="Test Serwera SMS" stan="W trakcie wysylki" godzina_skolejkowania="2007-10-31 13:04:20"/>
<SMS id="5ughqbvc22" numer="+48000693444" tresc="Wiadomosc z blednym numerem" stan="Niewyslano" godzina_skolejkowania="2007-09-21 10:20:14" przyczyna="Nie ma takiego numeru lub bledna odpowiedz sieci"/>
<SMS id="d9sf8jckj" numer="+48500693440" tresc="tresc informacji" stan="Niedoreczono" godzina_skolejkowania="2007-09-29 10:21:00" godzina_wyslania="2007-09-29 10:21:02" godzina_niedoreczenia="2007-09-30 12:00:20"/>
</SerwerSMS>
W powyższym przykładzie SerwerSMS.pl zwrócił informacje o czterech wiadomościach z których jedna została wysłana, jedna oczekuje na wysłanie, jednej nie udało się wysłać z powodu błędnego numeru odbiorcy a jedna została wysłana ale nie została doręczona.
Objaśnienie poszczególnych sekcji XML
| Znacznik XML | Opis |
|---|---|
| <SMS id="ID" … | Zawiera wszystkie informacje na temat danej wiadomości SMS oraz unikalny numer (ID) |
| numer="NUM" | Zawiera numer odbiorcy w pełnym formacie z numerem kierunkowym kraju na początku |
| tresc="TRESC" | Zawiera poprawnie skolejkowane wiadomości SMS które zostaną wysłane w najbliższym czasie |
| stan="STAN" | Zawiera informacje na temat stanu wysyłki wiadomości. Pole to może przyjmować następujące wartości: „Doreczono, Niedoreczono, Niewyslano, Oczekiwanie, W trakcie wysylki, Zaplanowano” |
| godzina_skolejkowania="GODZ" | Data oraz godzina przyjęcia wiadomości SMS do systemu (data wywołania). W przypadku gdy wysyłka SMS została zaplanowana na określony termin, widnieje tutaj godzina kiedy SMS zostanie wysłany. |
| godzina_wyslania="GODZ" | Data oraz godzina wysłania wiadomości SMS do odbiorcy |
| godzina_doreczenia="GODZ" | Data oraz godzina doręczenia wiadomości do odbiorcy. Informacja ta wyświetla się w przypadku gdy wiadomość posiada status oczekujący bądź została doręczona. Jeśli wiadomość nie zostanie doręczona, informacja ta nie pojawi się. |
| przyczyna="POWOD" | Występuje tylko w przypadku nieudanego wysłania i informuje z jakiego powodu wiadomość SMS nie została wysłana |
| godzina_niedoreczenia="GODZ" | Data ostatniej zmiany statusu wiadomości w przypadku gdy wiadomość nie została doręczona do adresata. Wyświetlona zostanie jedynie w sytuacji gdy wiadomość nie została doręczona w określonym czasie do adresata. |
Określanie adresu URL Abonenta na który mają być wysyłane raporty doręczeń
Odpowiednie opcje dostępne są w Panelu Klienta i wymagają jednorazowej konfiguracji. Aby informacje na temat były przesyłane do Abonenta należy zaznaczyć ustawienia jak na poniższym obrazku oraz podać swój własny adres URL w którym znajdą się takie parametry jak #STAN#, #DATA#, #PRZYCZYNA# oraz #RAPORT#.
Przed wysłaniem informacji do klienta, parametry te są podmieniane z danymi dotyczącymi określonej wiadomości SMS. System sprawdza, czy w odpowiedzi strona klienta zwraca odpowiedź o treści „OK”. Jeśli system nie wykryje takiej odpowiedzi, wysłanie raportu zostanie ponowione po 5, 15, 60 minutach a następnie po 24 godzinach. Jeśli wciąż strona klienta nie zwróci odpowiedzi o treści „OK”, SerwerSMS.pl przestanie wysyłać informację dotyczącą raportu doręczenia. Informacje o raportach doręczeń przesyłane są metodą GET.
Przesyłane parametry w adresie URL
| Parametr | Przykładowa wartość lub format | Opis |
|---|---|---|
| #STAN# | Doreczono, Niedoreczono, Niewyslano, Oczekiwanie | Wartość ta określa czy przekazana do wysyłki wiadomość została wysłana, a jeśli tak to czy została doręczona. |
| #DATA# | Np: 2009-10-21 14:23:28 | Data zmiany statusu wiadomości, gdy została doręczona, wrócił raport niedoręczenia lub gdy wiadomość została przekazana do niewysłanych. |
| #SMSID# | Np. 8dfa7tvc44s | Ciąg alfanumeryczny jednoznacznie określający pojedynczą wiadomość |
| #PRZYCZYNA# | Tekstowy opis z przyczyną wystąpienia błędu np. „Błędny numer nadawcy” | W parametrze tym przekazywana jest bardziej szczegółowa informacja na temat niedoręczenia lub niewysłania wiadomości. Jest ona wypełniona jedynie w przypadku gdy wiadomość została niedoręczona lub niewysłana. |
Zalecane ustawienia
Zalecane jest, aby raporty doręczenia wysyłanych wiadomości były przekazywane na zdefiniowany w Panelu Klienta adres URL. Przyczynia się to do zauważalnego zmniejszenia ruchu i obsługi wielu niepotrzebnych, powtarzalnych zapytań.
Jeśli nie ma takiej możliwości, najlepszą metodą sprawdzania raportów jest odpytywanie o konkretne identyfikatory wiadomości (smsid lub usmsid). Optymalnie jest odpytywać od razu o wiele wiadomości w jednym zapytaniu, np. w paczkach po 50 - 200 identyfikatorów. Maksymalna ilość SMSID sprawdzana podczas jednego zapytania to 500. W przypadku przesłania większej ilości SMSID, zostaną one pominięte i nie zostaną zwrócone w dokumencie XML.
Raporty doręczeń dostępne z poziomu HTTPS XML API sięgają ok 14 dni wstecz. Po tym okresie, przy odpytaniu o wybrany identyfikator wiadomości może zostać zwrócony pusty tag XML, bez informacji na temat wiadomości. Jest to sygnał, że wiadomość została już zarchiwizowana (jest dostępna z poziomu Panelu Klienta przez ok 12 miesięcy).
Raporty doręczeń są też aktualizowane w pierwszych ok 72 godzinach. Jeśli raport doręczenia nie zostanie zaktualizowany do tego czasu, nie zostanie już zaktualizowany (czasami zdarza się taka sytuacja gdy nie otrzymamy zwrotnego raportu od Operatora GSM). W takiej sytuacji należy pominąć dalsze sprawdzanie statusu wiadomości.
Zbyt częste odpytywanie o raporty doręczeń może spowodować reakcję ze strony administratorów SerwerSMS.pl. W takiej sytuacji, wysyłany jest monit dot. zalecanych optymalizacji. Jeśli nie będzie reakcji ze strony Klienta lub odpytania API nadal nie będą optymalne, SerwerSMS.pl może tymczasowo zablokować możliwość sprawdzania raportów do wyjaśnienia.