Rubrik: Schnittstellen / API, Formulare, An- und Abmelden, Einbindung in die Webseite

Schnittstelle zum externen Update von Empfängerdaten

| Drucken |
Schnittstelle zum externen Update von Abonnenten-Daten

Der folgende Artikel beschreibt das Update von Empfängerdaten, um z.B. Datenfelder einzelner Empfänger direkt aus Ihrer Webanwendung heraus zu ändern.

Diese Anleitung ist für Entwickler und Programmierer gedacht und setzt entsprechende Kenntnisse voraus.

Mithilfe dieser Schnittstelle können Sie die Inhalte von Datenfeldern, die bei Ihren Empfängern gespeichert sind, direkt verändern.

Dazu müssen die zu ändernden Datenfelder und deren Werte per POST-Request (mit Content-Type: application/x-www-form-urlencoded) an diese URL übergeben werden:

https://xyz.frnl.de/api/subscriber/
(http ist ebenfalls möglich, aus Sicherheitsgründen aber nicht empfehlenswert)

xyz ersetzen Sie bitte durch die Nummer Ihres Servers, die Zahl ist identisch zu der in Ihrer Login-Adresse zum Control Center.

Parameter  * kennzeichnet Pflichtfelder
user *
Ihr Benutzername
list *
die ID der Liste, in der der Empfänger gespeichert ist. Sie finden die ID der Liste u.a. im Control Center, ganz oben bei "Aktuelle Liste: Listenname (ID: 1234)"
email *
die Email-Adresse des abzufragenden Empfängers
hash *
der Sicherheitshash. MD5-Hash aus Email-Adresse, Listen-ID und einem geheimen Schlüssel. Den geheimen Schlüssel vereinbaren Sie bitte vor der ersten Nutzung der API mit uns.
PHP-Beispiel-Code:

$hash = md5($email.$list.$secret)
name Name des Empfängers. name ist ein Systemfeld, d.h. es ist bei jedem Empfänger automatisch vorhanden
fx f (für "field") mit folgender ID des zu ändernden Datenfeldes
Zusätzlich angelegte Datenfelder sind in jeder Liste mit einer ID-Nummer hinterlegt. So könnte z.B. die ID des Datenfeldes "Vorname" in Ihrer Liste "123" sein. Die jeweilige ID übernehmen Sie einfach aus dem HTML-Code Ihres Formulares.
Beispiel:
HTML-Code im Anmeldeformular:
<td>Vorname</td><td><input type='text' name='field[<font color="#FF0000">123</font>,0]' value='' /></td>
Um den Vornamen zu ändern. ist also der Parameter f123 zu übergeben
  • Um mehrere Datenfelder zu ändern, übergeben Sie einfach alle gewünschten Datenfelder mit den Werten in einer Abfrage:
    f123=Max&name=Mustermann&f234=Hamburg
  • Soll der Inhalt von Checkboxen-Feldern geändert werden, übergeben Sie den Wert "checked" für eine markierte Checkbox und "unchecked" für eine inaktive Checkbox

Wichtig:

Übergeben Sie Zeichenketten aus Benutzereingaben, wie z.B. "name" und andere Datenfelder immer URL-kodiert, damit Leer- und Sonderzeichen in URL-taugliche Zeichen umgewandelt werden. Ein Leerzeichen " " wird damit z.B. zu " " umgewandelt.

PHP: rawurlencode($string)
[removed] encodeURIComponent(string)
Python 2.x: (import urllib) urllib.quote(string)
Python 3.x (import urllib.parse) urllib.parse.quote(string)
Ruby: CGI.escape(string)


Beispiel:
Um Daten für die Emailadresse "test@example.com" in einer Liste mit der ID 555 zu ändern:

URL: http://123.frnl.de/api/subscriber/
POST body:
list=555&hash=0cefb38d0dda115b213353ff2196f390&email=test@example.com&user=testuser&name=Mustermann&f123=Max&f234=Frankfurt am Main


Bei Erfolg erhalten Sie den kompletten neuen Datensatz des Abonnenten im JSON-Format in der Form zurück:


{
    "ID": "12345678",
    "Email": "test@example.com",
    "Name": "Mustermann",
    "subscribe_date": "2009-12-31",
    "subscribe_time": "13:14:15",
    "subscribe_ip": "12.34.56.78",
    "Vorname": "Max"

    "Ort": "Frankfurt am Main"
}


Leere Felder, d.h. nicht vergebene Datenfelder,  enthalten als Wert "null".

Rückgabewerte  
ID die interne ID der Email-Adresse
Email die Email-Adresse
Name der Name des Empfängers
subscribe_date Datum der Anmeldung im ISO-8601 Format
subscribe_time Uhrzeit der Anmeldung
subscribe_ip IP-Adresse, von welcher die Anmeldung erfolgte
weitere Feldnamen jedes angelegte Zusatzdatenfeld wird bei Vorhandensein von Werten ebenfalls ausgegeben

Bei einem Fehler erhalten Sie die Rückgabe im JSON-Format in der Form:

{
    "Error": {
        "Fehler-ID": "Fehlermeldung im Klartext"
    }
}

Hinweise:

  • Wenn Sie für eine Liste die Anmeldung von Duplikaten zugelassen haben, wird mit der Abfrage immer nur der jeweils erste gefundene Datensatz geändert (in der Regel der zeitlich zuerst eingetragene Empfänger).
  • Es ist nicht möglich, über diese API die Email-Adresse zu ändern. Dazu muss der Empfänger ab- und neu angemeldet werden. Die Daten dazu können Sie vorher über die "Schnittstelle zur externen Abfrage von Abonnenten-Daten" auslesen, dann den Empfänger löschen und anschliessend mit neuer Email-Adresse wieder anmelden.
  • Um Werte von Datenfeldern zu löschen, übergeben Sie einfach einen leeren Wert, z.B. "name="</li> <li>Sie müssen nur Felder und Werte übergeben, die geändert werden sollen. Nicht übergebene Felder bleiben unverändert.</li> <li>Fehlerhafte oder ungültige Parameter werden kommentarlos ignoriert, dazu gehören z.B. auch fehlerhafte IDs.</li> </ul> <p>Sie können die Schnittstelle aus Ihrer Webanwendung aufrufen, mit PHP beispielsweise mithilfe der cURL-Bibliothek oder eines HTTP-Clients, wie z.B. <a href="http://docs.guzzlephp.org/en/latest/">Guzzle, in Python mit Requests usw.
    Die Rückgabe lässt sich dann leicht z.B. per json_decode() in ein Array konvertieren.

    Für Sonderwünsche oder spezielle Fragen kontaktieren Sie uns bitte - wir haben schon für eine Vielzahl von Anwendungen spezielle Schnittstellen und Lösungen für unsere Kunden geschaffen.

War dieser Artikel hilfreich?

Ja Nein