Bestands-API

Über diese Dokumentation

Diese Dokumentation teilt sich in zwei Bereiche auf. Ein Bereich ist diese Dokumentaions-Webseite. Sie enthält einen Überlick der WebApi und versucht die WebApi zu erklären und Besonderheiten einzelner Sparten zu beschreiben.

Der andere Bereich sind die technischeren (Swagger / OpenAPI) API-Dokumentations-Seiten der einzelnen Services. Sie enthalten detaillierte Informationen zur Übertragung, wie z.B. minimale/maximale Längen von Feldern oder eine Auflistung erlaubter Werte, sowie Feldbeschreibungen.

Da für den Zugriff auf Client-Zertifikat benötigt wird, ist die Swagger JSON hier nochmal verlinkt: OpenAPI 2.0 JSON Definition

Weiteres Wissenswertes:
Allgemeine Informationen
Fragen und Antworten

Infos zur Bestandsschnittstelle

dient zum Anlegen und Änderung von Verträgen durch Assekuradeure. Sie besitzt ein komplexeres Datenmodell als die Antragsschnittstelle, um unterschiedliche Produkte, ohne Anpassungen an der WebApi, bedienen zu können. Das Datenmodell ist in seinen Grundzügen über alle Sparten gleich. Je nach Sparte stehen allerdings unterschiedliche Felder zur Verfügung.

Jede Bestands-Schnittstelle besitzt mindestens diese drei Funktionen:

• Anlage
• Aenderung
• Storno

Anlage

Die Anlage-Funktion legt einen Antrag im Bestandssystem der NV an. Der Nutzer erhält nach erfolgreicher Anlage eine Antragsnr., sowie die Kunden-, Policen- und Vertragsnummer zurück. Die Policen- und Vertragsnummer muss vom Nutzer gespeichert werden, um für spätere Änderungen den Vertrag wieder addressieren zu können.

Änderung

Die Änderung-Funktion ermöglicht es einen angelegten Vertrag zu ändern. Das zu übertragende JSON-Objekt ist in seinem Aufbau genauso wie das Objekt für die Anlage. Der zu ändernde Vertrag wird über die URL adressiert. z.B. /bestand/hausrat/1.0/api/aenderung/1234567890/1

Storno

Wie der Name sagt, storniert diese Funktion einen Vertrag. Die Funktion ist für alle Sparten identisch. Die Angabe des Vertrages erfolgt wieder über die URL z.B. /bestand/hausrat/1.0/api/storno/1234567890/1. Im Request-Body wird bei dieser Funktion nur ein Storno-Objekt erwartet.

Aufbau der Neu/Änderung-JSON-Objekte

Jedes Objekt hat spartenübergreifend den gleichen Aufbau. Ein Objekt besteht grundsätzlich aus drei Elementen.

• Versicherungsnehmer
• Vertrag
• Metadaten

Versicherungsnehmer

Das Versicherungsnehmer-Element enthält alle Informationen zum Versicherungsnehmer.

"versicherungsnehmer": {
    "akadTitel": "Dr.",
    "anrede": "Herr",
    "anschrift": {
        "hausnummer": "1",
        "ort": "Neuharlingersiel",
        "plz": "26425",
        "postfach": null,
        "postfachPlz": null,
        "strasse": "Ostfriesenstr."
    },
    "beschaeftigungsart": "Angestellte/r",
    "faEmail": null,
    "faFax": null,
    "faHandy": null,
    "faTelefon": null,
    "geburtsdatum": "24.09.1988",
    "name": "Muster",
    "privEmail": "muster@nv-online.de",
    "privFax": null,
    "privHandy": null,
    "privTelefon": null,
    "vorname": "Max",
    "fremdKundennummer": "18571jd",
    "versandweg": "E-Mail",
    "bestaetigteEmail": "muster@nv-online.de",
    "bestaetigteEmailUhrzeit": "01.03.2025 08:45:23"
}

Vertrag

Das Vertrag-Element enthält alle Informationen zum Vertrag. Die Struktur ist spartenübergreifend gleich, Unterschiede gibt es nur in den zur Verfügung stehenden Feldern.

"vertrag": 
{
    "produktTyp": "HAU HausratPremium 6.0",
    "zahlungsweise": "monatlich",
    "beginnDatum": "01.01.2020",
    "ablaufdatum": "01.01.2023",
    "fremdvertragsNummer": "12GIO549",
    "notiz": null,
    "bankkonto": {
        "iban": "DE12345.....",
        "inhaber": "Max Mustermann"
    },
    "objekte": [
        {
            "objektTyp": "HAU Hausrat",
            "wohnflaeche": 120,
            "risiken": [
                {
                    "nettoOhneZuAbschlaege": 50,
                    "risikoTyp": "HAU FEBLSH",
                    "versicherungssumme": 78000
                }
            ],
            "risikoanschrift": {
                "hausnummer": "1",
                "ort": "Neuharlingersiel",
                "plz": "26425",
                "strasse": "Ostfriesenstr."
            }
        }
    ]
},

Metadaten

Das Metadaten-Element enthält Informationen, welche weder zum Versicherungsnehmer, noch direkt zum Vertrag gehören, wie z.B. die Vermittlernummer oder eine Notiz.

"metadaten": {
    "vorversicherung": {
        "gekuendigtDurch": "Kunde",
        "versicherer": "Pfefferminzia",
        "policennummer": "123456789",
        "schadenAnzahl": 0,
        "schadenHoehe": 0
    },
    "standdatum": "01.01.2020",
    "vermittlernummer": 1671,
    "werbeeinwilligung": "nein"
}

Vermittlernummer

Als Vermittlernummer ist die NV-Vermittlernummer anzugeben. Wird mit Untervermittlern zusammengearbeitet, die bei der NV eine eigene Nummer haben, so ist hier die Nummer des Untervermittlers anzugeben.

Storno

Das Storno-Objekt ist für alle Sparten identisch.

{
    "standdatum": "01.06.2020",
    "stornogrund": "999"
}

Eine Liste der Stornogründe befindet sich hier: Liste der Stornogründe

Übermittlung von Buchungsdaten

Buchungsdaten werden nicht über die WebApi übermittelt, sondern gebündelt in einer CSV-Datei.

Der Aufbau der CSV-Datei ist hier beschrieben.

Die CSV-Datei wird monatlich der NV übergeben. Sie wird dafür auf den SFTP-Server (sftp.nv-extra.net) der NV hochgeladen.