MitarbeiterWebservice

Wichtiger Hinweis: Diverse Funktionen stehen auch in moderneren Ameise-API's zur verfügung. Wenn sich Dein Use-Case damit abbilden lässt, emfehlen wir diese anstelle des MitarbeiterWebservice's zu nutzen

☛ Basisverwaltung von Kunden & Verträgen: Bestands-API

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

Mandant-ID / Kürzel-Mapping

ID	Kürzel	Mandant
1001	bd	blau direkt
1002	ari	Arisecur

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

Integration- / Testumgebung

https://mitarbeiterwebservice-maklerinfo.inte.dionera.dev/service/${mandant}/employee/${version}/rest

Produktion

https://mitarbeiterwebservice.maklerinfo.biz/service/${mandant}/employee/${version}/rest

Authentifizierung

Siehe oAuth2 / OIDC
Benötigter oAuth2 scope: ameise/mitarbeiterwebservice

ServiceAccount unterstützung

Version
v1	Ja

Funktionen

Name	HTTP	Eingabe	Ausgabe
getMitarbeiter	GET ${pfad}/{$ma}		JSON Mitarbeiter
getMitarbeiterRechte	GET ${pfad}/{$ma}/rechte		ArrayOf string
getCourtageliste	GET ${pfad}/{$ma}/courtageliste		JSON Courtageliste
getLicenses	GET ${pfad}/{$ma}/lizenzen		ArrayOf string
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
Hauptvermittler	string
Uebervermittler	string
Anrede	EnumValue getAnreden
Vorname	string
Nachname	string
Profilbilder	ArrayOf Thumbnail
Geburtsdatum	Date
Adresse	Adresse
Kontaktdaten	Kontaktdaten

Courtageliste

Name	Typ	Anmerkung
Id	string

Vermittler

Name	Typ	Anmerkung
Id	string
PublicId	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--