JustRelate

Webservices

Authentifizierung und Zugriff auf Personendaten

Authentifizierung

Eine Person kann mit dem folgenden Request am OMC angemeldet werden:

curl http://hostname/webservice/contacts/authenticate \
  -u webservice:apikey \
  -X POST \
  --form-string authentication[login]=login \
  --form-string authentication[password]=password

Kann die Person anhand der angegebenen Anmeldedaten identifiziert werden, liefert das OMC die Daten der Person wie bei der Abfrage über die ID (siehe unten).

Im Fehlerfall liefert das OMC den Status-Code 422 sowie die folgende Meldung im Body der Response:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Authentication failed.</error>
</errors>

Listen von Personen ermitteln

Vom OMC können Listen von Personen angefordert werden, die Liste aller Personen oder die Liste der zu einem Account gehörenden Personen:

curl http://hostname/webservice/contacts \
  -u webservice:apikey \
  -G 

curl http://hostname/webservice/contacts \
  -u webservice:apikey \
  -G \
  -d filter[account_id]=4

Das OMC gibt die Personen als contact-Elemente im Element contacts zurück. Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<contacts type="array">
  <contact>
    <job_title>Eink&#228;ufer</job_title>
    <title>Dr.</title>
    <updated_at type="datetime">2010-11-29T19:12:34+01:00</updated_at>
    <salutation>Sehr geehrte Frau Doktor Beck</salutation>
    <language>de</language>
    <want_email type="boolean">true</want_email>
    <account_id type="integer">4</account_id>
    <letter_address>Frau Dr. Katrin Beck</letter_address>
    <gender>F</gender>
    <id type="integer">282</id>
    <greeting>Frau Doktor Beck</greeting>
    <fax>+49 6659 3839575</fax>
    <phone>+49 6659 7103442</phone>
    <location_id type="integer">54</location_id>
    <last_name>Beck</last_name>
    <want_snailmail type="boolean">true</want_snailmail>
    <roles type="array"/>
    <login>Katrin.Beck@oezs-spielkiste.com</login>
    <want_phonecall type="boolean">true</want_phonecall>
    <email>Katrin.Beck@oezs-spielkiste.com</email>
    <mobile_phone>+49 166 8371439</mobile_phone>
    <first_name>Katrin</first_name>
    <active type="boolean">true</active>
  </contact>
  <contact>
    ...
  </contact>
</contacts>

Mit den folgenden Parametern können Sie weitere Angaben in das Ergebnis aufnehmen lassen:

  • include[]="location" liefert für jede Person auch deren jeweiligen Standort.
  • include[]="account" gibt für jede Person auch die Daten des Accounts zurück, zu der sie gehört.
  • filter[]="include_inactive" liefert auch deaktivierte Personen.

Personendaten auslesen

Die Daten einer bestimmten Person kann man über deren ID oder Login ermitteln:

curl http://hostname/webservice/contacts/id \
  -u webservice:apikey

curl http://hostname/webservice/contacts/validate_login \
  -u webservice:apikey \
  -G \
  -d login=login

Das OMC liefert, sofern die abgefragte Person existiert, ein XML-Dokument mit ihren Daten im Element contact. Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<contact>
  <job_title>Eink&#228;ufer</job_title>
  <title>Dr.</title>
  <updated_at type="datetime">2010-11-29T19:12:35+01:00</updated_at>
  <salutation>Dear Doctor Heinen</salutation>
  <language>en</language>
  <want_email type="boolean">true</want_email>
  <account_id type="integer">55</account_id>
  <letter_address>Mr. Dr. Bernd Heinen</letter_address>
  <gender>M</gender>
  <id type="integer">288</id>
  <greeting>Doctor Heinen</greeting>
  <fax>+49 6659 9831004</fax>
  <phone>+49 6659 2863019</phone>
  <location_id type="integer">55</location_id>
  <last_name>Heinen</last_name>
  <want_snailmail type="boolean">true</want_snailmail>
  <roles type="array"/>
  <login>Bernd.Heinen@babystaet.com</login>
  <want_phonecall type="boolean">true</want_phonecall>
  <email>Bernd.Heinen@babystaet.com</email>
  <mobile_phone>+49 169 8412311</mobile_phone>
  <first_name>Bernd</first_name>
  <active type="boolean">true</active>
</contact>

Falls der Schlüssel contact_want_webservice_roles_from_subscription_names in der Allgemeinen Konfiguration des OMC den Wert true hat, wird zusätzlich das Feld roles geliefert. Es enthält die Namen der benannten Sammellisten, in die die Person aufgenommen wurde.

Ferner können auch hier zusätzlich die Parameter -d include[]="location" und -d include[]="account" angegeben werden, um auch die Standort- sowie die Accountdaten der Person zu anzufordern.

Personen anlegen oder ändern

Eine Person anlegen

Über einen POST-Request unter Angabe der relevanten Parameter können Sie eine Person anlegen und einem Account zuordnen.

Neben der Account-ID müssen mindestens die folgenden Angaben zu der Person gemacht werden: ihr Nachname (last_name), das Geschlecht (gender: F, M oder N) sowie die Sprache (language). Die verfügbaren Sprachen sind Teil der Allgemeinen Konfiguration.

curl http://hostname/webservice/contacts \
  -u webservice:apikey \
  -X POST \
  --form-string contact[account_id]=4 \
  --form-string contact[last_name]=Hans \
  --form-string contact[first_name]=Muster \
  --form-string contact[gender]=M \
  --form-string contact[location_id]=true \
  --form-string contact[want_email]=true \
  --form-string contact[want_phonecall]=true \
  --form-string contact[want_snailmail]=true \
  --form-string contact[language]=de \
  --form-string contact[active]=true

Der Rückgabewert ist derselbe wie bei der Ermittlung der Personendaten.

Um gleichzeitig, d.h. mit derselben Anfrage, einen Account und einen Standort zu erstellen, muss die account_id weggelassen werden, und die folgenden Felder müssen zusätzlich definiert sein:

  --form-string contact[account_attributes][name]='Account Name' \
  --form-string contact[location_attributes][city]='Stadt Name' \
  --form-string contact[location_attributes][want_assign_geoloc]='false'

Personendaten ändern

Um Daten einer Person zu ändern, verwenden Sie einen PUT-Request unter Angabe der Personen-ID in der URL sowie der zu ändernden Felder im Body des Requests.

curl http://hostname/webservice/contacts/id \
  -u webservice:apikey \
  -X PUT \
  --form-string contact[last_name]="Muster-Beispiel" \
  --form-string contact[login]=muster4352 \
  --form-string contact[email]="info@example.com" \
  --form-string contact[first_name]="Hans-Günther"

Der Rückgabewert ist derselbe wie bei der Ermittlung der Personendaten.

Newsletter-Abonnenten und -Abonnements

Abonnenten eines Newsletters ermitteln

curl http://hostname/webservice/contacts \
  -u webservice:apikey \
  -G \
  -d filter[collection_name]=tips_tricks

Als Ergebnis wird die Liste der Personen zurückgegeben, die in der angegebenen Personen-Sammelliste enthalten sind.

Newsletter-Abonnements einer Person ermitteln

curl http://hostname/webservice/contacts/id/subscriptions \
  -u webservice:apikey

Das Ergebnis enthält im subscriptions-Element die Abonnements der Person als subscription-Elemente.

<?xml version="1.0" encoding="UTF-8"?>
<subscriptions type="array">
  <subscription>
    <title>News</title>
    <name>News</name>
  </subscription>
</subscriptions>

Verfügbare Newsletter ermitteln

curl http://hostname/webservice/contacts/all_subscriptions \
  -u webservice:apikey

Das Ergebnis enthält im subscriptions-Element die von Personen abonnierbaren Newsletters als subscription-Elemente, unabhängig davon, ob einzelne Personen bereits einen oder mehrere dieser Newsletter abonniert haben.

<?xml version="1.0" encoding="UTF-8"?>
<subscriptions type="array">
  <subscription>
    <name>News</name>
  </subscription>
  <subscription>
    <name>Latest_News</name>
  </subscription>
  <subscription>
    <name>vorstellung</name>
  </subscription>
</subscriptions>

Abonnierte Newsletter einer Person ändern

Die Newsletter-Abonnements einer Person können mit einem einzigen Webservice-Aufruf gesetzt werden. Existierende Abonnements werden automatisch entfernt, bevor die angegebenen Abonnements gespeichert werden.

curl http://hostname/webservice/contacts/id/update_subscriptions \
  -u webservice:apikey \
  -X PUT \
  --form-string subscriptions[][name]=News \
  --form-string subscriptions[][name]=Latest_News

Das Ergebnis hat das gleiche Format wie bei der Ermittlung der Abonnements.

Tagebucheinträge

Die individuellen Tagebucheinträge von Personen sind nur über das Web-Interface des OMC zugänglich. Über einen Webservice kann jedoch ein Tagebucheintrag zu einer Person hinzugefügt werden.

Tagebucheintrag zu einer Person hinzufügen

curl http://hostname/webservice/diaries \
  -u webservice:apikey \
  -X POST \
  --form-string diary[type]=web \
  --form-string diary[title]="Kommentar abgegeben" \
  --form-string diary[notes]="Super Seite!" \
  --form-string diary[internal]=false \
  --form-string diary[contact_id]=id

Als Ergebnis wird der neue Tagebucheintrag zurückgegeben:

<?xml version="1.0" encoding="UTF-8"?>
<diary>
  <account_id type="integer">1</account_id>
  <contact_id type="integer">4</contact_id>
  <created_at type="datetime">2010-07-13T15:18:41+02:00</created_at>
  <created_by>webservice</created_by>
  <diary_type>web</diary_type>
  <id type="integer">11</id>
  <internal type="boolean">false</internal>
  <notes>Super Seite!</notes>
  <send_email type="boolean">false</send_email>
  <summary>Kommentar abgegeben</summary>
  <updated_at type="datetime">2010-07-13T15:18:41+02:00</updated_at>
  <updated_by>webservice</updated_by>
</diary>

Passwort

Passwort für eine Person erzeugen und setzen

Bitte beachten Sie, dass das neue Passwort der Person per E-Mail übermittelt wird, wenn ihre E-Mail-Adresse definiert wurde und das System für den E-Mail-Versand konfiguriert wurde.

curl http://hostname/webservice/contacts/id/generate_password \
  -u webservice:apikey \
  -X POST \
  --form-string password[email_options][option1]=Option 1 \
  --form-string password[email_options][option2]=Option 2

Passwort einer Person setzen

curl http://hostname/webservice/contacts/id/update_password \
  -u webservice:apikey \
  -X PUT \
  --form-string password[old]=old_password \
  --form-string password[new]=new_password

Sonstiges

Einstellungen auslesen

Mit dem folgenden Request können Einstellungen wie die definierten Newsletters, Anreden und Sprachen ausgelesen werden:

curl http://hostname/webservice/contacts/lookup_options \
  -u webservice:apikey

Dieser Aufruf gibt ein XML-Dokument mit den genannten Einstellungen im Hauptelement lookup_options zurück. Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<lookup_options>
  <languages type="array">
    <language>
      <name>de</name>
    </language>
    <language>
      <name>en</name>
    </language>
  </languages>
  <subscriptions type="array">
    <subscription>
      <name>News</name>
    </subscription>
    <subscription>
      <name>Latest_News</name>
    </subscription>
  </subscriptions>
  <titles type="array">
    <title>
      <name></name>
    </title>
    <title>
      <name>Dr.</name>
    </title>
    <title>
      <name>Prof.</name>
    </title>
  </titles>
</lookup_options>
© JustRelate Group GmbH · 2024