Zusatz-Webservice – Untervermittler – Mr-Money Schnittstellen

Alle Beispiele setzen die Hilfsfunktion curlSend() und den Aufbau aus den Grundlagen voraus.

Methode	Zweck
`find`	Untervermittler selektieren und als Liste ausgeben
`insert`	Neue Untervermittler anlegen
`update`	Bestehende Datensätze aktualisieren
`delete`	Datensätze löschen
`listCompanies`	Gesellschaften auflisten, für die Vermittlernummern hinterlegt werden können

Referenzierung immer über pk
Der Primärschlüssel pk wird von der Datenbank vergeben und kann nicht geändert werden. update und delete arbeiten ausschließlich damit. Sie erhalten ihn beim insert oder über find.

Die Datenfelder

Diese Felder stehen zur Verfügung. Bei find können Sie über jedes davon selektieren, bei insert und update jedes davon setzen (Ausnahmen sind vermerkt).

Name	Typ	Länge	Erklärung
`pk`	int	11	Primärschlüssel, wird von der Datenbank gesetzt und kann nicht geändert werden
`Name1`	varchar	45	Namensfeld 1
`Name2`	varchar	45	Namensfeld 2
`Strasse`	varchar	35	Straße inkl. Hausnummer
`PLZ`	varchar	5	Postleitzahl
`Ort`	varchar	45	Ort
`Tel`	varchar	30	Telefonnummer Festnetz
`Handy`	varchar	20	Telefonnummer Mobil
`Fax`	varchar	30	Fax-Nummer
`email`	varchar	45	E-Mail-Adresse
`Homepage`	varchar	60	URL der Homepage
`MaklerID`	varchar	15	Vermittlernummer des übergeordneten Maklers
`v_id`	varchar	15	ID des Vermittlers – zusammen mit `pw_part` die Anmeldedaten
`pw_part`	varchar	10	Passwort des Vermittlers
`StNr`	varchar	20	Steuernummer
`Handelsregister`	varchar	32	Welches Handelsregister ist zuständig?
`Registernummer`	varchar	32	Registernummer des Vermittlers bei der BaFin
`Geschaeftsfuehrer`	varchar	32	Geschäftsführer
`Status_Re`	varchar	10	Rechner gebucht: `ja` oder `nein`
`Vermittlernummern`	text	–	JSON-Objekt mit den Vermittlernummern, nach Gesellschaft geschlüsselt – siehe Hinweis unten
`Vermittlerstatus`	varchar	30	Status des Vermittlers: `Makler` oder `Mehrfachagent`
`config`	text	–	JSON-Objekt mit Konfigurationsoptionen
`master`	varchar	30	Verbindung zum Master-Account – dieses Feld wird von Mr-Money gesetzt
`Status_AntragInaktiv`	int	2	Antrag deaktiviert: `0` oder `1`

⚠ Zum Feld Vermittlernummern
Die Liste der verfügbaren Gesellschaften legt der Makler fest. Die Schlüsselung muss mit den im Tarifrechner hinterlegten Bezeichnungen übereinstimmen – andernfalls können die Vermittlernummern nicht zugeordnet werden. Die gültigen Schlüssel liefert listCompanies.

`find` – Untervermittler suchen

Liefert eine Liste Ihrer Untervermittler. Die Auswahl lässt sich über jedes der Datenfelder eingrenzen. Ein leeres Parameter-Array (array()) liefert alle Datensätze.

Request – Selektion nach Nachname

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

Response – zwei Treffer, jeweils komplett

array (
  'response' =>
  array (
    'untervermittler' =>
    array (
      'find' =>
      array (
        0 =>
        array (
          0 =>
          array (
            'pk'                   => '15006',
            'Name1'                => 'Tom',
            'Name2'                => 'Tester',
            'Strasse'              => 'Teststraße 7a',
            'PLZ'                  => '01234',
            'Ort'                  => 'Bielefeld',
            'Tel'                  => '00000-0000001',
            'Handy'                => '0162-00000001',
            'Fax'                  => '00000-0000002',
            'email'                => 'tom.tester@example.de',
            'Homepage'             => 'www.example.de',
            'MaklerID'             => 'test_0815',
            'v_id'                 => 'TT',
            'pw_part'              => '1234567890',
            'StNr'                 => '',
            'Handelsregister'      => '',
            'Registernummer'       => '',
            'Geschaeftsfuehrer'    => '',
            'Status_Re'            => 'ja',
            'Vermittlernummern'    => '{"Gothaer-Versicherung":"00.000","Generali":"000000"}',
            'Vermittlerstatus'     => '',
            'config'               => '',
            'master'               => '',
            'Status_AntragInaktiv' => '0',
          ),
          1 =>
          array (
            'pk'    => '15038',
            'Name1' => 'Theodor',
            'Name2' => 'Tester',
            // ... gleiche Felder
          ),
        ),
      ),
    ),
  ),
)

`insert` – Untervermittler anlegen

Sie können mehrere Untervermittler in einem Aufruf anlegen – ein Parameter-Array pro Datensatz. Besondere Bedeutung haben v_id und pw_part: das sind die Anmeldedaten des Vermittlers.

Request – zwei Untervermittler in einem Aufruf

$UpdateParams = array (
    "dataUser" => array (
        'user' => 'IHREVERMITTLERNUMMER',
        'pass' => '********',
    ),
    "content"  => array (
        'untervermittler' => array (
            'insert' => array (
                array (
                    'Name1'             => 'Tom',
                    'Name2'             => 'Tester',
                    'Strasse'           => 'Teststraße 7b',
                    'PLZ'               => '01234',
                    'Ort'               => 'Bielefeld',
                    'Tel'               => '00000-0000001',
                    'Handy'             => '0162-00000001',
                    'Fax'               => '00000-0000002',
                    'email'             => 'tom.tester@example.de',
                    'Homepage'          => 'www.example.de',
                    'MaklerID'          => 'test_0815',
                    'v_id'              => 'TT1',
                    'pw_part'           => '1234567890',
                    'Vermittlernummern' => '{"Gothaer-Versicherung":"00.000","Generali":"000000","HDI":"00-000-0000000"}',
                ),
                array (
                    'Name1'    => 'Theodor',
                    'Name2'    => 'Tester',
                    'Strasse'  => 'Teststraße 17c',
                    'PLZ'      => '01234',
                    'Ort'      => 'Bielefeld',
                    'email'    => 'theodor.tester@example.de',
                    'MaklerID' => 'test_0815',
                    'v_id'     => 'TT2',
                    'pw_part'  => '1234567890',
                ),
            ),
        ),
    ),
);

Response – die vergebenen Primärschlüssel

array (
  'response' =>
  array (
    'untervermittler' =>
    array (
      'insert' =>
      array (
        0 => array ( 'status' => 'success', 'pk' => '10821' ),
        1 => array ( 'status' => 'success', 'pk' => '10822' ),
      ),
    ),
  ),
)

Über diese Primärschlüssel referenzieren Sie die Datensätze bei späteren update- und delete-Aufrufen.

`update` – Untervermittler ändern

Auch hier können mehrere Datensätze in einem Aufruf geändert werden. Übergeben Sie neben pk nur die Felder, die tatsächlich geändert werden sollen.

Request

$UpdateParams = array (
    "dataUser" => array (
        'user' => 'IHREVERMITTLERNUMMER',
        'pass' => '********',
    ),
    "content"  => array (
        'untervermittler' => array (
            'update' => array (
                array (
                    'pk'      => 10821,
                    'Name1'   => 'Tom',
                    'Name2'   => 'Tester',
                    'Strasse' => 'Teststraße 7b',
                ),
                array (
                    'pk'                => 10822,
                    'Name1'             => 'Theodor',
                    'Name2'             => 'Tester',
                    'Strasse'           => 'Teststraße 129a',
                    'Vermittlernummern' => '{"Gothaer-Versicherung":"00.000","Generali":"000000"}',
                ),
            ),
        ),
    ),
);

Response

array (
  'response' =>
  array (
    'untervermittler' =>
    array (
      'update' =>
      array (
        0 => array ( 'status' => 'success', 'affected' => 0 ),
        1 => array ( 'status' => 'success', 'affected' => 1 ),
      ),
    ),
  ),
)

Zu affected
Beide Vorgänge oben waren erfolgreich. Datensatz 10821 war bereits auf dem übergebenen Stand, deshalb affected => 0. Datensatz 10822 wurde tatsächlich geändert, deshalb affected => 1. affected kann nie größer als 1 werden, da über pk immer genau ein Datensatz referenziert wird.

`delete` – Untervermittler löschen

Mehrere Datensätze gleichzeitig löschbar. Die Selektion erfolgt immer über den Primärschlüssel pk.

Request – drei Datensätze löschen

$UpdateParams = array (
    "dataUser" => array (
        'user' => 'IHREVERMITTLERNUMMER',
        'pass' => '********',
    ),
    "content"  => array (
        'untervermittler' => array (
            'delete' => array (
                array ( 'pk' => 10800 ),
                array ( 'pk' => 10810 ),
                array ( 'pk' => 10831 ),
            ),
        ),
    ),
);

Response

array (
  'response' =>
  array (
    'untervermittler' =>
    array (
      'delete' =>
      array (
        0 => false,     // pk 10800 wurde NICHT gelöscht
        1 => 1,         // pk 10810 gelöscht
        2 => 1,         // pk 10831 gelöscht
      ),
    ),
  ),
)

⚠ delete liefert kein Status-Objekt
Anders als insert und update gibt delete pro Vorgang nur 1 oder false zurück. Der Schnittstellenaufruf oben war insgesamt erfolgreich – trotzdem wurde Vorgang 0 nicht ausgeführt. Das passiert immer dann, wenn auf den Datensatz nicht zugegriffen werden kann. Prüfen Sie daher jeden Vorgang einzeln.

`listCompanies` – Gesellschaften auflisten

Liefert die Gesellschaften, für die beim Untervermittler Vermittlernummern hinterlegt werden können. Als Referenz dient der Array-Key (z.B. AMEX-PT-G) – genau dieser Schlüssel gehört in das JSON des Feldes Vermittlernummern.

Request

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

Response (gekürzt)

array (
  'response' =>
  array (
    'untervermittler' =>
    array (
      'listCompanies' =>
      array (
        0 =>
        array (
          'AIG' =>
          array (
            'Gesell'    => 'AIG',
            'Gesell-sp' => 'HR',
            'Gesell-tn' => '510',
            'Pool'      => '0',
            'Pool-sp'   => 'HR',
            'Pool-tn'   => '510',
          ),
          'AIG_PV24' =>
          array (
            'Gesell'    => 'AIG',
            'Gesell-sp' => 'PHO',
            'Gesell-tn' => '108',
            'Pool'      => 'Photovoltaik24',
            'Pool-sp'   => 'PHO',
            'Pool-tn'   => '108',
          ),
          'AMEX-PT-G' =>
          array (
            'Gesell'    => 'Generali',
            'Gesell-sp' => 'PHV',
            'Gesell-tn' => '364',
            'Pool'      => 'AMEX',
            'Pool-sp'   => 'PHV',
            'Pool-tn'   => '364',
          ),
          // ...
          'VEMA-Würzburger' =>
          array (
            'Gesell'    => 'Wuerzburger',
            'Gesell-sp' => 'HR',
            'Gesell-tn' => '258',
            'Pool'      => 'VEMA',
            'Pool-sp'   => 'HR',
            'Pool-tn'   => '258',
          ),
          'WÜBA-Versicherung' =>
          array (
            'Gesell'    => 'WueBa',
            'Gesell-sp' => 'UNF',
            'Gesell-tn' => '208',
            'Pool'      => '0',
            'Pool-sp'   => 'UNF',
            'Pool-tn'   => '208',
          ),
          'Würzburger-Versicherung' =>
          array (
            'Gesell'    => 'Wuerzburger',
            'Gesell-sp' => 'PHV',
            'Gesell-tn' => '836',
            'Pool'      => '0',
            'Pool-sp'   => 'PHV',
            'Pool-tn'   => '836',
          ),
        ),
      ),
    ),
  ),
)

Feld	Bedeutung
`Gesell`	Kurzname der Versicherungsgesellschaft
`Gesell-sp`	Sparte der Gesellschaft
`Gesell-tn`	Tarifnummer bei der Gesellschaft
`Pool`	Name des Pools bzw. `0`, wenn die Gesellschaft direkt angebunden ist
`Pool-sp`	Sparte innerhalb des Pools
`Pool-tn`	Tarifnummer innerhalb des Pools

Eine Gesellschaft kann mehrfach vorkommen
Im Beispiel oben taucht die AIG zweimal auf: einmal als AIG (Sparte HR, direkt angebunden) und einmal als AIG_PV24 (Sparte PHO über den Pool Photovoltaik24). Ebenso die Würzburger als VEMA-Würzburger und Würzburger-Versicherung. Maßgeblich für die Zuordnung ist immer der Array-Key, nicht der Wert in Gesell.

⚠ Array-Keys zeichengenau übernehmen
Die Schlüssel enthalten teils Umlaute (VEMA-Würzburger, WÜBA-Versicherung), die zugehörigen Gesell-Werte dagegen nicht (Wuerzburger, WueBa). Schreiben Sie den Schlüssel für Vermittlernummern deshalb nie ab, sondern übernehmen Sie ihn direkt aus dem Response – sonst schlägt die Zuordnung fehl.

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

Klasse untervermittler

Die Datenfelder

find – Untervermittler suchen

insert – Untervermittler anlegen

update – Untervermittler ändern

delete – Untervermittler löschen

listCompanies – Gesellschaften auflisten

Klasse `untervermittler`

`find` – Untervermittler suchen

`insert` – Untervermittler anlegen

`update` – Untervermittler ändern

`delete` – Untervermittler löschen

`listCompanies` – Gesellschaften auflisten