HTTPS API v2 / 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 jak i łą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 wielokrotnego odpytywania naszego systemu 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.
messages/reports
Dostępne parametry
| Parametr | Typ | Przykładowa wartość lub format | Opis |
|---|---|---|---|
| username | String | Login | Login użytkownika API. |
| password | String | Haslo | Hasło użytkownika API. |
| phone | String|Array | +48500600700 | Numer lub numery telefonów przesłane w tablicy w pełnym formacie tj. np. +48500600700 (w adresie URL znak „+” to kod „%2B”). |
| date_from oraz date_to | 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. |
| id | String|Array | 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ść ID SMS przesyłając je za pomocą tablicy, wtedy zostaną wyświetlone informacje na temat wszystkich wybranych wiadomości. Maksymalna ilość ID SMS w jednym zapytaniu to 500. |
| status | String | delivered|undelivered|pending|sent|unsent|in_progress|saved | Parametr opcjonalny, filtruje wyświetlane wiadomości wg stanu wysyłki. |
| unique_id | String|Array | 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ść unique_id przesyłając je za pomocą tablicy, wtedy zostaną wyświetlone informacje na temat wszystkich wybranych wiadomości. |
| show_contact | Boolean | true, false lub brak | Wyświetla szczegóły kontaktu, jeśli numer istnieje w bazie odbiorców. |
Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.
Zwrot odpowiedzi
{
"items":[{
"id":"1c7a5432c9",
"phone":"+48600700800",
"status":"delivered",
"queued":"2014-10-20 11:47:23",
"sent":"2014-10-20 11:47:24",
"delivered":"2014-10-20 11:47:57",
"sender":"",
"type":"eco",
"text":"Test SerwerSMS.pl",
"flash":false,
"utf":false,
"parts":1,
"cost":0.6,
"method":"PANEL",
"mnc":26003,
"country":"Polska",
"network":"Orange"
},
{
"id":"8af63d4829",
"phone":"+48600700800",
"status":"sent",
"queued":"2014-10-20 14:31:23",
"sent":"2014-10-20 14:31:23",
"delivered":"2014-10-20 14:32:01",
"sender":"",
"type":"eco",
"text":"Test SerwerSMS.pl",
"flash":false,
"utf":false,
"parts":1,
"cost":0.6,
"method":"PANEL",
"mnc":26003,
"country":"Polska",
"network":"Orange"
},
{
"id":"d7cc8939e9",
"phone":"+48500600700",
"status":"undelivered",
"queued":"2014-10-20 16:54:53",
"sent":"2014-10-20 16:54:56",
"sender":"INFORMACJA",
"type":"full",
"text":"Test SerwerSMS.pl",
"reason":"message_expired",
"flash":false,
"utf":false,
"parts":1,
"cost":0.12,
"method":"PANEL",
"mnc":26003,
"country":"Polska",
"network":"Orange"
},
{
"id":"f3f5a0424e",
"phone":"4888888888888",
"status":"unsent",
"queued":"2014-10-10 14:33:16",
"type":"full",
"reason":"wrong_number",
"text":"Test SerwerSMS.pl"
}]
}
W powyższym przykładzie SerwerSMS.pl zwrócił informacje o czterech wiadomościach z których jedna została doręczona, jedna została wysłana i oczekuje na raport doręczenia, jedna została wysłana, ale nie doręczona i jednej nie udało się wysłać z powodu błędnego numeru odbiorcy.
Objaśnienie parametrów zwrotnych
| Znacznik | Opis |
|---|---|
| id | Zawiera unikalny numer (ID). |
| phone | Zawiera numer odbiorcy w pełnym formacie z numerem kierunkowym kraju na początku. |
| status | Zawiera informacje na temat stanu wysyłki wiadomości. Pole to może przyjmować następujące wartości: „delivered, undelivered, sent, unsent, in_progress, saved”. |
| queued | 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. |
| sent | Data oraz godzina wysłania wiadomości SMS do odbiorcy. |
| delivered | 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ę. |
| reason | Występuje tylko w przypadku nieudanego wysłania i informuje z jakiego powodu wiadomość SMS nie została wysłana. Możliwe wartości: message_expired - nie udało się doręczyć wiadomości SMS w wyznaczonym terminie ważności, wrong_number - błędny numer odbiorcy, unsupported_number - nieobsługiwany numer, message_rejected - wiadomość odrzucona przez operatora, operator_error - błąd po stronie operatora, missed_call - nie odebrane połączenie VMS, limit_exhausted - wyczerpany limit środków na koncie, lock_send - blokada wysyłki, wrong_message - nieprawidłowa treść wiadomości, wrong_sender_name - nieprawidłowa nazwa nadawcy, number_is_blacklisted - numer znajduje się na czarnej liście, sending_to_foreign_networks_is_locked - blokada wysyłki zagranicznych wiadomości, other_error - inny błąd, np. numer jest stacjonarny, nie udało się zidentyfikować kod sieci itp. |
| text | Zawiera treść wiadomości SMS która zostanie wysłana. |
| flash | Informacja o parametrze flash. |
| utf | Informacja o włączonej obsłudze polskich znaków. |
| parts | Liczba części z ilu składa się wiadomość. |
| cost | Koszt wysyłki wiadomości uwzględniający liczbę części w przypadku długich SMS. Nie obowiązuje dla kont Pre-paid z aktywnym pakietem testowym. |
| method | Metoda wysyłki wiadomości. |
| mnc | Kod sieci numeru. |
| country | Kraj operatora. |
| network | Sieć w jakiej znajduje się numer. |
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 przejść w Panelu Klienta do menu Ustawienia Interfejsów → HTTPS XML API → Raporty doręczeń → Wysyłanie raportów pod wskazany adres URL, i 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 (id lub unique_id). Optymalnie jest odpytywać od razu o wiele wiadomości w jednym zapytaniu, np. w paczkach po 50 - 200 identyfikatorów. Maksymalna ilość ID sprawdzana podczas jednego zapytania to 500. W przypadku przesłania większej ilości ID wiadomości, zostaną one pominięte i nie zostaną zwrócone w dokumencie JSON/XML.
Raporty doręczeń dostępne z poziomu HTTPS API sięgają ok. 5-7 dni wstecz. Po tym okresie, przy odpytaniu o wybrany identyfikator wiadomości może zostać zwrócony pusty parametr "items" (JSON), 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 on 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 dotyczący 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.