Einleitung
Die SOAP API stellt die primäre Schnittstelle mit Lese- und Schreibzugriff dar. Mit ihr können Daten objektspezifisch abgefragt und geändert werden. Der Funktionsumfang orientiert sich an den Funktionen des Systems, so dass in einem eingeschränkten Umfang eine Fernsteuerung des Systems möglich wird.
Bitte beachten!
Globale Benutzer, welche zur Nutzung der SOAP-API vorgesehen sind oder bereits dafür verwendet werden, sollten nicht zum arbeiten in der Systemoberfläche verwendet werden.
Wenn dies dennoch der Fall ist, laufen Sie Gefahr durch einen Wechsel in einen Mandanten über die Systemoberfläche den globalen Benutzer zu einem Mandanten-Benutzer zu machen, und zwar solange, bis dieser Benutzer über die Systemoberfläche wieder auf die “Globale Übersicht” wechselt.
Dies kann Auswirkungen auf alle Methoden haben, welche den Parameter mandator_id benötigen. Hier würde dieser globale Benutzer welcher in einen Mandanten gewechselt hat, den Parameter mandator_id ignorieren und stattdessen die ID des Mandanten verwenden, in den er gewechselt wurde.
Verwendung der API
Authentifizierung
Die Authentifizierung erfolgt über Basic Auth. Die erforderlichen Schritte werden in der Regel von den verwendeten Bibliotheken übernommen.
Der für den Zugriff auf die API verwendete Benutzer benötigt das System Recht Webservices 2.0. Wie Sie Rollen und Rechte konfigurieren, erfahren Sie in unserem Beitrag "Rollen und Rechte konfigurieren".
Unterstützte Protokolle
Das SOAP Protokoll ist sprachunabhängig, Server und Clients können in beliebigen Sprachen wie Java, Perl, Python, PHP oder Ruby implementiert werden. Für SOAP sind Bibliotheken integraler Bestandteil vieler Programmiersprachen.
Details zu Bibliotheken finden sich unter https://de.wikipedia.org/wiki/SOAP#Implementierungen
Zugriff auf Objekte bzw. Ressourcen
Folgende Objekttypen können über die Schnittstelle verarbeitet werden:
- Artikel
- Artikel-Vorlagen
- Artikel-Typen
- Container
- Container-Typen
- Datei
- Formular
- Formular Alias
- Bild
- eMailings
- eMailing-Vorlage
- Pool
- Pool Data Miner
- Report
- Zielgruppe
Einschränkungen
Bitte beachten Sie, dass einzeln der Request über die API nicht mehr als 10MB groß sein darf. Dies ist eine Sicherheitsrichtlinie. Größere Requests müssen geteilt übertragen werden.
E-Mail Validierung
Beim Eintragen von E-Mail-Adressen findet eine Validierung statt, die es verhindert, ungültige Email-Adressen in einen Pool einzutragen. Folgende Kriterien werden geprüft:
- E-Mail Syntax korrekt
- E-Mail nicht in Blacklist vorhanden
- Domain hat gültigen A-Record
- Domain hat gültigen MX-Record
Allgemeine Verwendung
EvalancheHashMaps werden überall dort eingesetzt, wo Listen von Key-Value-Paaren benötigt werden, die Keys im jedoch erst zur Laufzeit bestimmbar sind.
Da die Eigenschaft des einzelnen EvalancheHashMapItem vom Typ string sein muss, gelten folgende Regeln bei abweichenden Datentypen:
Mehrzeilige Eingabe (formatiert/HTML-Editor)
Valides XHTML mit optionalem Root-Node, beispielsweise:
Foo & Baroder
<div>Foo & Bar</div>Invalides XHTML kann dazu führen, dass der Artikel über die Oberfläche nicht mehr bearbeitbar ist. Mailings, die einen solchen Artikel enthalten können ggf. nicht mehr versendet werden!
Ganze Zahl
Wird als String-Repräsentation übergeben (in PHP durch strval($integer_value).
Wahr/Falsch
Wahr wird als String mit dem Inhalt 1, Falsch als String mit dem Inhalt 0 übergeben.
Einfachselektionen
Die Options-Id des Wertes wird als String-Repräsentation übergeben.
Datum & Datum mit Uhrzeit
Unix-Timestamp als String-Repräsentation.
Es können auch Datumswerte als String (z.b.: 2020-01-01) übergeben werden, dies führt jedoch dazu, dass auch bei Aktualisierungen mit bereits vorhandenen Datumswerten das Profil-Änderungsdatum gesetzt wird.
Verwendung bei Artikeln und Containern
Mehrfachselektionen: Die Liste der ausgewählten Options-Ids als Liste von Ids getrennt mit “|”, z. B. 123|456|789
Links (Liste): Liste von Objekten mit den Eigenschaften text und url JSON serialisiert, z. B. [{“text”:”DuckDuckGo”,”url”:”https://ddg.gg“},{“text”:”Google”,”url”:”http://www.google.com“}]
Werte (Liste): Liste von Objekten mit den Eigenschaften key und value JSON serialisiert, z. B. [{“key”:”foo”,”value”:”bar”},{“key”:”herp”,”value”:”derp”}]
Bild (Liste): Die Liste der ausgewählten Bild-Ids als JSON serialisierte Liste, z. B. (“[1233,1234,1235]”)
Container (Liste): Die Liste der ausgewählten Container-Ids als JSON serialisierte Liste, z. B. (“[1233,1234,1235]”)
Verwendung bei Profilen
Mehrfachselektionen: Die Liste der ausgewählten Options-Ids als mit | (“pipe”) serialisierter String, z. B. ("|1233|1234|1235|")
Einfachselektionen: Die ausgewählte Options-Id wird ebenfalls als mit | (“pipe”) serialisierter String, z. B. ("|1233|")
UID: Die verschlüsselte ID eines Profiles kann über das virtuelle Attribut “SID” abgefragt werden. Methoden die alle Profildaten zurückliefern ist das virtuelle Attribut “SID” automatisch vorhanden.
WSDL
Informationen zu Zugriffspunkten und WSDL Dateien finden Sie in der folgenden Tabelle:
| Port | WSDL Document/literal | WSDL RPC/encoded |
|---|---|---|
| Article | [LOGIN_DOMAIN]/soap.php/wsdl/article | [LOGIN_DOMAIN]/soap.php/wsdlcompat/article |
| Articletemplate | [LOGIN_DOMAIN]/soap.php/wsdl/articletemplate | [LOGIN_DOMAIN]/soap.php/wsdlcompat/articletemplate |
| Articletype | [LOGIN_DOMAIN]/soap.php/wsdl/articletype | [LOGIN_DOMAIN]/soap.php/wsdlcompat/articletype |
| Blacklist | [LOGIN_DOMAIN]/soap.php/wsdl/blacklist | [LOGIN_DOMAIN]/soap.php/wsdlcompat/blacklist |
| Campaign | [LOGIN_DOMAIN]/soap.php/wsdl/campaign | [LOGIN_DOMAIN]/soap.php/wsdlcompat/campaign |
| Category | [LOGIN_DOMAIN]/soap.php/wsdl/category | [LOGIN_DOMAIN]/soap.php/wsdlcompat/category |
| Container | [LOGIN_DOMAIN]/soap.php/wsdl/container | [LOGIN_DOMAIN]/soap.php/wsdlcompat/container |
| Containertype | [LOGIN_DOMAIN]/soap.php/wsdl/containertype | [LOGIN_DOMAIN]/soap.php/wsdlcompat/containertype |
| Document | [LOGIN_DOMAIN]/soap.php/wsdl/document | [LOGIN_DOMAIN]/soap.php/wsdlcompat/document |
| Form | [LOGIN_DOMAIN]/soap.php/wsdl/form | [LOGIN_DOMAIN]/soap.php/wsdlcompat/form |
| Image | [LOGIN_DOMAIN]/soap.php/wsdl/image | [LOGIN_DOMAIN]/soap.php/wsdlcompat/image |
| Mailing | [LOGIN_DOMAIN]/soap.php/wsdl/mailing | [LOGIN_DOMAIN]/soap.php/wsdlcompat/mailing |
| Mailingvorlage | [LOGIN_DOMAIN]/soap.php/wsdl/mailingtemplate | [LOGIN_DOMAIN]/soap.php/wsdlcompat/mailingtemplate |
| Mandator | [LOGIN_DOMAIN]/soap.php/wsdl/mandator | [LOGIN_DOMAIN]/soap.php/wsdlcompat/mandator |
| Milestone | [LOGIN_DOMAIN]/soap.php/wsdl/milestone | [LOGIN_DOMAIN]/soap.php/wsdlcompat/milestone |
| Pool | [LOGIN_DOMAIN]/soap.php/wsdl/pool | [LOGIN_DOMAIN]/soap.php/wsdlcompat/pool |
| Pooldataminer | [LOGIN_DOMAIN]/soap.php/wsdl/pooldataminer | [LOGIN_DOMAIN]/soap.php/wsdlcompat/pooldataminer |
| Profile | [LOGIN_DOMAIN]/soap.php/wsdl/profile | [LOGIN_DOMAIN]/soap.php/wsdlcompat/profile |
| Report | [LOGIN_DOMAIN]/soap.php/wsdl/report | [LOGIN_DOMAIN]/soap.php/wsdlcompat/report |
| Scoring | [LOGIN_DOMAIN]/soap.php/wsdl/scoring | [LOGIN_DOMAIN]/soap.php/wsdlcompat/scoring |
| Smartlink | [LOGIN_DOMAIN]/soap.php/wsdl/smartlink | [LOGIN_DOMAIN]/soap.php/wsdlcompat/smartlink |
| Targetgroup | [LOGIN_DOMAIN]/soap.php/wsdl/targetgroup | [LOGIN_DOMAIN]/soap.php/wsdlcompat/targetgroup |
| User | [LOGIN_DOMAIN]/soap.php/wsdl/user | [LOGIN_DOMAIN]/soap.php/wsdlcompat/user |