Zusatz-Webservice – Grundlagen – Mr-Money Schnittstellen

Endpunkt

Es gibt genau einen Endpunkt für alle Klassen und Methoden. Die gewünschte Funktion wird nicht über die URL, sondern über die Struktur des JSON-Dokuments im Request-Body bestimmt.

POST https://api.versicherungsmaklersoftware.de/

Eigenschaft	Wert
Methode	`POST`
Content-Type	`application/json;charset="utf-8"`
Accept	`application/json`
Body	JSON-Dokument mit den Sektionen `dataUser` und `content`

Aufbau des Requests

Das JSON-Dokument besteht aus zwei Sektionen auf oberster Ebene:

Sektion	Inhalt
`dataUser`	Die Zugangsdaten. Enthält `user` (Ihre Vermittlernummer) und `pass` (Ihr Passwort).
`content`	Die eigentliche Nutzlast als verschachteltes Array: `klasse` → `methode` → Liste von Parameter-Arrays.

Die vier Ebenen von `content`

Schema

"content" => array (
    'klassenname' => array (        // 1. Ebene: welche Klasse?
        'methodenname' => array (   // 2. Ebene: welche Methode?
            array ( ... ),          // 3. Ebene: 1. Aufruf mit seinen Parametern
            array ( ... ),          //           2. Aufruf mit anderen Parametern
        ),
    ),
)

Warum die dritte Array-Ebene?
Sie kapselt die Parameter eines einzelnen Aufrufs. Dadurch können Sie dieselbe Methode mehrfach in einem Request ausführen – z.B. fünf Untervermittler mit einem Aufruf anlegen. Auch bei Methoden ohne Parameter muss diese Ebene vorhanden sein, dann als leeres Array: array( array() ).

Klassen und Methoden lassen sich beliebig kombinieren. Nicht steuerbar ist die Reihenfolge der Abarbeitung – sie ergibt sich aus der Array-Struktur. Wenn ein Ergebnis von einem vorherigen Schritt abhängt, setzen Sie dafür zwei getrennte Requests ab.

Aufbau des Response

Der Response spiegelt exakt die Struktur des Requests wider, eingebettet in einen Schlüssel response. Der Index in der dritten Ebene entspricht dem Index Ihres Aufrufs im Request:

Schema

$data['response']['klassenname']['methodenname'][0]   // Ergebnis des 1. Aufrufs
$data['response']['klassenname']['methodenname'][1]   // Ergebnis des 2. Aufrufs

Bei Methoden, die eine Liste liefern (z.B. find, fetchList), folgt darunter noch eine weitere Ebene mit den einzelnen Datensätzen: [0][0], [0][1] und so fort.

⚠ Klassennamen im Response sind kleingeschrieben
Auch wenn Sie im Request 'Untervermittler' schreiben, kommt der Schlüssel im Response als 'untervermittler' zurück. Verwenden Sie am besten durchgehend Kleinschreibung.

Fehlerbehandlung

⚠ Fehler kommen nicht als HTTP-Status
Ein fachlicher Fehler führt in aller Regel trotzdem zu HTTP 200. Prüfen Sie deshalb immer das Ergebnis des einzelnen Aufrufs, nicht nur den HTTP-Code.

Je nach Methode signalisiert der Response einen Fehler unterschiedlich:

Signal	Bedeutung
`error`-Schlüssel	Enthält eine Klartext-Fehlermeldung, z.B. „Es konnte kein Eintrag mit der Nummer 89472 gefunden werden."
`status` => `success`	Bei schreibenden Methoden (`insert`, `update`, `setGewaehlterTarif`) das Zeichen für einen erfolgreichen Vorgang
`notice` => `notFound`	Der Datensatz existiert nicht – kein Fehler, aber auch kein Ergebnis (z.B. bei `getTextAbout`)
`false` statt Array	Bei `delete`: Der Datensatz konnte nicht gelöscht werden, weil kein Zugriff darauf besteht

PHP – Ergebnis eines Aufrufs robust auswerten

<?php
$data = json_decode( $response, true );

if ( ! is_array( $data ) || ! isset( $data['response'] ) ) {
    // Ungueltige Antwort - z.B. HTML-Fehlerseite statt JSON
    return false;
}

$ergebnis = $data['response']['antrag']['fetchAntrag'][0];

if ( isset( $ergebnis['error'] ) ) {
    // Fachlicher Fehler mit Klartextmeldung
    echo 'Fehler: ' . $ergebnis['error'];
    return false;
}

// Ergebnis verwenden
?>

Rate Limits

Die Schnittstelle hat einige Begrenzungen, um eine Überlastung des Systems zu verhindern.

⚠ 10 Anfragen pro Sekunde
Das ist das Standard-Limit. Benötigen Sie mehr, wenden Sie sich an Mr-Money – Sie werden dann in die Whitelist aufgenommen und erhalten ein individuelles Limit.

Beachten Sie: Da sich mehrere Aufrufe in einem Request bündeln lassen, lässt sich das Limit in der Praxis meist gut einhalten. Statt 50 Untervermittler einzeln anzulegen, senden Sie ein insert mit 50 Parameter-Arrays.

Die Hilfsfunktion `curlSend()`

Diese Funktion wird auf allen folgenden Seiten als vorhanden vorausgesetzt. Sie kapselt den cURL-Aufruf und gibt die rohe Antwort des Servers zurück.

PHP – Vollständiger Aufruf inkl. curlSend()

<?php
header( "Content-Type: text/plain; charset=UTF-8" );

$UpdateParams = array (
    "dataUser" => array (
        'user' => 'IHREVERMITTLERNUMMER',
        'pass' => '********',
    ),
    "content"  => array (
        'untervermittler' => array (
            'find' => array (
                array (),
            ),
        ),
    ),
);

$url = 'https://api.versicherungsmaklersoftware.de/';

$response = curlSend( json_encode( $UpdateParams ), $url );
$data     = json_decode( $response, true );

var_export( $data );


function curlSend( $content, $url )
{
    $headers = array (
        "POST " . dirname( parse_url( $url, PHP_URL_PATH ) ) . " HTTP/1.0",
        "Content-type: application/json;charset=\"utf-8\"",
        "Accept: application/json",
        "Cache-Control: no-cache",
        "Pragma: no-cache",
        "Content-length: " . strlen( $content ),
    );

    $ch = curl_init();
    curl_setopt( $ch, CURLOPT_URL,            $url );
    curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
    curl_setopt( $ch, CURLOPT_TIMEOUT,        60 );
    curl_setopt( $ch, CURLOPT_HTTPHEADER,     $headers );
    curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, false );
    curl_setopt( $ch, CURLOPT_SSL_VERIFYHOST, 2 );
    curl_setopt( $ch, CURLOPT_POST,           1 );
    curl_setopt( $ch, CURLOPT_POSTFIELDS,     $content );

    $data = curl_exec( $ch );

    if ( curl_errno( $ch ) ) {
        print "Error: " . curl_error( $ch );

        return 'Fail';
    }

    curl_close( $ch );

    return $data;
}
?>

Hinweis zur Zeichenkodierung
Der Webservice arbeitet mit UTF-8 – anders als der Vergleichsrechner, der ISO-8859-1 erwartet. Wenn Ihre Anwendung in ISO-8859-1 läuft, wandeln Sie die Werte vor json_encode() um (utf8_encode() bzw. iconv()) und die Ergebnisse nach dem Dekodieren wieder zurück. json_encode() liefert sonst false, sobald ein Umlaut im Datensatz steht.

Mehrere Aktionen in einem Request

Im folgenden Beispiel wird ein Untervermittler angelegt, zwei weitere werden geändert und anschließend wird die gesamte Liste abgerufen – alles in einem einzigen Aufruf.

PHP – Request mit drei Aktionen

$UpdateParams = array (
    "dataUser" => array (
        'user' => 'IHREVERMITTLERNUMMER',
        'pass' => '********',
    ),
    "content"  => array (
        'untervermittler' => array (
            'insert' => array (
                array (
                    'Name1'    => 'Tamara',
                    'Name2'    => 'Tester',
                    'Strasse'  => 'Teststraße 76e',
                    'PLZ'      => '01234',
                    'Ort'      => 'Bielefeld',
                    'email'    => 'tamara.tester@example.de',
                    'MaklerID' => 'test_0815',
                    'v_id'     => 'TT7',
                    'pw_part'  => '1234567890',
                ),
            ),
            'update' => array (
                array (
                    'pk'      => 10821,
                    'Name1'   => 'Tom',
                    'Strasse' => 'Teststraße 7b',
                ),
                array (
                    'pk'      => 10822,
                    'Name1'   => 'Theodor',
                    'Strasse' => 'Teststraße 129a',
                ),
            ),
            'find' => array (
                array (),
            ),
        ),
    ),
);

Response – gleiche Struktur, gleiche Indizes

array (
  'response' =>
  array (
    'untervermittler' =>
    array (
      'insert' =>
      array (
        0 => array ( 'status' => 'success', 'pk' => '10821' ),
      ),
      'update' =>
      array (
        0 => array ( 'status' => 'success', 'affected' => 0 ),
        1 => array ( 'status' => 'success', 'affected' => 1 ),
      ),
      'find' =>
      array (
        0 =>
        array (
          0 => array ( 'pk' => '15006', 'Name1' => 'Tom', /* ... */ ),
          1 => array ( 'pk' => '15038', 'Name1' => 'Theodor', /* ... */ ),
        ),
      ),
    ),
  ),
)

affected => 0 bedeutet dabei nicht „fehlgeschlagen", sondern „der Datensatz war bereits auf diesem Stand".

✉ Feedback
Fehler oder Unstimmigkeit in dieser Doku entdeckt? Schreiben Sie uns: ts@mr-money.de

Grundlagen: Request & Response