SOAP-Schnittstelle

Nur in den Editionen Pro und Enterprise

Newsletter → Konfiguration → Module → SOAP-Schnittstelle

Damit kann ein Fremdsystem Gruppen lesen und anlegen, Abonnenten anlegen und Abonnenten einer Gruppe zuordnen — eine Warenwirtschaft, ein CRM, ein eigenes Skript.

Für eine neue Anbindung nehmen Sie REST

Die REST-Schnittstelle kann dasselbe, braucht keine zusätzliche PHP-Erweiterung, hat einen eigenen Schlüssel und lässt sich mit jedem Werkzeug ansprechen, das HTTP kann.

SOAP bleibt, weil vorhandene Anbindungen weiterlaufen sollen. Beide laufen nebeneinander, jede mit eigenem Schalter.

---

Voraussetzung

Die PHP-Erweiterung soap. Auf Shared Hosting ist sie alles andere als selbstverständlich.

Fehlt sie, sagt es das Modul beim Einschalten, und Aufrufer bekommen einen sprechenden Fehler statt einer weißen Seite. Bitten Sie Ihren Hoster, sie nachzurüsten — sie heißt dort meist php-soap —, oder nehmen Sie REST.

Der Endpunkt

Steht auf der Modulseite und sieht so aus:

https://ihre-domain.test/?wpng_action=module_wpng_mod_soap

Der Schlüssel

Die SOAP-Schnittstelle benutzt den Sicherheitsschlüssel für Hash-Werte unter Allgemein. Er liegt auf beiden Seiten und unterschreibt jeden Aufruf; übertragen wird er nie.

Dieser Schlüssel kann mehr als die Schnittstelle

Er unterschreibt ausserdem die Bestätigungs- und Abmeldelinks aus der Zeit vor 2.0. Wer ihn an ein Fremdsystem gibt, gibt mehr weg als den Zugang zu dieser Schnittstelle.

Die REST-Schnittstelle hat dafür einen eigenen Schlüssel, der nichts anderes kann. Das ist ein weiterer Grund, für eine neue Anbindung REST zu nehmen.

---

Was die Schnittstelle kann

Vier Aktionen:

Aktion
getGroups	Alle Gruppen mit Nummer und Namen
createGroup	Eine Gruppe anlegen
createAbonnent	Einen Abonnenten anlegen, wahlweise mit Bestätigungsmail
addToGroup	Abonnenten einer Gruppe zuordnen

Mehr nicht. Es gibt kein Lesen, Ändern oder Löschen von Abonnenten und keinen Zugriff auf Newsletter.

addToGroup ersetzt die Gruppen

Die bisherigen Gruppenzuordnungen des Abonnenten werden überschrieben, nicht ergänzt. Der gleichnamige REST-Endpunkt ordnet zusätzlich zu.

Das ist ein Unterschied, über den schon Anbindungen gestolpert sind. Er bleibt so, weil eine Änderung jeden vorhandenen Aufrufer beträfe.

Für Ihre Entwickler

Aufgerufen wird eine Methode, und die Aktion ist ihr erstes Argument:

$client = new SoapClient( null, array(
    'location' => 'https://ihre-domain.test/?wpng_action=module_wpng_mod_soap',
    'uri'      => 'http://wpng',
    'encoding' => 'UTF-8',
) );

$antwort = $client->call( $action, $arParam, '', $signatur );

Eine WSDL gibt es nicht; der Client läuft im Non-WSDL-Modus.

Aktion	Parameter
getGroups	nur time
createGroup	name
createAbonnent	email (Pflicht), title, vname, name, strasse, plz, ort, status, sendOptIn
addToGroup	group_id, abo (Liste von Abonnentenkennungen)

time ist bei der neuen Unterschrift Pflicht und muss eine Unixzeit sein.

Die Antwort ist immer ein Array mit code, message und data. code ist 1 bei Erfolg.

getGroups antwortet anders als die übrigen drei

Die Gruppen stehen unter message, nicht unter data:

{ "code": 1, "message": { "1": "Kundennewsletter", "2": "Interessenten" }, "data": [] }

Das ist seit jeher so und bleibt so — ein Umzug nach data bräche jeden vorhandenen Aufrufer. Bei den anderen drei Aktionen steht in message ein Text und in data das Ergebnis, etwa {"abo_id": 70}.

Wie die Unterschrift gebildet wird, steht ausführlich mit Referenzumsetzung und einem Prüfwert zum Gegenrechnen in der technischen Beschreibung des Plugins. Fragen Sie im Forum danach.

---

Die Unterschrift: neu und alt

Jeder Aufruf trägt eine Unterschrift. Es gibt zwei Formen.

	Bis 1.1.4	Seit 2.0
Verfahren	MD5	HMAC-SHA256
Deckt ab	die Namen der übergebenen Felder	Namen und Werte, dazu den Zeitstempel
Zeitstempel	floss ein, wurde aber nie geprüft	wird geprüft, Fenster 15 Minuten

Warum die alte Form ein Problem ist

Sie deckt nur die Feldnamen ab, nicht die Werte. Wer einen Aufruf mitschneidet, kann daraus

createAbonnent  email=kunde@beispiel.test   group_id=4

machen:

createAbonnent  email=fremd@anderswo.test   group_id=1

Die Unterschrift passt weiterhin. Und weil der Zeitstempel nie geprüft wurde, war ein mitgeschnittener Aufruf unbegrenzt lange gültig.

Ab Werk werden beide Formen angenommen, damit Ihre Gegenstelle nicht am selben Tag umgestellt werden muss.

Der Übergang

1. Heute. Nichts zu tun, bestehende Anbindungen laufen unverändert.
2. Sobald Ihre Gegenstelle die neue Unterschrift schickt: Unter Pflege auf Nur noch die neue Unterschrift annehmen stellen.
3. Der Schalter lässt sich jederzeit zurücknehmen.

Es gibt keinen Stichtag. Jede Installation entscheidet das selbst.

Nicht umstellen, bevor die Gegenstelle so weit ist

Aufrufe schlagen danach fehl, und zwar still — das Fremdsystem bekommt eine Fehlermeldung, Sie sehen davon nichts. Sprechen Sie es mit denen ab, die das System betreuen.

---

Was in Ihre Datenschutzerklärung muss

Nichts zusätzlich. Die Schnittstelle speichert keine eigenen Daten; sie legt Abonnenten und Gruppen an, dieselben Zeilen, die auch das Anmeldeformular schreibt.

Zwei Dinge sollten Sie trotzdem bedenken:

• Wer die Schnittstelle benutzt, bekommt Abonnentendaten zu sehen. Das Fremdsystem ist damit ein Empfänger im Sinne Ihrer Datenschutzerklärung. Wer das ist, wissen nur Sie.
• Über http gehen die Inhalte im Klartext über die Leitung. Die Unterschrift schützt den Schlüssel, nicht die Mailadressen im Aufruf. Betreiben Sie Ihre Website über https.

Und: Ein Abonnent, den ein Fremdsystem anlegt, hat kein Einwilligungsprotokoll. Der Nachweis muss im Fremdsystem liegen. Wer sendOptIn mitschickt, lässt die Bestätigungsmail von hier aus hinausgehen — das ist der bessere Weg.