REST-API

Vermittlerpost Schritt für Schritt

Hinter dem Vermittlerportal verbirgt sich eine REST-API. Das heißt, es stellt zustandslose Schnittstellen zu Verfügung. Mithilfe eines einfachen REST-Clients können wir bestimmte Daten abrufen und z.B. in andere Systeme integrieren. Auf Linux beispielsweise kann man mit cURL auf der einfachen Kommandozeile REST-Client-Aktionen ausführen. Alles, was wir dazu noch benötigen, ist ein API-Key, der uns bei den Anfragen an den Server authentifiziert.

Im 1. Schritt holen wir uns eine Liste aller ungelesenen Dokumente. Dabei geht es noch nicht um die schweren PDFs, sondern lediglich um die Metadaten in einem schlanken JSON-Objekt. Den Aufruf können wir so oft aufrufen, wie wir möchten: wir werden jedes Mal das gleiche Ergebnis erhalten, sofern wir nicht ein Dokument explizit als abgeholt bestätigen (3. Schritt) oder neue Vermittlerpost zugestellt wird.

cURL-Aufruf:

curl -X GET "https://slp-vermittlerportal.de/vermittlerpost/api/ungelesenedokumente" -H "accept: application/json" -H "apikey:ABC123abcXYZ"

Ergebnis:

[{ "id": 41, "filename": "Maxi Musterfrau --- H 201-052203999999-99 --- Versicherungsschein.pdf", "hash": "uniquehash", "name": "Musterfrau", "vorname": "Maxi", "vsnr": "H 201-052203999999/99", "schadennummer": "999999/1-18", "sparte": "Haftpflichtversicherung", "adressBlock": "Maxi Musterfrau<br>Erfenschlager Straße 17-19<br>09125 Chemnitz", "anlagen": "Versicherungsschein", "angelegtDatum": 1520505379000, "abgeholtDatum": null, "biproschluessel": "100007000", "downloadHref": "/vermittlerpost/api/download/uniquehash" }]

Im 2. Schritt geht es um das eigentliche Dokument. In Schritt 1 bekommen wir zu jedem Dokument in der Eigenschaft "downloadHref" den eigentlichen Download-Link. Diesmal bekommen wir kein JSON-Objekt, sondern das pure Dokument als Octet-Stream. Auch diesen Aufruf können wir so oft wiederholen, wie wir möchten oder bis der Download erfolgreich abgeschlossen wurde.

cURL-Aufruf:

curl -X GET "https://slp-vermittlerportal.de/vermittlerpost/api/download/uniquehash" -H "accept: application/octet-stream" -H "apikey:ABC123abcXYZ"

Ergebnis:

eine Datei Maxi Musterfrau --- H 201-052203999999-99 --- Versicherungsschein.pdf

Im 3. Schritt bestätigen wir, dass wir die Datei erhalten haben. Im Vermittlerportal wird damit das Dokument ebenfalls als gelesen markiert und im 1. Schritt wird von nun an das Dokument nicht mehr mitgeliefert. Wenn wir zweimal das gleiche Dokument markieren wollen, erhalten wir Status 409 als Fehler.

cURL-Aufruf:

curl -X POST "https://slp-vermittlerportal.de/vermittlerpost/api/markiereabgeholt/uniquehash" -H "apikey:ABC123abcXYZ"

Ergebnis:

Status: 200

Damit haben wir in 3 Schritten einen Ablauf geschaffen, der unsere Vermittlerpost zuverlässig vom Server holt.