Dokumentacja API 3.0 - Bramka SMS

Transkrypt

http://bramka.gsmservice.pl
e-mail: [email protected]
tel.: +48 12 398 42 52
fax.: +48 12 398 36 44
Bramka SMS:
•
•
•
•
Dokumentacja
interfejsu
SMS HTTP API
Wersja 3.0 [15 styczeń 2008]
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 ver. 3.0 [15.01.2008]
SPIS TREŚCI:
1.
Historia zmian w dokumentacji..................................................................................... 3
2.
Wprowadzenie................................................................................................................ 3
2.1.
2.2.
3.
Krok 1 - Rejestracja konta w GSMService.pl .................................................................... 3
Krok 2 – Aktywacja subkonta API..................................................................................... 4
Podstawowe funkcje dostępne w API .......................................................................... 4
3.1.
3.2.
3.3.
3.4.
Wysyłanie wiadomości SMS ............................................................................................ 4
Status wysłanych SMSów ................................................................................................ 5
Sprawdzanie stanu konta ................................................................................................. 6
Sprawdzenie kosztu SMS’a.............................................................................................. 7
4.
Definiowanie zawartości Pola Nadawcy....................................................................... 7
5.
Kody statusów API ........................................................................................................ 8
6.
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. ............................................... 6
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
1. Historia zmian w dokumentacji.
Wersja
Data
Wprowadzone zmiany
3.0
15.01.2008
Dostosowano dokumentację interfejsu API do nowej platformy
bramki SMS, dodano moŜliwość wysyłania SMSów ze
zdefiniowanym czasem doręczenia wiadomości.
2.8
09.01.2007
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 http://bramka.gsmservice.pl
Za pomocą programu SzybkiSMS [http://www.szybkisms.pl]
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. Parametry 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.
2.1. 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ę http://bramka.gsmservice.pl/register.php,
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.
Strona 3
2.2. Krok 2 – Aktywacja subkonta API
Po zalogowaniu się na http://bramka.gsmservice.pl 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 http://bramka.gsmservice.pl/pricing.php.
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.
3.1. 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:
https://bramka.gsmservice.pl/api/send.php?login=xxxxx&pass=xxxxx&numer=xxxxx&tekst=xx
xxxx&rodzaj=x&podpis=x&showid=1
gdzie xxx to odpowiednie wartości parametrów. Parametry 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.
Parametr
Opis parametrów
login
Login subkonta API w Bramce SMS [zdefiniowany w czasie aktywacji API]
pass
Hasło do subkonta API w Bramce SMS [zdefiniowane w czasie aktywacji API]
Strona 4
numer
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. 48601444555
tekst
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-8859-2.
rodzaj
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
Podpis1, 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!!!
deliv_time
Parametr 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)
showid
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. 5.
3.2. 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):
https://bramka.gsmservice.pl/api/status.php?login=xxxxx&pass=xxxxxx&smsid=xxxx&ilosc=x
gdzie xxx to odpowiednie wartości parametrów, które zostały objaśnione w Tab. 2.
1
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.
Strona 5
Tab. 2. Objaśnienie parametrów modułu do odczytu statusów wysłanych SMSów.
Parametr
Opis parametrów
login
pass
smsid
ilosc
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! Parametry 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.
3.3. 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:
https://bramka.gsmservice.pl/api/stan.php?login=xxxxx&pass=xxxxxx
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.
Parametr
Opis parametrów
login
pass
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.
Strona 6
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:
https://bramka.gsmservice.pl/api/price.php?numer=xxxxxxxxxxx&tekst=xxxxxxxxx&rodzaj=x
gdzie xxx to odpowiednie wartości parametrów. Parametry 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.
Parametr
Opis parametrów
numer
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. 48601444555
tekst
Treść SMSa, która ma zostać wysłana (treść powinna zostać odpowiednio zakodowana
np. funkcją urlencode (w PHP). Obowiązuje kodowanie ISO-8859-2.
rodzaj
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. 5.
4. 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
Strona 7
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.
Parametr
Opis parametrów
000
001
002
003
004
005
006
Brak wystarczającej ilości punktów na koncie w Bramce SMS
Błąd techniczny w składni SMSa
SMS nie został wysłany
SMS został wysłany
Sieć, do której próbowano wysłać SMSa jest obecnie niedostępna
Numer odbiorcy jest nieprawidłowy
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
009
010
011
012
Nieprawidłowy Login lub/i hasło do subkonta API
Nieprawidłowy rodzaj SMSa
SMS oczekuje w kolejce na wysłanie
Trwa oczekiwanie na zwrócenie statusu SMSa przez sieć GSM
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 003
200
201
202
203
204
205
FAX został przekazany do operatora.
FAX został wysłany do odbiorcy.
Linia odbiorcy była zajęta. FAX nie został wysłany.
Brak sygnału faksu. Prawdopodobnie pod podanym numerem nie pracuje fax.
Nie udało się odebrać informacji o rezultacie wysyłania faksu.
Połączenie nie zostało odebrane.
206
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.
207
Faks został częściowo wysłany. Przetransmitowano tylko cześć stron gdyŜ połączenie
zostało przerwane.
208
209
Błąd protokołu. FAX nie został wysłany.
Faks wysyłający i odbierający nie uzgodniły opcji transmisji.
Strona 8
210
211
212
Wiadomość jest w trakcie wysłania.
Wystąpił nieoczekiwany błąd. Wiadomość nie została wysłana.
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:
e-mail:
tel.:
fax.:
http://www.gsmservice.pl
[email protected]
+48 12 398 42 52
+48 12 398 36 44
Dodatkowe informacje znaleźć moŜna równieŜ pod adresem http://bramka.gsmservice.pl/api.php.
Strona 9

Dokumentacja API 3.0 - Bramka SMS

Transkrypt

Podobne dokumenty

Wysyłanie SMSów z Internetu

KPP W ŚWIECIU TELEFON (SMS) PRZEZNACZONY DLA OSÓB

Numer telefonu komórkowego Imię Nazwisko Data urodzenia Ulica

Instrukcja techniczna implementacji ProfitSMS.pl

1. Dane osobowe: Numer telefonu komórkowego Imię Nazwisko

www.azp.pila.pl/sms - Aeroklub Ziemi Pilskiej