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:
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:4096 -nodes -keyout <UID>.key -out <UID>.pem -subj '/O=<Nazwa firmy>/OU=WebApi/CN=<UID>'
2. Plik <UID>.pem należy przesłać do działu IT SARE. Nie przesyłamy pliku z kluczem prywatnym. (<UID>.key)
Proszę zwrócić uwagę na UID który należy wstawić w CN.
3. Użycie kluczy dla PHP (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 |
| 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 |
| 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