SOAP

Info

Adres usługi (wsdl)

https://www.enewsletter.pl/api/server.php?wsdl

Wymagania

Aktualnie wymagamy przy połączeniu TLS w wersji v1.2

Do użycia web service wymagamy połączenia SSL z prywatnym certyfikatem, który Państwu wystawimy i podpiszemy w naszym lokalnym CA. W ten sposób rozwiążemy problem uwierzytelniania i autoryzacji, jak i bezpieczeństwa przesyłanych danych. Sposób generowania certyfikatu dla serwera Linux/unix:

Generowanie kluczy osobistych

1. Na serwerze, który będzie łączył się z SARE generujemy klucz i prośbę o podpisanie:

openssl req -new -sha256 -newkey rsa:2048 -nodes -keyout [UID].key -out [UID].pem -subj '/O=<Nazwa firmy>/OU=WebApi/CN=[UID]'

Uwaga

Proszę zwrócić uwagę na UID który należy wstawić w CN.

2. Plik [UID].pem należy przesłać do działu IT SARE. Nie przesyłamy pliku z kluczem prywatnym. ([UID].key)
3. Użycie kluczy dla PHP5 (wbudowany moduł SOAP) Sklejamy klucz prywatny .key i fragment certyfikatu [UID]_signed.pem do jednego pliku .pem Będzie on miał postać zgodnie z poniższym schematem:

-----BEGIN RSA PRIVATE KEY-----
MIICXgIBAAKBgQDpxZYFwQD5VwfsGyluJy5H0hQ2cfhmiHTqHyzZrKwjG/WGtmMd
o0Uy6eNkMfw+vYoHZzrma3dnTjShHfAz6VH4gZgZDSLG6P3WlLMgKgrcTwveRRgK
vvpoXbLllYbVENITuqO7nYU3dJxrP/ILXF/JyBRBL2wNlWkqvjBukRD4fwIDAQAB
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIICPzCCAaigAwIBAgIBCTANBgkqhkiG9w0BAQUFADAmMQ0wCwYDVQQKEwRTQVJF
MRUwEwYDVQQLEwxTQVJFIFJvb3QgQ0EwHhcNMDkwNDIxMTMxMjEyWhcNMTAwNDIx
MTMxMjEyWjAuMQ0wCwYDVQQKEwRUZXN0MQ8wDQYDVQQLEwZXZWJBcGkxDDAKBgNV
-----END CERTIFICATE-----

Po czym ten plik ustawiamy w konstruktorze:

$client = new SoapClient('https://www.enewsletter.pl/api/server.php?wsdl', array('local_cert' => "keycert.pem"));

Argumenty

Obligatoryjność argumentów określona jest w pliku wsdl. Dla przykładu:

<xsd:complexType name="Address">
<xsd:all>
<xsd:element name="email" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="status" type="xsd:integer" minOccurs="0" maxOccurs="1"/>
[...]

Oznacza to, że obiekt typu Address musi mieć ustawioną własność email, ale własność status jest dowolna.

Typy

Typy kompleksowe

Nazwa	Typ	Opis
GroupsArray	tablica	lista grup, do których dopisać nowy adres
Address	tablica/obiekt	subskrybent
AddressesArray	tablica	lista subskrybentów
ImportReturn	tablica/obiekt	informacja zwrotna z importu adresów: uid – UID rozpoznany podczas operacji (z certyfikatu) bad – liczba adresów rozpoznanych jak błędne blocked – liczba adresów zablokowanych systemowo (przez operatora) duplicates – liczba duplikatów
SimpleAddress	tablica/obiekt	uproszczony typ adresu używany podczas usuwania adresów z bazy
SimpleAddressesArray	tablica	lista subskrybentów uproszczonego typu
RemoveReturn	tablica/obiekt	informacja zwrotna z importu adresów: uid – UID rozpoznany podczas operacji (z certyfikatu) removed – liczba usuniętych adresów (zmiana statusu) errors – liczba błędów podczas operacji blocked – liczba adresów zablokowanych systemowo (przez operatora)
LoginReturn	tablica/obiekt	informacja zwrotna logowania: login – wartość określająca poprawność zalogowania (1 – poprawne) uid – UID rozpoznany podczas operacji (z certyfikatu)
CheckGroupReturn	tablica/obiekt	informacja sprawdzenia grupy: exists – wartość logiczna określająca istnienie grupy name – nazwa grupy short – skrótowa nazwa grupy desc – opis grupy addressees – liczba adresów w grupie Wartości name…short są ustawiane tylko jeżeli grupa istnieje
GroupInfo	tablica/obiekt	Lista cech potrzebnych do stworzenia nowej grupy: id – id grupy name – nazwa grupy short – skrócona nazwa grupy desc – opis grupy
CreateGroupReturn	tablica/obiekt	Informacja zwrotna utworzenia grupy: status – wartość logiczna info – informacja o błędach podczas próby utworzenia grupy lub informacja czy grupa została stworzona/nadpisana
ListGroupsReturn	tablica	Lista numerów ID grup zdefiniowanych w systemie

Typ Address

Typ Address jest używany podczas wywoływania funkcji ImportAddresses – służy do reprezentowania adresów dopisywanych/modyfikowanych w bazie.

Nazwa	Typ	Wymagany	Domyślnie	Opis
email	string	TAK	n/d	adres email subskrybenta
gsm	string		-	numer GSM subskrybenta w formacie międzynarodowym (np.: +48123456789)
status	integer		5	status adresu: 2 – wypisany recznie przez operatora 3 – wypisał się (po analizie chęci wypisania) – ustawiany również w wyniku usuwania adresów przez API 4 – chęć wypisania (kliknął w link wypisujący w mailu) 5 – zapisany brak weryfikacji (przy importach przed mailingiem weryfikującym) 6 – zapisany niepotwierdzony (z formularza – został wysłany mail z prośbą o potwierdzenie) 7 – zablokowany przez operatora 8 – zapisany i potwierdzony (tylko do tych adresów można zrealizować wysyłkę)
groups	GroupsArray		-	lista grup, w których znajdzie się adres (identycznie przy nadpisywaniu i aktualizacji adresów) – ustawienie powoduje reset przynależności do grup
groups_add	GroupsArray		-	lista grup, do których dodać adres (podczas aktualizacji można w ten sposób zmienić przynależność adresu do grup)
groups_rem	GroupsArray		-	lista grup, z których wypisać adres (podczas aktualizacji można w ten sposób zmienić przynależność adresu do grup)
name	string		-	pole nazwa w systemie
comment	string		-	pole komentarz w systemie
mail_type	string		text,HTML	format maila, który osoba ma otrzymywać text,HTML – osoba będzie otrzymywać newsletter w wersji HTML wraz z częścią TXT (o ile zostanie zdefiniowana) text – osoba będzie otrzymywać newsletter w wersji TXT (lub nie otrzyma jeżeli nie zdefiniowano części TXT)
prop[1-9]	string (max 255)		-	podstawowe cechy 1-9 adresu
cust_[nazwa cechy]	string		-	rozszerzone cechy adresu zgodnie ze strukturą bazy zdefiniowaną w systemie
interface	integer (1-10)		kolejny numer importu	numer interfejsu (żródła pochodzenia) adresu, zgodnie z tym ustawieniem będą wysyłane odpowiednie komunikaty subskrypcji przy ustawionym parametrze sendConfirmation w metodzie ImportAddresses

Typ SimpleAddress

Typ SimpleAddress jest używany podczas wywoływania funkcji RemoveAddresses – służy do reprezentowania adresów usuwanych z bazy. Adresy można usuwać wykorzystując:

• adres e-mail – unikalny na poziomie bazy klienta
• klucz adresu mkey – unikalny na poziomie bazy klienta (OPCJA AKTUALNIE NIEAKTYWNA)

Usunięcie adresu przy użyciu metody RemoveAddresses nie powoduje fizycznego usunięcia adresu z bazy a jedynie zmianę statusu na 3 – wypisał się.

Nazwa	Typ	Wymagany	Domyślnie	Opis
email	string		-	adres email subskrybenta
gsm	string		-	numer GSM subskrybenta

Metoda Login

Metoda Login powinna zostać wykonana jednorazowo jako pierwsza przed innymi metodami podczas procesu synchronizacji. Obejmuje ona proces SSL handshake’u i sprawdzania poprawności UID w sekcji CN certyfikatu.

Parametry metody ImportAddresses

Nazwa	Typ	Wymagany	Domyślnie	Opis
addresses	AddressesArray	TAK	n/d	lista obiektów typu Address do importu
onDuplicate	string		update	akcja do wykonania gdy importowany adres jest w bazie. Możliwe wartości: “update”- uaktualnij ustawione dane (reszta danych bez zmian) “replace” –nadpisz wszystkie dane (kasuj historie) “skip” – opuść duplikat
onDuplicateStatusChange	bool		true	Flaga nadpisywania status gdy adres istnieje w bazie. Niektóre adresy mogą zostać zablokowane między importami (np. po zgłoszeniu spamu)– ta flaga pozwala nie nadpisywać statusu podczas aktualizacji.
sendConfirmation	bool		false	Flaga wysyłki maila potwierdzającego dopisanie do bazy. Zostanie wysłany komunikat subskrypcji właściwy dla interfejsu dopisanego adresu (własność interface typu Address)

Parametry metody RemoveAddresses

Nazwa	Typ	Wymagany	Domyślnie	Opis
addresses	SimpleAddressesArray	TAK	n/d	lista obiektów typu SimpleAddress do usunięcia z bazy (zmiany statusu)

Parametry metody CheckGroup

Nazwa	Typ	Wymagany	Domyślnie	Opis
groupID	integer	TAK	n/d	ID grupy, której obecność w systemie testujemy, jeżlei istnieje zostanie zwrócona szczegółowa informacja o grupie

Parametry metody ClearGroup

Nazwa	Typ	Wymagany	Domyślnie	Opis
groupID	integer	TAK	n/d	ID grupy do wyczyszczenia, adresy zostaną usunięte z grupy (nie z systemu, jeżeli nie istnieją w żadnej innej grupie zostaną przeniesiona do specjalnej grupy 0)

Parametry metody CreateGroup

Nazwa	Typ	Wymagany	Domyślnie	Opis
group	GroupInfo	TAK	n/d	Dane do założenia nowej grupy. Jeżeli grupa istnieje to jej dane ulegają modyfikacji.

Parametry metody RemoveGroup

Nazwa	Typ	Wymagany	Domyślnie	Opis
groupID	integer	TAK	n/d	ID grupy do usunięcia, przed usunięciem grupy zostaną z niej usunięte adresy (pozostaną w systemie

Metoda ListGroups

Służy do zwrócenia z systemu tablicy numerów ID grup zdefiniowanych w systemie. Medoda nie wymaga parametrów.

Metoda Execute

Jest to jedna z najważniejszych metod w całym interfejsie SOAP. Pozwala ona na wykonanie dowolnego skryptu SAREscript i otrzymanie wyniku jego wykonania.

Nazwa	Typ	Wymagany	Domyślnie	Opis
command	string	TAK	n/d	Skrypt SAREscript do wykonania
base	string	NIE	false	Lista grup, na której należy wykonać skrypt (np. 1,2,3) lub “all” gdy na całej bazie. W takim przypadku skrypt wykonywany jest “w kontekście” każdego z adresów. W przypadku wartości false, skrypt nie używa adresów (jest wykonywany tylko raz).
returnResult	bool	NIE	false	Parametr ma znaczenie tylko jeżeli parametr base jest różny od false. W zależności od jego wartości metoda zwraca dla false tylko informację o liczbie przetworzonych adresów oraz pominiętych (np. przez funkcję system_skipmessage()). Dla true dołącza wynik działania skryptu.

Załączniki

Aktualny schemat WSDL do analizy offline.

Przykładowy skrypt klienta w php4 z wykorzystaniem biblioteki nuSOAP.

Przykładowy skrypt klienta w php5 z wykorzystaniem PHP5:SOAP

Przykładowe wykorzystanie metod SOAP z wykorzystaniem PHP5:SOAP