Antrags-API

Über diese Dokumentation

Diese Dokumentation teilt sich in zwei Bereiche auf. Ein Bereich ist diese Dokumentations-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 die Endpunkt-URLs und z.B. minimale/maximale Längen von Feldern oder eine Auflistung erlaubter Werte, sowie Feldbeschreibungen.

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

Weiteres Wissenswertes: Allgemeine Informationen

Infos zur Antragsschnittstelle

Jede Antrags-Schnittstelle besitzt mindestens diese drei Funktionen:

• Validierung
• Tarifierung
• Policierung

Neben diesen drei Funktionen kann es noch weitere spartenspezifische Funktionen geben, z.B. zum Abrufen einer Tarifzone bei Hausrat.

Validierung

Die Validierung prüft einen übergebenen JSON-Antrag. Geprüft werden die Feldinhalte sowohl auf minimal/maximal Längen, als auch auf die erlaubten Werte. Außerdem werden Zusammenhänge geprüft. Zum Beispiel darf bei Selbstzahler das Bankkonto weggelassen werden. Ist die Zahlart allerdings SEPA-Lastschrift, muss das Bankkonto angegeben werden. Die Validierung wird auch immer vor der Tarifierung und Policierung durchgeführt.

Tarifierung

Die Tarifierung berechnet auf Grundlage des angegebenen JSON-Antrags die Prämie. Die Tarifierung erfolgt auch bei jeder Policierung. Als Ergebnis der Tarifierung kommt folgendes Objekt zurück.

{
    "zuAbschlaege": 0,
    "nettopraemie": 62.4,
    "bruttopraemieZW": 72.48,
    "versicherungssteuer": 10.08,
    "praemienAbweichung": 0.08
}

zuAbschlaege enthält die Summe aller verwendeten Zu- und Abschläge. nettopraemie enthält die Nettoprämie inkl. Zu- und Abschlägen. bruttopraemieZW enthält die Bruttoprämie lt. Zahlweise. inkl. aller Zu- und Abschläge und Vers.-Steuer. versicherungssteuer enthält den Vers.-Steuer Betrag. praemienAbweichung enthält die Differenz zur im Antrag genannten Referenzprämie. Die Referenzprämie soll der hier zurückgegebenen bruttopraemieZW entsprechen.

Policierung

Die Policierung nimmt den JSON-Antrag an und speichert diesen bei der NV.

Aufbau der JSON-Anträge

Jedes Antragsdokument hat spartenübergreifend den gleichen Aufbau. Ein Antrag 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": "Iban",
    "privEmail": "tahrends@nv-online.de",
    "privFax": null,
    "privHandy": null,
    "privTelefon": null,
    "vorname": "Bic"
}

Feld null setzen oder weg lassen?

Felder, die in den Beispielen mit null belegt sind, sind grundsätzlich optional und können auch komplett weggelassen werden. Felder mit null-Werten sind also gleichzustellen mit weggelassenen Feldern. Eine leere Zeichenfolge ist allerdings nicht null gleichzustellen und führt zu Validierungsfehlern!

Vertrag

Das Vertrag-Element enthält alle Informationen zum zukünftigen Vertrag. Es gliedert sich in einen allgemeinen spartenübergreifenden Teil und in einen spartenspezifischen Teil. Der Allgemein Teil enthält Informationen wie den Vertragsbeginn, Laufzeit und Zahlungsweise.

"vertrag": {
    "allgemein": {
        "beginnDatum": "01.01.2020",
        "fremdvertragsNummer": null,
        "inkassoart": "Selbst",
        "laufzeit": 3,
        "produktVariante": "Spar",
        "referenzPraemie": 72.56,
        "zahlungsweise": "jaehrlich"
    },
    "[Sparte]": {
        ...
    }
}

Die Referenzprämie ist die vom API-Nutzer selbst berechnete Bruttoprämie lt. Zahlweise. Weicht diese von der Prämie ab, die von der NV berechnet wurde, wird im Prämien-Objekt der Antwort eine Prämienabweichung ungleich 0.00 ausgewiesen.

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"
    },
    "vorschaeden": {
        "anzahl": 0,
        "hoehe": 0.00
    },
    "notiz": "Dies ist eine Notiz.",
    "vermittlernummer": 12345,
    "werbeeinwilligungBrief": "nein",
    "werbeeinwilligungEmail": "ja",
    "werbeeinwilligungTelefon": "nein",
    "emailKommunikation": "ja",
    "emailBestaetigt": "nein",
    "antragsPdf": "[Base64 kodierte PDF]"
}

Vermittlernummern

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.

Kein Vorversicherer

Gibt es keine Angabe zum Vorversicherer, so ist das Feld vorversicherer weg zu lassen oder null zu setzen.

Feld Antrags-PDF

Über das Feld antragsPDF besteht die Möglichkeit einen PDF-Antrag mitzuschicken. Dieses muss in Base64 kodiert und als String übertragen werden.

Spartenspezifische Beschreibungen

📕 Hausratversicherung
📕 Haus- und Grundbesitzer Haftpflicht
📕 Hundehalterhaftpflicht
📕 Pferdehalterhaftpflicht
📕 Privathaftpflicht
📕 Unfallversicherung
📕 Wohngebäudeversicherung