Skip to content

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

Kundenverwaltung

VermittlerWebservice - Kundenverwaltung

Vertragsverwaltung

VermittlerWebservice - Vertragsverwaltung

Archivierung

VermittlerWebservice - Archivierung

Vermittler-Informationen

VermittlerWebservice - Vermittler-Informationen

Vermittler-Untervermittler anlegen

VermittlerWebservice - Vermittler-Untervermittler anlegen

Vermittler-Untervermittler bearbeiten

VermittlerWebservice - Vermittler-Untervermittler bearbeiten

Listen

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

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);