SOAP

Adres usługi (wsdl)
https://www.enewsletter.pl/api/server.php?wsdl

Wymagania

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:

I 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 <Nazwa_firmy>.key -out <Nazwa_firmy>.pem -subj '/O=<Nazwa firmy>/OU=WebApi/CN=<uid>'

2. Plik <Nazwa_firmy>.pem należy przesłać do działu IT SARE. Nie przesyłamy pliku z kluczem prywatnym. (<Nazwa_firmy>.key)

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

3. Użycie kluczy dla PHP5 (wbudowany moduł SOAP)
Sklejamy klucz prywatny .key i fragment certyfikatu <nazwa_firmy>_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

Metody
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

Możliwość komentowania jest wyłączona.