Zum Inhalt

Ein Fremdsystem anbinden

Nur in den Editionen Pro und Enterprise

Eine Warenwirtschaft, ein CRM, ein Formular auf einer anderen Website soll Abonnenten eintragen. Diese Anleitung geht den Weg über die REST-Schnittstelle — für eine neue Anbindung ist sie die richtige Wahl.

Sie brauchen dafür jemanden, der programmieren kann. Die Schnittstelle ist kein Knopf, sondern eine Schnittstelle.

1. Das Modul einschalten

Newsletter → Konfiguration → Module → REST-Schnittstelle → Modul aktiviert: Ja, dann speichern.

Beim Einschalten entsteht ein Schlüssel: 64 Hexziffern, sichtbar auf der Modulseite. Er ist ein eigener — nicht der der SOAP-Schnittstelle.

Über http gehen die Inhalte im Klartext

Die Unterschrift schützt den Schlüssel, nicht die Mailadressen im Aufruf. Richten Sie ein Zertifikat ein, bevor Sie anbinden. Das Modul weist im Backend darauf hin, wenn Ihre Installation nicht über https läuft.

2. Die Adresse bestimmen

Auf der Modulseite steht die Basisadresse. Sie hat eine von zwei Formen:

mit sprechenden Permalinks    https://ihre-domain.test/wp-json/wpng/v1/
ohne                          https://ihre-domain.test/?rest_route=/wpng/v1/

Geben Sie an Ihre Entwickler die Adresse von der Modulseite weiter, nicht eine selbst gebaute.

3. Den Schlüssel übergeben

Nicht per E-Mail und nicht in einem Ticketsystem. Nehmen Sie den Weg, den Ihr Haus für Zugangsdaten vorsieht.

Was der Schlüssel kann und was nicht

Er erlaubt genau vier Dinge: Gruppen lesen, Gruppen anlegen, Abonnenten anlegen und Abonnenten Gruppen zuordnen. Er gibt keinen Zugriff auf Newsletter, keinen Zugriff auf das Backend und keinen auf bestehende Abonnenten.

Das ist der Unterschied zur SOAP-Schnittstelle, deren Schlüssel auch die Abmeldelinks aus alten Mails unterschreibt.

4. Die Gegenstelle prüft sich an /status

Der erste Aufruf, den Ihre Entwickler machen sollten:

GET /wpng/v1/status

Er legt nichts an und ändert nichts. Kommt

{ "plugin": "wpNewsletterGermany", "version": "2.0.0", "zeit": 1789936431 }

zurück, stimmen Adresse, Schlüssel und Unterschrift — und die Anbindung kann loslegen, ohne einen Testabonnenten in Ihrer Liste zu hinterlassen.

zeit ist die Uhrzeit Ihrer Installation

Das Zeitfenster für einen Aufruf ist 15 Minuten. Läuft die Uhr der Gegenstelle anders, schlagen alle Aufrufe mit wpng_rest_zeit_abgelaufen fehl — und /status sagt, um wie viel.

5. Die Gruppen abholen

GET /wpng/v1/groups

[ { "id": 1, "name": "Interessenten" }, { "id": 2, "name": "Kundennewsletter" } ]

Lassen Sie die Gegenstelle die Nummern holen, nicht fest eintragen. Wer eine Gruppe umbenennt oder neu anlegt, bricht sonst die Anbindung.

6. Einen Abonnenten anlegen

POST /wpng/v1/subscribers
{ "email": "neu@beispiel.test", "vname": "Anke", "name": "Brandt", "sendOptIn": 1 }

Klären Sie status und sendOptIn, bevor der erste Aufruf läuft

Wahl Folge
"sendOptIn": 1 Die Bestätigungsmail geht von hier aus hinaus. Der Abonnent wird erst mit dem Klick aktiv
"status": 2 Der Abonnent ist sofort aktiv, ohne Bestätigung

Der erste Weg ist fast immer der richtige: Dann ist die Einwilligung hier nachweisbar.

Der zweite setzt voraus, dass das Fremdsystem die Einwilligung selbst eingeholt und dokumentiert hat. Fragen Sie nach, wo dieser Nachweis liegt, bevor Sie ihn zulassen — das Plugin schreibt für über die Schnittstelle angelegte Abonnenten kein Einwilligungsprotokoll.

Kennt das System die Adresse schon, kommt 409 zurück, mit der Kennung des vorhandenen Abonnenten. Das ist kein Fehler, sondern genug, um weiterzuarbeiten.

7. Einer Gruppe zuordnen

POST /wpng/v1/groups/2/subscribers
{ "abo": [ 70, 71 ] }

{ "group_id": 2, "zugeordnet": [ 70 ], "unbekannt": [ 71 ] }

Zugeordnet wird zusätzlich — bisherige Gruppen bleiben. Ein Abonnent, den es nicht gibt, lässt den Aufruf nicht scheitern; die Antwort nennt beide Listen.

Die Unterschrift

Jeder Aufruf trägt zwei Kopfzeilen:
X-WPNG-Timestamp Unixzeit
X-WPNG-Signature HMAC-SHA256 über Verfahren, Route, Abfrageteil, Zeit und Rumpf

Das vollständige Beispiel steht unter REST-Schnittstelle.

Die häufigsten drei Fehler beim Anbinden:

Fehler Ursache
wpng_rest_zeit_abgelaufen Die Uhren laufen auseinander. NTP auf beiden Seiten prüfen
wpng_rest_signatur_falsch Meistens der Rumpf: Er muss Zeichen für Zeichen so unterschrieben werden, wie er über die Leitung geht. Wer nach dem Unterschreiben noch einmal json_encode() aufruft, bekommt einen anderen Rumpf
Die leere Zeile fehlt Ohne Abfrageparameter ist die dritte Zeile der Unterschrift leer — der Zeilenumbruch bleibt trotzdem stehen

Was Sie ausserdem regeln sollten

Wer bekommt Abonnentendaten zu sehen? Das Fremdsystem ist damit ein Empfänger im Sinne Ihrer Datenschutzerklärung. Wer das ist, wissen nur Sie — und es gehört hinein.

Was passiert bei einem Abgleich in die andere Richtung? Die Schnittstelle kann nicht lesen, wer sich abgemeldet hat. Wenn Ihr Fremdsystem das wissen muss, brauchen Sie dafür einen anderen Weg — etwa den CSV-Export.

Wer erneuert den Schlüssel, wenn es nötig wird? Neuen Schlüssel erzeugen weist jede Gegenstelle ab, die noch den alten benutzt. Stimmen Sie es vorher ab.

Und wenn es SOAP sein muss

Wenn Ihr Fremdsystem nur SOAP kann, geht das weiter — siehe SOAP-Schnittstelle.

Zwei Unterschiede, die Ihre Entwickler kennen müssen:

  • addToGroup ersetzt die Gruppen des Abonnenten, statt zu ergänzen.
  • getGroups antwortet unter message, nicht unter data.

Und: Es braucht die PHP-Erweiterung soap auf Ihrem Server.