API & Einbindung

Die Kündigungshilfe ist für private und gewerbliche Anwender frei verwendbar. So binden Sie den Assistenten in Ihre Website oder Ihr Maklerportal ein.

Überblick

Verlinken

Direkter Einstieg mit vorausgewählter Sparte per GET-Parameter.

Einbetten

IFrame-Layout ohne Kopf/Fuß, mit Farbschema und automatischer Höhe.

Daten übergeben

Kunden-, Vertrags- und Maklerdaten per JSON oder XML vorbefüllen.

Link & GET-Parameter

Alle Parameter werden an die URL des Assistenten angehängt und lassen sich kombinieren:

Beispiel

https://www.kuendigungshilfe.info/Assistent/?sp=rs

Parameter	Beschreibung
`sp=rs`	Sparte vorauswählen (Kürzel siehe Tabelle unten).	ausprobieren
`iframe`	Alternatives Layout ohne Kopf- und Fußbereich für die Einbindung per IFrame. Optional mit Partnernamen als Wert (lädt partnerspezifische Einstellungen und Stylesheets).	ausprobieren
`theme=flatly`	Farbschema im IFrame-Layout (nur zusammen mit `iframe`).	ausprobieren
`partner=name`	Blendet partnerspezifische Vertragsarten ein.
`UID={…}`	Lädt einen über die Import-Schnittstelle angelegten Vorgang (wird im Response als „Link“ geliefert).
`sharePDF=9F3C2A7E51D04B8C6A2E7F1093B5D4C8`	Öffnet einen geteilten Vorgang zur Unterschrift durch einen Dritten.
`ENVIROMENT=name`	Wie `iframe`-Partnername, jedoch ohne IFrame-Layout.

IFrame-Einbindung

Mit dem Parameter iframe wird ein Layout ohne Kopf- und Fußbereich ausgeliefert – als zusätzlicher oder alleiniger Parameter:

https://www.kuendigungshilfe.info/Assistent/?sp=phv&iframe ausprobieren

https://www.kuendigungshilfe.info/Assistent/?iframe ausprobieren

Der Assistent meldet seine Höhe alle 400 ms per postMessage an die einbettende Seite – als Zahl und zusätzlich als JSON {"bodyHeight": …}. So passen Sie die Höhe des IFrames automatisch an:

HTML

<iframe id="kuendigungshilfe" src="https://www.kuendigungshilfe.info/Assistent/?iframe&theme=flatly"
        style="width:100%;border:0;min-height:600px" title="Kündigungshilfe"></iframe>
<script>
  // Der Assistent meldet seine Höhe regelmäßig per postMessage –
  // einmal als Zahl und einmal als JSON {"bodyHeight": …}.
  window.addEventListener('message', function (event) {
    var height = typeof event.data === 'number' ? event.data : null;
    if (height === null) {
      try { height = JSON.parse(event.data).bodyHeight; } catch (e) { return; }
    }
    if (height) document.getElementById('kuendigungshilfe').style.height = height + 'px';
  });
</script>

Sie benötigen ein spezielles Design oder partnerspezifische Einstellungen? Sprechen Sie uns an.

Themes

Im IFrame-Layout kann über den Parameter theme ein Farbschema gewählt werden:

Cerulean theme=cerulean
Cosmo theme=cosmo
Cyborg theme=cyborg
Darkly theme=darkly
Default theme=default
Flatly theme=flatly
Journal theme=journal
Lumen theme=lumen
Paper theme=paper
Readable theme=readable
Sandstone theme=sandstone
Simplex theme=simplex
Slate theme=slate
Spacelab theme=spacelab
Superhero theme=superhero
United theme=united
Yeti theme=yeti

Import-Schnittstelle

Über die Import-Schnittstelle übergeben Sie Kunden-, Vertragspartner- und Vertragsdaten. Im Body des POST-Requests wird ein JSON-Objekt (UTF-8) oder XML-Dokument mitgesendet. Die Antwort enthält die UID und den Link zum Aufruf des vorbefüllten Assistenten – hängen Sie gerne &iframe an.

Import-URL (POST)

https://www.kuendigungshilfe.info/Import

Wichtig: Vor der Benutzung muss Ihre IP-Adresse von uns freigegeben werden. Freigabe anfragen

Request (JSON)

JSON

{
    "returnPathPDF": null,
    "Anschrift_Kunde": {
        "Vorname": "Testi",
        "Name": "Test",
        "Zusatz": "c/o Test Max",
        "Strasse": "Teststrasse 11",
        "PLZ": "01234",
        "Ort": "Musterhausen",
        "email": null
    },
    "Anschrift_Kunde_neu": {
        "Vorname": "Testa",
        "Name": "Test",
        "Strasse": "Testgasse 23",
        "PLZ": "12340",
        "Ort": "Musterstadt"
    },
    "Anschrift_Gesellschaft": {
        "Firma": "Debeka",
        "Strasse": "Test",
        "PLZ": "01234",
        "Ort": "Muster",
        "fax": "4567890",
        "email": "vertraege@pfefferminzia.de"
    },
    "Anschrift_Makler": {
        "Vorname": "Makler",
        "Name": "Bieber",
        "Strasse": "Holzgasse 11",
        "PLZ": "01234",
        "Ort": "Baumhausen",
        "email": "makler@baum.de"
    },
    "partner": "",
    "Sparte": "HR",
    "Sparte_ID": null,
    "Vertragsnummer": "Test 08/15",
    "Ablaufdatum": "22.03.2017",
    "mitteilen": "Kündigung",
    "AenderungAdresse": false
}

Sparte – Kürzel der Sparte (siehe Tabelle), alternativ Sparte_ID. Unbekannte Sparten werden als „allgemeiner Vertrag“ behandelt.
Ablaufdatum – wählt automatisch „Kündigung zum Ablauf“ mit diesem Datum.
mitteilen – Kündigung, Vertragsänderung oder Widerruf vorauswählen.
AenderungAdresse – wählt die Adressänderung vor (Anschrift_Kunde_neu erforderlich).
Anschrift_Makler – optional; ermöglicht das Schreiben im Auftrag des Kunden.
partner – optional für partnerspezifische Einstellungen.

Response (JSON)

Der Parameter success zeigt, ob der Request verarbeitet wurde. Autofill gibt an, ob die Anschrift des Vertragspartners anhand des Namens automatisch ermittelt wurde. Die importierten Daten finden Sie zur Kontrolle unter import.

JSON

{
    "success": true,
    "data": {
        "UID": "{AEA8A0B5-24AB-00DA-3FFE-A3E551EFC2A3}",
        "Link": "https://www.kuendigungshilfe.info/Assistent/?UID={AEA8A0B5-24AB-00DA-3FFE-A3E551EFC2A3}",
        "Autofill": true,
        "import": {
            "Anschrift_Kunde": { "Vorname": "Testi", "Name": "Test", "...": "..." },
            "Anschrift_Gesellschaft": {
                "id": "80",
                "Firma": "Debeka Allgemeine Versicherung Aktiengesellschaft",
                "Strasse": "Ferdinand-Sauerbruch-Str. 18",
                "PLZ": "56058",
                "Ort": "Koblenz",
                "fax": null,
                "email": "..."
            },
            "Sparte": "HR",
            "Sparte_ID": "8",
            "Vertragsnummer": "Test 08/15",
            "Ablaufdatum": "22.03.2017"
        }
    }
}

Request & Response (XML)

Die Schnittstelle versteht dieselben Felder auch als XML mit dem Wurzelelement <import>. Die Antwort erfolgt dann ebenfalls als XML.

XML-Request

<?xml version="1.0" encoding="utf-8"?>
<import>
  <!--optionale URL welche bei Erstellung des PDF aufgerufen wird-->
  <returnPathPDF/>
  <!--Anschrift des Kunden-->
  <Anschrift_Kunde>
    <Vorname>Testi</Vorname>
    <Name>Test</Name>
    <Zusatz>c/o Test Max</Zusatz>
    <Strasse>Teststrasse 11</Strasse>
    <PLZ>01234</PLZ>
    <Ort>Musterhausen</Ort>
    <email/>
  </Anschrift_Kunde>
  <!--bei AenderungAdresse=true erforderlich-->
  <Anschrift_Kunde_neu>
    <Vorname>Testa</Vorname>
    <Name>Test</Name>
    <Strasse>Testgasse 23</Strasse>
    <PLZ>12340</PLZ>
    <Ort>Musterstadt</Ort>
  </Anschrift_Kunde_neu>
  <!--Anschrift des Vertragspartners-->
  <Anschrift_Gesellschaft>
    <Firma>Debeka</Firma>
    <Strasse>Test</Strasse>
    <PLZ>01234</PLZ>
    <Ort>Muster</Ort>
    <fax>4567890</fax>
    <email>vertraege@pfefferminzia.de</email>
  </Anschrift_Gesellschaft>
  <!--Sparte-->
  <Sparte>HR</Sparte>
  <!--Alternativ Sparten ID-->
  <Sparte_ID/>
  <Vertragsnummer>Test 08/15</Vertragsnummer>
  <!--Wenn Ablaufdatum gesetzt wird, wird automatisch die Kündigung zum Ablauf gewählt-->
  <Ablaufdatum>22.03.2017</Ablaufdatum>
  <!--Kündigung|Vertragsänderung|Widerruf-->
  <mitteilen>Widerruf</mitteilen>
  <!--Wenn eine Adressänderung vorausgewählt werden soll-->
  <AenderungAdresse>1</AenderungAdresse>
</import>

XML-Response

<?xml version="1.0" encoding="utf-8"?>
<import>
  <success>1</success>
  <data>
    <UID>{138A90E1-B6EE-CCE7-B68A-7848C74B3FD1}</UID>
    <Link>https://www.kuendigungshilfe.info/Assistent/?UID={138A90E1-B6EE-CCE7-B68A-7848C74B3FD1}</Link>
    <Autofill>1</Autofill>
    <import>
      <returnPathPDF/>
      <Anschrift_Kunde>…</Anschrift_Kunde>
      <Anschrift_Gesellschaft>
        <id>80</id>
        <Firma>Debeka Allgemeine Versicherung Aktiengesellschaft</Firma>
        <Strasse>Ferdinand-Sauerbruch-Str. 18</Strasse>
        <PLZ>56058</PLZ>
        <Ort>Koblenz</Ort>
        <fax/>
      </Anschrift_Gesellschaft>
      <Sparte>HR</Sparte>
      <Sparte_ID>8</Sparte_ID>
      <Vertragsnummer>Test 08/15</Vertragsnummer>
      <Ablaufdatum>22.03.2017</Ablaufdatum>
      <mitteilen>Widerruf</mitteilen>
      <AenderungAdresse>1</AenderungAdresse>
    </import>
  </data>
</import>

Erzeugtes Dokument zurückliefern – `returnPathPDF`

Wenn Sie im Import eine URL unter returnPathPDF angeben, wird jedes erzeugte Dokument als JSON-POST mit folgender Struktur an diese URL geschickt:

JSON

{
   "success": true,
   "response": {
      "filename": "dateiname.pdf",
      "filesize": 123456,
      "file": "BASE64…",
      "data": {
            … Daten des Vorgangs …
      }
   }
}

Sparten-Kürzel

Für den GET-Parameter sp und das Import-Feld Sparte (Groß-/Kleinschreibung egal):

Kürzel	Vertragsart
`BU`	Berufsunfähigkeitsversicherung	öffnen
`GLS`	Glas	öffnen
`HR`	Hausrat	öffnen
`KFZ`	KFZ	öffnen
`LV`	Lebensversicherung	öffnen
`PKV`	Private Krankenversicherung	öffnen
`PHV`	Privathaftpflicht	öffnen
`RS`	Rechtsschutz	öffnen
`RV`	Rentenversicherung	öffnen
`RLV`	Risiko-Lebensversicherung	öffnen
`SON`	Sonstige Versicherung	öffnen
`TIE`	Tierhalter (Hund/Pferd)	öffnen
`UNF`	Unfall	öffnen
`WG`	Wohngebäude	öffnen
`BAU`	Bausparvertrag	öffnen
`FITVertr`	Fitnessvertrag	öffnen
`GAS`	Gasvertrag	öffnen
`MV`	Maklervertrag	öffnen
`MIETVertr`	Mietvertrag	öffnen
`MOBVetr`	Mobilfunkvertrag	öffnen
`STROM`	Stromvertrag	öffnen
`ZTGAbo`	Zeitungsabo	öffnen
`ALLGVertr`	allgemeiner Vertrag	öffnen

PHP-Beispiele

Komplette, lauffähige Beispielskripte für die Import-Schnittstelle:

PHP · JSON

<?php
class Test {
    /**
     *
     */
    public function start()
    {
        $json = array(
            'returnPathPDF' => null, //optionale URL welche bei erstellung des PDF aufgerufen wird
            'Anschrift_Kunde' => array( //Anschrift des Kunden
                'Vorname' => 'Testi',
                'Name' => 'Test',
                'Zusatz' => 'c/o Test Max',
                'Strasse' => 'Teststrasse 11',
                'PLZ' => '01234',
                'Ort' => 'Musterhausen',
                'email' => null,
            ),
            /*bei AenderungAdresse=true erforderlich*/
            'Anschrift_Kunde_neu' => array( //Neue Anschrift des Kunden
                'Vorname' => 'Testa',
                'Name' => 'Test',
                'Strasse' => 'Testgasse 23',
                'PLZ' => '12340',
                'Ort' => 'Musterstadt',
            ),
            'Anschrift_Gesellschaft' => array( //Anschrift des Vertragspartners
                'Firma' => 'Debeka',
                'Strasse' => 'Test',
                'PLZ' => '01234',
                'Ort' => 'Muster',
                'fax' => '4567890',
                'email' => 'vertraege@pfefferminzia.de',
            ),
            'Sparte' => 'HR', //Sparte:
            'Sparte_ID' => null, //Alternativ Sparten ID
            'Vertragsnummer' => 'Test 08/15',
            'Ablaufdatum' => '22.03.2017', //Wenn Ablaufdatum gesetzt wird, wird automatisch die Kündigung zum nächst mgl. Zeitpunkt gewählt
            //'mitteilen' => 'Widerruf', //Kündigung|Vertragsänderung|Widerruf
            //'AenderungAdresse' => true,
        );
        echo '<pre>';
        print_r(json_decode($this->execCurl(json_encode($json), 'https://www.kuendigungshilfe.info/Import')));
        echo '</pre>';
        exit;
    }

    /**
     * @param string $content
     * @param string $url
     * @return mixed
     */
    private function execCurl($content, $url)
    {

        $headers = array(
            "POST " . basename($url) . " HTTP/1.0",
            "Content-type: application/json;charset=\"utf-8\"",
            "Accept: application/json",
            "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_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $content);

        $data = curl_exec($ch);

        if (curl_errno($ch)) {
            return curl_error($ch);
        } else {
            curl_close($ch);
            return $data;
        }
    }
}

$Test = new Test();
$Test->start();

PHP · XML

<?php
class Test {
    /**
     *
     */
    public function start()
    {
        $doc = new \DOMDocument('1.0', 'utf-8');
        $doc->formatOutput = true;
        $doc->preserveWhiteSpace = true;
        $import = $doc->createElement('import');
        $import->appendChild($doc->createComment('optionale URL welche bei Erstellung des PDF aufgerufen wird'));
        $import->appendChild($doc->createElement('returnPathPDF'));

        $import->appendChild($doc->createComment('Anschrift des Kunden'));
        $Anschrift_Kunde = $doc->createElement('Anschrift_Kunde');
        $Anschrift_Kunde->appendChild($doc->createElement('Vorname', 'Testi'));
        $Anschrift_Kunde->appendChild($doc->createElement('Name', 'Test'));
        $Anschrift_Kunde->appendChild($doc->createElement('Zusatz', 'c/o Test Max'));
        $Anschrift_Kunde->appendChild($doc->createElement('Strasse', 'Teststrasse 11'));
        $Anschrift_Kunde->appendChild($doc->createElement('PLZ', '01234'));
        $Anschrift_Kunde->appendChild($doc->createElement('Ort', 'Musterhausen'));
        $Anschrift_Kunde->appendChild($doc->createElement('email'));
        $import->appendChild($Anschrift_Kunde);

        $import->appendChild($doc->createComment('bei AenderungAdresse=true erforderlich'));
        $Anschrift_Kunde_neu = $doc->createElement('Anschrift_Kunde_neu');
        $Anschrift_Kunde_neu->appendChild($doc->createElement('Vorname', 'Testa'));
        $Anschrift_Kunde_neu->appendChild($doc->createElement('Name', 'Test'));
        $Anschrift_Kunde_neu->appendChild($doc->createElement('Strasse', 'Testgasse 23'));
        $Anschrift_Kunde_neu->appendChild($doc->createElement('PLZ', '12340'));
        $Anschrift_Kunde_neu->appendChild($doc->createElement('Ort', 'Musterstadt'));
        $import->appendChild($Anschrift_Kunde_neu);

        $import->appendChild($doc->createComment('Anschrift des Vertragspartners'));
        $Anschrift_Gesellschaft = $doc->createElement('Anschrift_Gesellschaft');
        $Anschrift_Gesellschaft->appendChild($doc->createElement('Firma', 'Debeka'));
        $Anschrift_Gesellschaft->appendChild($doc->createElement('Strasse', 'Test'));
        $Anschrift_Gesellschaft->appendChild($doc->createElement('PLZ', '01234'));
        $Anschrift_Gesellschaft->appendChild($doc->createElement('Ort', 'Muster'));
        $Anschrift_Gesellschaft->appendChild($doc->createElement('fax', '4567890'));
        $Anschrift_Gesellschaft->appendChild($doc->createElement('email', 'vertraege@pfefferminzia.de'));
        $import->appendChild($Anschrift_Gesellschaft);

        $import->appendChild($doc->createComment('Sparte'));
        $import->appendChild($doc->createElement('Sparte', 'HR'));

        $import->appendChild($doc->createComment('Alternativ Sparten ID'));
        $import->appendChild($doc->createElement('Sparte_ID'));

        $import->appendChild($doc->createElement('Vertragsnummer', 'Test 08/15'));

        $import->appendChild($doc->createComment('Wenn Ablaufdatum gesetzt wird, wird automatisch die Kündigung zum nächst mgl. Zeitpunkt gewählt'));
        $import->appendChild($doc->createElement('Ablaufdatum', '22.03.2017'));

        $import->appendChild($doc->createComment('Kündigung|Vertragsänderung|Widerruf'));
        $import->appendChild($doc->createElement('mitteilen', 'Widerruf'));

        $import->appendChild($doc->createComment('Wenn eine Adressänderung vorausgewählt werden soll'));
        $import->appendChild($doc->createElement('AenderungAdresse', true));

        $doc->appendChild($import);
        $xml = $doc->saveXML();
        echo '<pre>';
        echo "Request:\n" . htmlspecialchars($xml) . "\n\nResponse:\n";
        $xml = $this->execCurl($xml, 'https://www.kuendigungshilfe.info/Import');

        echo htmlspecialchars($xml) . '</pre>';
        exit;
    }

    /**
     * @param string $content
     * @param string $url
     * @return mixed
     */
    private function execCurl($content, $url)
    {

        $headers = array(
            "POST " . basename($url) . " HTTP/1.0",
            "Content-type: text/xml;charset=\"utf-8\"",
            "Accept: text/xml",
            "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_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $content);

        $data = curl_exec($ch);

        if (curl_errno($ch)) {
            return curl_error($ch);
        } else {
            curl_close($ch);
            return $data;
        }
    }
}

$Test = new Test();
$Test->start();

API & Einbindung

Überblick

Verlinken

Einbetten

Daten übergeben

Link & GET-Parameter

IFrame-Einbindung

Themes

Import-Schnittstelle

Request (JSON)

Response (JSON)

Request & Response (XML)

Erzeugtes Dokument zurückliefern – returnPathPDF

Sparten-Kürzel

PHP-Beispiele

Erzeugtes Dokument zurückliefern – `returnPathPDF`