VermittlerWebservice

Allgemein

Dieser Webservice ermöglicht Makler den Zugriff auf ihren Bestand

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}	Die Basis URL der Schnittstelle
${vmt}	Die Vermittlernummer
${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}/broker/${version}/rest

Authentifizierung

Die Authentifizierung wird im Artikel VermittlerWebservice - Authentifizierung Beschrieben

Funktionen

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."
    ]
}

Error-Codes bei der Authentifizierung

400	Auth-Header unplausibel oder unplausibles Digest
403	Vermittler ist gesperrt
404	Api-ID existiert nicht
500	technischer Fehler oder Infrastruktur-Problem

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

Kundenverwaltung

☛ VermittlerWebservice - Kundenverwaltung

Vertragsverwaltung

☛ VermittlerWebservice - Vertragsverwaltung

Archivierung

☛ VermittlerWebservice - Archivierung

Mime-Types

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

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 & getAdressen:

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: /${vmt}/kunden/${Kunde-Id}
Last-Modified: Thu, 10 Sep 2015 13:30:31 GMT
Content-ID: <55f2a57d6f824>

--MIME_boundary
X-Dio-Method: GET
X-Dio-Path: /${vmt}/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--

Beispiel PHP mit fsockopen

$otp='177c29 ... d063a9';
$vermittler='012XYZ';
$kunde='123456';
$boundary = "MIME_boundary-" . md5(mt_rand() . microtime());
$start = 'get-laender';


$parts = [
    [
        'id' => 'get-laender',
        'method' => 'GET',
        'path' => '/laender'
    ],
    [
        'id' => 'get-gesellschaften',
        'method' => 'GET',
        'path' => '/'.$vermittler.'/gesellschaften'
    ],
    [
        'id' => 'get-kunde-'.$kunde,
        'method' => 'GET',
        'path' => '/'.$vermittler.'/kunden/'.$kunde
    ],
    [
        'id' => 'get-kunde-adressen-'.$kunde,
        'method' => 'GET',
        'path' => '/'.$vermittler.'/kunden/'.$kunde.'/adressen'
    ]
];


$body = implode(
    "\n",
    array_map(function($part) use ($boundary) {
        return '--'.$boundary."\n"
            . 'Content-ID: '.$part['id']."\n"
            . 'X-Dio-Method: '.$part['method']."\n"
            . 'X-Dio-Path: '.$part['path'];
    }, $parts)
) . "\n"
. '--'.$boundary.'--';


$headers = 'POST /service/bd/broker/1.0/rest/ HTTP/1.1
Host: www.maklerinfo.biz
X-Dio-Otp: '.$otp.'
Content-Type: multipart/related; boundary="'.$boundary.'"; start="'.$start.'"
Content-Length: '.strlen($body).'
User-Agent: Dionera HttpClient 1.0
Connection: close';

$content = $headers
    ."\r\n\r\n"
    .$body;

$fp = fsockopen('tls://www.maklerinfo.biz',443);
fwrite($fp, $content);
$response = stream_get_contents($fp);

VermittlerWebservice

Allgemein

Platzhalter

HTTP-Header

Basis URL

Authentifizierung

Funktionen

Kundenverwaltung

Vertragsverwaltung

Archivierung

Vermittler-Informationen

Vermittler-Untervermittler anlegen

Vermittler-Untervermittler bearbeiten

Listen

Fehlerbehandlung

Beispiel

Error-Codes bei der Authentifizierung

Datentypen

SimpleTypes

EnumerationItem

Kundenverwaltung

Vertragsverwaltung

Archivierung

Mime-Types

MultiCall

Beispiel