Dokumentacja interfejsu SMS HTTP API. Wersja 3.0 [15 styczeń 2008]

Transkrypt

1 tel.: fax.: Bramka SMS: Obsługiwanych ponad 600 sieci w ponad 200 krajach Świata SMSy z własnym polem nadawcy Raporty doręczeń Obsługa długich wiadomości SMS Dokumentacja interfejsu SMS HTTP API Wersja 3.0 [15 styczeń 2008]

2 SPIS TREŚCI: 1. Historia zmian w dokumentacji Wprowadzenie Krok 1 - Rejestracja konta w GSMService.pl Krok 2 Aktywacja subkonta API Podstawowe funkcje dostępne w API Wysyłanie wiadomości SMS Status wysłanych SMSów Sprawdzanie stanu konta Sprawdzenie kosztu SMS a Definiowanie zawartości Pola Nadawcy Kody statusów API Dodatkowe informacje i kontakt... 9 SPIS TABEL: Tab. 1. Objaśnienie parametrów modułu do wysyłania wiadomości SMS... 4 Tab. 2. Objaśnienie parametrów modułu do odczytu statusów wysłanych SMSów... 6 Tab. 3. Objaśnienie parametrów modułu do sprawdzania stanu konta Tab. 4. Objaśnienie parametrów modułu do sprawdzenia kosztu wysyłki wiadomości... 7 Tab. 5. Objaśnienie kodów zwracanych statusów... 8 Copyright 2008 INTERMEDIA Strona 2

3 1. Historia zmian w dokumentacji. Wersja Data Wprowadzone zmiany Dostosowano dokumentację interfejsu API do nowej platformy bramki SMS, dodano moŝliwość wysyłania SMSów ze zdefiniowanym czasem doręczenia wiadomości. Dodano kilka nowych statusów wiadomości SMS, dodano parametr showid. 2. Wprowadzenie Dokument ten powstał w celu umoŝliwienia integracji Bramki SMS GSMService.pl z dowolną aplikacją lub systemem. Na obecnej platformie GSMService.pl istnieje kilka róŝnych moŝliwości wysyłania wiadomości SMS: Bezpośrednio ze strony Za pomocą programu SzybkiSMS [ Za pośrednictwem interfejsu API W niniejszym dokumencie przedstawiono moŝliwości, jakie niesie za sobą wykorzystanie interfejsu API. W chwili obecnej poprzez API moŝliwa jest wysyłka wiadomości SMS oraz Flash SMS. W niedalekiej przyszłości umoŝliwimy wysyłanie poprzez API wiadomości faksowych. Wysłanie wiadomości SMS, sprawdzenie jej statusu czy stanu konta poprzez API polega na wywołaniu odpowiedniego adresu WWW z jednoczesnym przekazaniem do niego pewnych parametrów. y mogą zostać przekazane za pośrednictwem metody HTTP POST lub HTTP GET. JednakŜe ze względów wydajnościowych oraz pewnych ograniczeń metody GET zalecamy wykorzystanie do tego celu metody HTTP POST. Komunikacja z API moŝe odbywać się zarówno na porcie 80 (w przypadku nieszyfrowanych połączeń) lub na porcie 443 (z szyfrowaniem SSL). Wszystkie wartości przekazywanych parametrów powinny zostać potraktowane uprzednio funkcją urlencode (w przypadku PHP), lub jej odpowiednikiem dla danego języka programowania. Bardzo prosimy dokładnie zapoznać się z niniejszą dokumentacją przed rozpoczęciem integracji. Ułatwi to cały proces oraz pozwoli uniknąć wielu problemów. Aby rozpocząć integrację dowolnej aplikacji z Bramką SMS konieczne jest posiadanie konta w serwisie GSMService.pl i aktywacja dostępu do konta API (zwanego w dalszej części tej dokumentacji subkontem API). PoniŜej prezentujemy rok po kroku jak aktywować dostęp do interfejsu API Krok 1 - Rejestracja konta w GSMService.pl JeŜeli nie posiadasz jeszcze konta w GSMService.pl naleŝy je załoŝyć. W przeciwnym wypadku przejdź do kroku 2. Aby zarejestrować nowe konto w GSMService.pl naleŝy: Wejść na stronę Wypełnić formularz rejestracyjny. Po pomyślnej rejestracji zostaniesz automatycznie zalogowany i poproszony o akceptację Regulaminu Bramki SMS. Będziesz mógł równieŝ wówczas wprowadzić dane do Faktur VAT, jeŝeli chcesz je otrzymywać po kaŝdym zasileniu konta. Copyright 2008 INTERMEDIA Strona 3

4 2.2. Krok 2 Aktywacja subkonta API Po zalogowaniu się na naleŝy: Wybrać z lewego MENU, z sekcji INTEGRACJA (API) opcję Aktywacja kont API, Wypełnić formularz podając dowolny login oraz hasło dla subkonta API (wpisywany login i hasło posłuŝą do autentykacji uŝytkownika przy wywoływaniu wszystkich funkcji API, dlatego teŝ prosimy o staranne dobranie i bezpieczne przechowywanie loginu oraz hasła, aby nikt niepowołany nie uzyskał dostępu do Państwa konta API). Po pomyślnym wysłaniu formularza subkonto API zostanie załoŝone i aktywowane. UWAGA! Obecnie pierwsze subkonto API aktywowane jest bezpłatnie. Za kaŝde kolejne subkonto pobieramy jednorazową opłatę w wysokości 10 zł brutto. Posiadając aktywne konto API moŝna rozpocząć proces integracji. Aby wysyłać wiadomości SMS, konieczne jest zasilenie konta wybranym pakietem punktów. Zestawienie dostępnych pakietów znaleźć moŝna na stronie W celu zasilenia konta, będąc zalogowanym do Bramki SMS, naleŝy wybrać opcję Doładuj konto z lewego MENU, a następnie postępować zgodnie ze wskazówkami. 3. Podstawowe funkcje dostępne w API Wydanie polecenia (w tym wysłanie wiadomości SMS) polega na wywołaniu odpowiednio przygotowanego adresu URL. Adres składa się ze ścieŝki do skryptu oraz z parametrów przekazywanych do niego metodą POST lub GET Wysyłanie wiadomości SMS W celu wysłania wiadomości SMS poprzez interfejs API naleŝy wywołać następujący adres URL z parametrami w postaci: xxxx&rodzaj=x&podpis=x&showid=1 gdzie xxx to odpowiednie wartości parametrów. y moŝna przekazywać zarówno metodą POST, jak i GET. Zostały one objaśnione w Tab. 1. Tab. 1. Objaśnienie parametrów modułu do wysyłania wiadomości SMS. login pass Login subkonta API w Bramce SMS [zdefiniowany w czasie aktywacji API] Hasło do subkonta API w Bramce SMS [zdefiniowane w czasie aktywacji API] Copyright 2008 INTERMEDIA Strona 4

5 numer tekst rodzaj podpis deliv_time showid Numer telefonu odbiorcy, pod który SMS ma zostać wysłany. UWAGA!!! Koniecznie w postaci międzynarodowej z kodem kraju na początku (bez znaku +) np Treść SMSa, która ma zostać wysłana - powinna zostać odpowiednio zakodowana np. funkcją urlencode (w PHP). Maksymalna długość pojedynczego SMSa 160 znaków. Maksymalna długość łączonego SMSa: 306 znaków. Uwaga! Niektóre znaki liczone są podwójnie, np. znaki: [ ] ~ ^ { } \. Treść powinna być zgodna z kodowaniem ISO Rodzaj wysyłanego SMSa: 1 SMS tradycyjny (wysyłany z własnym polem nadawcy) 2 Flash SMS (wysyłany z własnym polem nadawcy) Podpis 1, który znajdzie się w polu nadawcy zamiast numeru nadawcy. JeŜeli pominięto ten parametr, SMS zostanie wysłany z polem nadawcy Bramka SMS. UWAGA prosimy przeczytać przypis na końcu tej strony!!! zawiera czas (wyraŝony w minutach od chwili wywołania funkcji wysyłającej), kiedy wiadomość ma zostać doręczona do odbiorcy. Wiadomość zostanie doręczona o zdefiniowanej porze (+ - 5 minut). Maksymalna wartość: 0 Nie zostanie zwrócony identyfikator wiadomości 1 Zostanie równieŝ zwrócony identyfikator wysłanej wiadomości (szczegóły poniŝej) Mając identyfikator wiadomości moŝliwe jest sprawdzenie aktualnego statusu wysłanej wiadomości. Więcej w rozdziale 3.2 Status wysłanych SMSów. Po wywołaniu adresu z prawidłowo przekazanymi parametrami, w treści wyświetlonej strony otrzymamy kod statusu SMSa w formie: a) Gdy parametr showid=0: Status:XXX b) Gdy parametr showid=1: Status:XXX SMSID gdzie XXX oznacza odpowiedni kod trzycyfrowy statusu, natomiast SMSID to identyfikator wysłanej wiadomości. Objaśnienie poszczególnych kodów statusu przedstawia Tab Status wysłanych SMSów Istnieje moŝliwość sprawdzenia aktualnego statusu wysyłanych wiadomości SMS. Statusy SMSów zmieniają się np. w momencie doręczenia wiadomości do odbiorcy, itp. W celu sprawdzenia aktualnego statusu wiadomości naleŝy wywołać adres w następującej formie (parametry moŝna przekazać metodą POST lub GET): gdzie xxx to odpowiednie wartości parametrów, które zostały objaśnione w Tab KaŜda zawartość pola nadawcy musi zostać uprzednio zweryfikowana. Oznacza to, Ŝe konieczne jest uprzednie zdefiniowanie wszystkich wyraŝeń, numerów itd. wykorzystywanych w polu nadawcy. KaŜdy uŝytkownik moŝe bezpłatnie zdefiniować nieograniczoną ilość pól nadawcy. Uprzednie zdefiniowanie zawartości oraz weryfikacja ma na celu ograniczenie potencjalnych naduŝyć i podnieść bezpieczeństwo wszystkich uŝytkowników bramki. Opis, w jaki sposób zdefiniować zawartość pola nadawcy oraz pozostałe informacje znajdują się w Rozdziale 4. niniejszej dokumentacji. Copyright 2008 INTERMEDIA Strona 5

6 Tab. 2. Objaśnienie parametrów modułu do odczytu statusów wysłanych SMSów. login pass smsid ilosc Login subkonta API w Bramce SMS [zdefiniowany w czasie aktywacji API] Hasło do subkonta API w Bramce SMS [zdefiniowane w czasie aktywacji API] Identyfikator wiadomości otrzymany po wysyłaniu wiadomości parametr opcjonalny. Liczba ostatnio wysłanych wiadomości SMS, których aktualne statusy mają zostać zwrócone (zakres 1-300) parametr opcjonalny. JeŜeli podany jest parametr smsid to parametr ilosc jest pomijany. UWAGA! y smsid oraz ilosc są opcjonalne, lecz wymagana jest obecność jednego z nich. Po wywołaniu odpowiednio spreparowanego adresu w treści wyświetlonej strony otrzymamy wyniki w wierszach o następującej postaci: smsid nr_docelowy data godzina status rodzaj koszt gdzie: smsid identyfikator SMSa w naszym systemie nr_docelowy numer telefonu odbiorcy SMSa data i godzina data i godzina ostatniej zmiany statusu SMSa status aktualny kod statusu SMSa w formie trzycyfrowej zgodnie z Tab. 5 rodzaj rodzaj SMSa (1 SMS tradycyjny, 2 Flash SMS, 3 SMS ekonomiczny, 4 Logo czarno-białe, 5 Tapeta, 6 Logo kolorowe, 7 wiadomość FAKS, 99 SMS aktywacyjny) koszt koszt wysyłki danego SMSa (wyraŝony w punktach) KaŜdy z wierszy zawiera informację o dokładnie jednej wiadomości SMS Sprawdzanie stanu konta Aby sprawdzić aktualny stan konta w Bramce SMS za pośrednictwem interfejsu API naleŝy wywołać adres o następującej składni: gdzie xxx to odpowiednie wartości parametrów. Znaczenie kaŝdego parametru przedstawia Tab. 3. Tab. 3. Objaśnienie parametrów modułu do sprawdzania stanu konta. login pass Login subkonta API w Bramce SMS [zdefiniowany w czasie aktywacji API] Hasło do subkonta API w Bramce SMS [zdefiniowane w czasie aktywacji API] Po wywołaniu prawidłowego adresu z przekazanymi parametrami, w treści wyświetlonej strony otrzymamy aktualny stan punktów na koncie w postaci: Stan:XXX gdzie XXX oznacza dostępną ilość punktów. Copyright 2008 INTERMEDIA Strona 6

7 3.4. Sprawdzenie kosztu SMS a Koszt wiadomości uzaleŝniony jest od docelowej sieci GSM i moŝe być okresowo zmieniany przez poszczególnych operatorów GSM. Aby sprawdzić aktualny koszt wiadomości SMS, wysyłanej pod konkretny numer, naleŝy wywołać adres o następującej postaci: gdzie xxx to odpowiednie wartości parametrów. y moŝna przekazać za pomocą metody POST lub GET. Objaśnienia parametrów przedstawia Tab. 4. Tab. 4. Objaśnienie parametrów modułu do sprawdzenia kosztu wysyłki wiadomości. numer tekst rodzaj Numer telefonu odbiorcy, pod który ma zostać wysłany SMS. UWAGA!!! Koniecznie w postaci międzynarodowej z kodem kraju na początku (bez znaku +) np Treść SMSa, która ma zostać wysłana (treść powinna zostać odpowiednio zakodowana np. funkcją urlencode (w PHP). Obowiązuje kodowanie ISO Rodzaj wysyłanego SMSa: 1 SMS tradycyjny 2 Flash SMS Po wywołaniu adresu z prawidłowymi parametrami, w treści wyświetlonej strony otrzymamy: Koszt:XX gdzie XX oznacza koszt wiadomości (wyraŝony w punktach). W przypadku, kiedy podamy nieprawidłowe parametry lub wystąpi błąd, otrzymamy: ERR:XXX gdzie XXX oznacza trzycyfrowy kod błędu. Znaczenie kaŝdego z kodów znaleźć moŝna w Tab Definiowanie zawartości Pola Nadawcy Pole nadawcy jest to numer lub nazwa nadawcy SMSa, która wyświetla się na telefonie odbiorcy w polu od. Z uwagi na konieczność zachowania wysokich standardów bezpieczeństwa oraz konieczność ograniczenia potencjalnych naduŝyć niezbędne jest uprzednie zdefiniowanie oraz zweryfikowanie zawartości pola nadawcy, które moŝna będzie wykorzystać podczas wysyłania wiadomości SMS. W tym celu naleŝy zalogować się na konto bramki w serwisie GSMService.pl, a następnie wybrać z lewego menu (sekcja MENU GŁÓWNE ) opcję Edycja pola nadawcy. W formularzu moŝna wpisać zarówno numer telefonu, jak i tekst alfanumeryczny, który chcesz Copyright 2008 INTERMEDIA Strona 7

8 wykorzystać w polu nadawcy. Tekst alfanumeryczny moŝe zawierać maksymalnie 11 znaków, w tym małe i duŝe litery od A do Z, cyfry od 1 do 9 oraz znak spacji. Pozostałe znaki nie są akceptowane. Tekst alfanumeryczny po zweryfikowaniu przez operatora Bramki SMS zostanie przypisany do Twojego konta i będziesz mógł go uŝywać w polu nadawcy podczas wysyłania wiadomości SMS. W przypadku, gdy wprowadzisz do formularza numer telefonu, otrzymasz na ekranie wskazówki, w jaki sposób go zweryfikować. KaŜdy uŝytkownik Bramki SMS moŝe zdefiniować dowolną ilość pól nadawcy. W przypadku, gdy wysyłając wiadomość SMS wprowadzisz niezdefiniowane uprzednio pole nadawcy, wiadomość zostanie wysłana z polem nadawcy ustawionym na Bramka SMS. 5. Kody statusów API Opisane w niniejszej dokumentacji funkcje zwracają w rezultacie swojej pracy pewne trzycyfrowe kody, które świadczą o przebiegu danej operacji. W Tab. 5. znajduje się ich spis wraz z niezbędnymi objaśnieniami. Tab. 5. Objaśnienie kodów zwracanych statusów. 000 Brak wystarczającej ilości punktów na koncie w Bramce SMS 001 Błąd techniczny w składni SMSa 002 SMS nie został wysłany 003 SMS został wysłany 004 Sieć, do której próbowano wysłać SMSa jest obecnie niedostępna 005 Numer odbiorcy jest nieprawidłowy 006 Brak treści SMSa 007 Problem z doręczeniem SMSa (abonent ma wyłączony telefon, jest poza zasięgiem sieci, jego numer został przeniesiony lub jego skrzynka odbiorcza jest przepełniona itp.) 008 Nieprawidłowy Login lub/i hasło do subkonta API 009 Nieprawidłowy rodzaj SMSa 010 SMS oczekuje w kolejce na wysłanie 011 Trwa oczekiwanie na zwrócenie statusu SMSa przez sieć GSM 012 Wiadomość anulowana przez uŝytkownika 013 SMS został doręczony do odbiorcy (otrzymano raport doręczenia). UWAGA! Status ten aktywny jest w nie wszystkich docelowych sieciach. Sieci, które nie obsługują raportów doręczeń zwrócą status FAX został przekazany do operatora. 201 FAX został wysłany do odbiorcy. 202 Linia odbiorcy była zajęta. FAX nie został wysłany. 203 Brak sygnału faksu. Prawdopodobnie pod podanym numerem nie pracuje fax. 204 Nie udało się odebrać informacji o rezultacie wysyłania faksu. 205 Połączenie nie zostało odebrane Zbyt niska jakość połączenia ze strony odbiorcy nie pozwala na wysyłkę faksu pod ten numer. Faks wysyłający nie rozpoczął transmisji obrazu. Faks został częściowo wysłany. Przetransmitowano tylko cześć stron gdyŝ połączenie zostało przerwane. 208 Błąd protokołu. FAX nie został wysłany. 209 Faks wysyłający i odbierający nie uzgodniły opcji transmisji. Copyright 2008 INTERMEDIA Strona 8

9 210 Wiadomość jest w trakcie wysłania. 211 Wystąpił nieoczekiwany błąd. Wiadomość nie została wysłana. 212 Wiadomość jest w trakcie wysłania. 6. Dodatkowe informacje i kontakt Odpowiedzi na Wasze pytania oraz dodatkowe informacje uzyskać moŝna kontaktując się z nami: PHU INTERMEDIA www: bramka@gsmservice.pl tel.: fax.: Dodatkowe informacje znaleźć moŝna równieŝ pod adresem Copyright 2008 INTERMEDIA Strona 9