Skip to content

MitarbeiterWebservice

Allgemein

Dieser Webservice ermöglicht es Maklermitarbeitern sich im MVP anzumelden..

Platzhalter

Auf dieser Seite werden folgende Platzhalter verwendet welche abhängig vom Consumer ersetzt werden müssen:

Platzhalter Beschreibung
${mandant} Kürzel des Mandanten
${version} Versionsnummer der Schnittstelle
${pfad-sts} Pfad zum Authentifizierungsserver
${pfad} Die Basis URL der Schnittstelle
${ma} Die Mitarbeiter-ID
${Auth} Alle HTTP-Header zwecks der Authentifizierung
${*-Id} Bezieht sich auf die Id eines Speziellen Objektes

HTTP-Header

Allen Parametern welche im HTTP-Header übertragen werden und nicht zu einem offiziellen Standard gehören oder zweckentfremdet wurden MUSS der Präfix X-Dio- voran gestellt werden.

Basis URL

Die Basis URL der Schnittstelle ist wie folgt aufgebaut:
https://www.maklerinfo.biz/service/${mandant}/employee/${version}/rest

Authentifizierung

Die Authentifizierung, sowie das Anfordern eines neuen Passwortes, werden im Artikel MitarbeiterWebservice - Authentifizierung beschrieben

Funktionen

Name HTTP Eingabe Ausgabe
getMitarbeiter GET ${pfad}/{$ma} JSON Mitarbeiter
getVermittler GET ${pfad}/{$ma}/vermittler/${Vermittler-Id} JSON Vermittler

Kundenverwaltung

MitarbeiterWebservice - Kundenverwaltung

Vertragsverwaltung

MitarbeiterWebservice - Vertragsverwaltung

Archivierung

MitarbeiterWebservice - Archivierung

Listen

MitarbeiterWebservice - Listen

Fehlerbehandlung

Über den Erfolg eines Aufrufes gibt der HTTP-Status-Code im Header der Antwort aufschluss. Ist eine Aktion erfolgreich wird i.d.R der code 200 (OK) zurückgegeben. Falls ein Fehler aufgetreten ist und die Ursache beim Client liegt, wird mit einem der 4xx codes geantwortet, liegt die Ursache beim Server mit 500 (Internal Server Error). Liegt der Fehler beim Anwender wird zusätzlich im HTTP-Body ein JSON-Objekt mit den anzuzeigenden Meldungen ausgegeben, falls nicht wird eine standard HTML-Fehlerseite ausgegeben.

Beispiel

HTTP/1.1 400 Bad Request
Content-Length: 69
Content-Type: application/json
Connection: close

{
    "Meldungen": [
        "Dieser Benutzername ist bereits vergeben."
    ]
}

Datentypen

SimpleTypes

Name Basis-Typ Anmerkung
DateTime string Als Format bei der Eingabe können Alle gängigen Datumsformatierungen angegeben werden welche automatisiert aufgelöst werden können, die unterstützten Formate können Sie unter php.net einsehen. Sofern ein offizieller Standard kein anderes Format vorschreibt (zB. HTTP Last-Modified Header) wird das Format YYYY-MM-DDTHH:II:SS zurückgegeben, beziehend auf die Zeitzone Europe/Berlin.
☛ Sollte sich das Gerät in einer anderen Zeitzone befinden, geben Sie diese bei Anfragen an!
Date string Als Format bei der Eingabe können Alle gängigen Datumsformatierungen angegeben werden welche automatisiert aufgelöst werden können, die unterstützten Formate können Sie unter php.net einsehen. Sofern ein offizieller Standard kein anderes Format vorschreibt (zB. HTTP Last-Modified Header) wird das Format YYYY-MM-DD zurückgegeben
Uri string Verweise auf weitere Resoursen innerhalb des Service's
EnumValue string Bezieht sich auf den Schlüßel (Value) eines EnumerationItem's

EnumerationItem

Name Typ Anmerkung
Value string Schlüßel
Text string Text zur Darstellung

Mitarbeiter

Name Typ Anmerkung
Id string
Vermittler string Vermittlernummer
Anrede EnumValue getAnreden
Vorname string
Nachname string
Profilbilder ArrayOf Thumbnail
Geburtsdatum Date
Adresse Adresse
Kontaktdaten Kontaktdaten

Vermittler

Name Typ Anmerkung
Id string
Name string
Namenszusatz string
Logos ArrayOf Thumbnail
Website
Nachname
Geburtsdatum
Adresse Adresse
Kontaktdaten Kontaktdaten

Adresse

Name Typ Anmerkung
Strasse string
Postleitzahl string
Ort string

Kontaktdaten

Name Typ Anmerkung
Telefon string
Fax string
Mobil string
EMail string
Skype string

Thumbnail

Name Typ Anmerkung
Pfad string
Breite int falls leer wurde das Bild entsprechend der Höhe skaliert
Hoehe int falls leer wurde das Bild entsprechend der Breite skaliert

Meldungen

Erfolgs- o. Fehlermeldungen je nach Status

Name Typ Anmerkung
Meldungen ArrayOf string

Mime-Types

Name MIME
JSON application/json
Text text/plain
PDF application/pdf
Datei

Caching

Bestimmte Rückgaben von Funktionen lassen sich cachen.
Wird dies bei einer Funktion unterstützt werden folgende Header zurückgegeben:

Name Datentyp Beschreibung
Cache-Control string "private" oder "public" gibt an ob der Cache sich auf den eingeloggten Kunden bezieht (und somit beim logout gelöscht werden muss) oder ob die Daten auch danach noch bestehen bleiben dürfen
Last-Modified DateTime

Wird der If-Modified-Since Header bei einem weiteren Aufruf übergeben wird dieser mit dem der Datum der letzten Änderung verglichen. Ist dieser kleiner, wird die angeforderte Ressource zurück gegeben, sonst gibt der Service eine leere Antwort mit dem HTTP-Status "304 Not Modified" zurück.

Beispiele

If-Modified-Since: Thu, 10 Sep 2015 13:30:31 GMT
Cache-Control: private, must-revalidate, max-age=3600

HTTP/1.1 304 Not Modified
Last-Modified: Thu, 10 Sep 2015 13:30:31 GMT
Cache-Control: private, must-revalidate, max-age=3600
Content-Length: 0
Connection: close

MultiCall

Es ist möglich mehrere Funktionen in einer Anfrage aufzurufen. Dies kann den erstmaligen Aufbau einer Seite beschleunigen sowie die Abfrage ob sich gecachete Ressourcen verändert haben. In diesem Fall MUSS ein POST-Request auf die URL ${pfad} getätigt werden welches als Content-Type den Wert multipart/related; multipart/related; boundary=MIME_boundary; start="<55f2a57f2fc60>" enthällt (Die Werte für boundary & start dürfen Angepasst werden).

In den jeweiligen Content-Abschnitten MÜSSEN folgende Header vorkommen:

Name Typ Beschreibung
Content-ID string ID des Abschnitts
Method string Die HTTP-Methode welche bei einem normalen Request verwendet worden wäre
Path string Der Pfad welcher bei einem normalen Request verwendet worden wäre

Der Service Antwortet nun ebenfalls mit einem Content-Type multipart/related, der HTTP-Status wird immer, sofern authentifiziert, 200 OK sein.
Es werden mindestens folgende Header für jeden Content Abschnitt zurückgeliefert:

Name Typ Beschreibung
Content-ID string ID des Abschnitts
Status string Der HTTP-Status welcher bei einem normalen Request zurückgegeben worden wäre
Request-ID string Die entsprechende Content-ID der Anfrage auf welche sich dieser Abschnitt bezieht

Beispiel

Request getKunde & getKundenAdressen:

POST ${pfad} HTTP/1.1
${Auth}
Content-Type: multipart/related; boundary=MIME_boundary; start="<55f2a57d6f824>"
Connection: close

--MIME_boundary
X-Dio-Method: GET
X-Dio-Path: /${ma}/kunden/${Kunde-Id}
If-Modified-Since: Thu, 10 Sep 2015 13:30:31 GMT
Content-ID: <55f2a57d6f824>

--MIME_boundary
X-Dio-Method: GET
X-Dio-Path: /${ma}/kunden/${Kunde-Id}/adressen
Content-ID: <55f2a57d6f86b>

--MIME_boundary--

Response (gekürzt):

HTTP/1.1 200 OK
Content-Type: multipart/related; boundary=MIME_boundary; start="<55f2a57f2fc60>"
Connection: close

--MIME_boundary
X-Dio-Request-ID: <55f2a57d6f824>
Last-Modified: Thu, 10 Sep 2015 13:30:31 GMT
Cache-Control: private, must-revalidate, max-age=3600
X-Dio-Status: 304 Not Modified
Content-ID: <55f2a57f2fc60>

--MIME_boundary
X-Dio-Request-ID: <55f2a57d6f86b>
X-Dio-Status: 200 OK
Content-Type: application/json
Content-ID: <55f2a57f2fcb5>

[{"Uri": ... }]

--MIME_boundary--