REST API v1 ^(legacy)

Uwaga

API REST v1 jest wersją przestarzałą. Zalecamy korzystanie z nowego interfejsu REST API.

Interfejs SARE REST API działa z wykorzystaniem protokołów http i https (połączenie szyfrowane). Poszczególne funkcje wybierane są poprzez wywołanie odpowiedniego pliku.

acq.php

Dokumentacja API skryptu służącego do dodania (lub sprawdzenia) adresu w bazie klienta

1. Parametry wejściowe (metoda GET lub POST)

Nazwa	Opis	Wymagany	Typ
s_uid	UID użytkownika w SARE	TAK	String
s_key	unikalny klucz do dopisywania	TAK	String
s_email	adres e-mail do 255 znaków	TAK	String
s_gsm	numer GSM (moduł SMS) w formacie +48…	NIE	String
s_encoded	kodowanie znaków: ‘utf-8′ – domyślnie ‘iso-8859-2′ ‘iso-8859-1′	NIE	String
s_group_[0-31]	numer grupy do której dopisad: 0 – domyślnie do żadnej Przykład: s_group_2=1&s_group_4=1	NIE	Bool
s_name	pole nazwa	NIE	String
s_comment	pole opis	NIE	String
s_type	typ prenumerowanego newslettera: ‘text,HTML’ – newsletter HTML + txt (domyślnie) ‘text’ – newsletter plain text	NIE	String
s_property[1-9]	pola z dodatkowymi cechami	NIE	String
s_cust_[nazwa]	pola z rozszerzonymi cechami (zgodnie ze strukturą zdefiniowaną w systemie)	NIE	String/ Enum
s_interface	numer interfejsu zbierającego 1-9 0 – domyślnie	NIE	Integer
s_ip	IP dopisującego	NIE	String
s_no_send	jeżeli ustawione – nie wysyła prośby o potwierdzenie, nie wyświetla strony, tylko zwraca mainkey (“key=????????”) 0 – domyślnie	NIE	Bool
s_rv	jeżeli ustawione – nie wyświetla strony, tylko zwraca kod wyniku 0 – domyślnie	NIE	Bool

Uwaga

UWAGA! Parametry typu string powinny być zakodowane np. przez urlencode()

2. Wartości zwracane oraz kody błędów (tylko jeżeli s_rv=1)

Wartość zwracana	Opis
1	adres dopisany pomyślnie
4	adres istnieje w bazie, ale nie został potwierdzony
7	adres istnieje w bazie, ale jest zablokowany przez operatora
8	adres istnieje w bazie i jest już potwierdzony
-1	brak któregoś z wymaganych parametrów
-2	adres e-mail niepoprawny składniowo
-3	numer UID niepoprawny składniowo
-4	niepoprawny klucz do dopisywania
-5	numer GSM niepoprawny składniowo
-97	ustawiony limit API
-98	niewłaściwy UID
-99	błąd połączenia z bazą danych

3. Przykłady użycia

3.1 Dodanie adresu user@domena.pl do bazy klienta o UID=001 i globalnym kluczu 16c609d3451133ec09231 http://s.enewsletter.pl/acq.php?s_uid=001&s_key=16c609d3451155ec09231&s_ema il=user@domena.pl Domyślnie zostały ustawione: – kodowanie znaków na UTF-8 – format przesyłki na text/HTML

3.2 Dodanie adresu user@domena.pl do bazy klienta o UID=001 i globalnym kluczu 16c609d3451155ec09231 z przesyłką w formacie tekstowym i kodowaniem ISO http://s.enewsletter.pl/acq.php?s_uid=001&s_key=16c609d3451155ec09231&s_ema il=user@domena.pl&s_encoded=iso-8859-2&s_type=text

3.3 Wywołanie zwracające tylko kod wynikowy http://s.enewsletter.pl/acq.php?s_uid=001&s_key=16c609d3451155ec09231&s_ema il=user@domena.pl&s_rv=1>

4. Testowanie

Podczas błędnych wywołano zostanie wyświetlony jedynie komunikat błędu. W celu sprawdzenia kodu błędu niezbędne jest wywołanie z s_rv=1. SARE posiada zabezpieczenie polegające na ignorowaniu adresu e-mail, który jest dodawany po raz drugi w ciągu 10 min. W takim wypadku SARE zwróci 1 (podgląd z włączoną opcją s_rv=1) – wyniki mogą być mylące.

upd.php

Dokumentacja API skryptu do aktualizacji adresów e-mail w bazie klienta

1. Parametry wejściowe (metoda GET lub POST)

Nazwa	Opis	Wymagany	Typ
s_uid	UID użytkownika w SARE	TAK	String
s_mkey	unikalny klucz adresu zapisanego w bazie klienta	TAK	String
s_gsm	numer GSM (moduł SMS) w formacie +48…	NIE	String
s_encoded	kodowanie znaków: ‘utf-8′ – domyślnie ‘iso-8859-2′ ‘iso-8859-1′	NIE	String
s_group_[0-31]	numer grupy, do której dopisać: 0 – domyślnie do żadnej Przykład: s_group_2=1&s_group_4=1	NIE	Bool
s_groupoff_[0-31]	numer grupy, z której wypisad: 0 – domyślnie z żadnej Przykład: s_groupoff_2=1	NIE	Bool
s_name	pole nazwa	NIE	String
s_comment	pole opis	NIE	String
s_type	typ prenumerowanego newslettera: ‘text,HTML’ – newsletter HTML + txt (domyślnie) ‘text’ – newsletter plain text	NIE	String
s_property [1-9]	pola z dodatkowymi cechami	NIE	String
s_cust_[nazwa]	pola z rozszerzonymi cechami (zgodnie ze strukturą zdefiniowaną w systemie)	NIE	String/ Enum
s_ip	IP aktualizującego	NIE	String
s_redirect	URL do przekierowania po aktualizacji	NIE	String

Uwaga

UWAGA! Parametry typu string powinny być zakodowane np. przez urlencode()

2. Wartości zwracane oraz kody błędów (tylko jeżeli s_rv=1)

Wartość zwracana	Opis
1	adres zaktualizowany pomyślnie
7	adres istnieje w bazie, ale jest zablokowany przez operatora
-1	brak któregoś z wymaganych parametrów
-2	adres e-mail niepoprawny składniowo
-3	numer UID niepoprawny składniowo
-4	niepoprawny klucz adresu
-5	numer GSM niepoprawny składniowo
-97	ustawiony limit API
-98	niewłaściwy UID
-99	błąd połączenia z bazą danych

3. Przykłady użycia

3.1 Ustawienie kodowania ISO i typu txt dla newsletterów przesyłanych na adres o kluczu 51133ec09231 w bazie klienta o UID=001 http://s.enewsletter.pl/upd.php?s_uid=001&s_mkey=51133ec09231&s_encoded=iso-8859-2&s_type=text

3.2 Zmiana nazwy adresu o kluczu 51133ec09231 w bazie klienta o UID=001 i przekierowanie do strony www.sare.pl http://s.enewsletter.pl/upd.php?s_uid=001&s_mkey=51133ec09231&s_nazwa=Nazwa&s_redirect=http://www.sare.pl

3.3 Przepisanie adresu o kluczu 51133ec09231 w bazie klienta o UID=001 z grupy 1. do grupy 2. http://s.enewsletter.pl/upd.php?s_uid=001&s_mkey=51133ec09231&s_group_2=1&sgroupoff_1=1

4. Testowanie

Skrypt zmienia tylko te dane, które zostały ujęte w parametrach wywołania. Dla przykładu wywołanie: http://s.enewsletter.pl/upd.php?s_uid=001&s_mkey=51133ec09231 nie zmieni żadnych danych w bazie. W wywołaniu nie podajemy adresu e-mail do modyfikacji – jest on ustalany za pomocą klucza s_mkey

chk.php

Dokumentacja API skryptu do sprawdzenia adresu w bazie

1. Parametry wejściowe (metoda GET lub POST)

Nazwa	Opis	Wymagany	Typ
s_uid	UID użytkownika w SARE	TAK	String
s_key	unikalny klucz do dopisywania	TAK	String
s_email	adres e-mail do 255 znaków	TAK	String

?> UWAGA! Parametry typu string powinny być zakodowane np. przez urlencode()

2. Wartości zwracane oraz kody błędów (tylko jeżeli s_rv=1)

Wartość zwracana	Opis
8	adres zapisany i potwierdzony
7	adres zablokowany
6	adres zapisany niepotwierdzony
5	adres zapisany brak weryfikacji
4	chęć wypisania adresu
3	adres wypisał się
2	adres wypisany ręcznie
0	brak adresu w bazie
-1	brak któregoś z wymaganych parametrów
-2	adres e-mail niepoprawny składniowo
-3	numer UID niepoprawny składniowo
-4	niepoprawny klucz do dopisywania
-97	ustawiony limit API
-98	niewłaściwy UID
-99	błąd połączenia z bazą danych

3. Przykłady użycia

3.1 Sprawdzenie adresu user@domena.pl w bazie klienta o UID=001 i globalnym kluczu 16c609d3451133ec09231 http://s.enewsletter.pl/chk.php?s_uid=001&s_key=16c609d3451155ec09231&s_email=user@domena.pl

rm.php

Dokumentacja API skryptu do usuwania adresów e-mail z bazy klienta

1. Parametry wejściowe (metoda GET)

Nazwa	Opis	Wymagany	Typ
u	UID użytkownika w SARE	TAK	String
key	unikalny klucz do zapisywania	TAK	String
mkey	unikalny klucz adresu zapisanego w bazie klienta	TAK	String
ml	kod mailingu do aktualizacji	NIE	Integer

2. Przykłady użycia

2.1 Usunięcie adresu o kluczu 9994c z bazy klienta o UID=001 i kluczu głównym ba1957be5 http://s.enewsletter.pl/rm.php?u=001&key=ba1957be5&mkey=9994c

2.2 Usunięcie adresu o kluczu 9994c z bazy klienta o UID=001 i kluczu głównym ba1957be5 oraz modyfikacja mailingu o numerze 5567cd http://s.enewsletter.pl/rm.php?u=001&key=ba1957be5&mkey=9994c&ml=5567cd

3. Testowanie

Skrypt nie sprawdza poprawności argumentu ml (kod mailingu). Adresy nie są usuwane fizycznie z bazy,a jedynie zmieniany jest ich status, dlatego jeden adres można ‘usunąć’ wielokrotnie.