Webservice Dokumentation

Vorbereitung

Damit Sie den Web-Service nutzen können muss zunächst ein Suchprofil eingerichtet werden. Beim Speichern des Suchprofils muss darauf geachtet werden, dass dieses mit der Option "Web-Service" angelegt wird:

Dies gilt gleichermassen für Suchprofile vom Typ Projekte wie auch vom Typ Submissionen — legen Sie für jeden Objekttyp ein eigenes Suchprofil an.

Die ID des Suchprofils kann seiner URL entnommen werden, z.B

• Nach der Einrichtung des Suchprofils kann dieses per Webservice erst ab dem nächsten Tag abgerufen werden!
• Neue Ergebnisse können nur an den beim Speichern des Suchprofils aktivierten Tagen abgerufen werden!

Umgebungen

Login

Um sich mit dem Web-Service zu verbinden, muss zunächst ein Login erfolgen. Dieser kann unter dem Endpunkt POST /login_check erreicht werden. Hier wird eine Anfrage mithilfe des Benutzernamens und Passwortes des zur Verfügung gestellten Benutzers gestellt. Der Login ist identisch — unabhängig davon, ob Sie anschliessend Projekte oder Submissionen abrufen.

Ein erfolgreicher Login liefert einen JWT-Token und einen entsprechenden Refresh-Token. Ersteres wird für jeden weiteren Kontakt mit der Schnittstelle benötigt. Letzteres wird benötigt, um sich nach Ablauf des Tokens einen neuen Token ausstellen zu lassen.

Wenn Sie einen normalen Benutzer haben, welcher sich nicht mehrfach gleichzeitig einloggen kann, bekommen Sie auch einen Security-Cookie. Diesen müssen Sie ebenfalls bei jedem Aufruf mit sich führen.

Hinweis zur Session-Verwaltung: Beim Testen der Schnittstelle ist zu beachten, dass pro Benutzerkonto nur eine aktive Session erlaubt ist. Wenn Sie sich über die Schnittstelle mit Benutzername und Passwort einloggen, wird eine bestehende Browser-Session automatisch beendet. Das gleiche gilt umgekehrt: Sobald Sie sich erneut im Browser anmelden, wird die bestehende API-Session beendet. Dies sollte insbesondere bei Entwicklungs- und Testarbeiten berücksichtigt werden.

Der JWT ist standardmässig eine Stunde lang gültig. Benötigt man eine längere Session, kann man den Token mithilfe des Refresh-Tokens unter POST /token/refresh wie folgt erneuern:

Das Ergebnis dieser Abfrage ist identisch mit der Login-Abfrage. Der Refresh-Token ist 8 Stunden lang gültig und wird ebenfalls erneuert bei jedem Aufruf.

Abholen der Daten

Es gibt zwei mögliche Endpunkte entsprechend der im Xplorer verfügbaren Produkte.

SearchProfile-IDs sind strikt an den jeweiligen Endpunkt (Objekttyp) gebunden und können nicht zwischen verschiedenen Endpunkten wiederverwendet werden. Wird ein SearchProfile mit einem nicht passenden Endpunkt verwendet, führt dies zu einem „SearchProfile with given id not found"-Fehler, auch wenn die ID grundsätzlich existiert.

Hinweis: Welche Objekte bei Ihnen verfügbar sind, hängt von Ihrem Baublatt- Rahmenvertrag ab.

Das Abholen der Daten findet über einen der o.g. Endpunkte per GET statt, z.B. /web_service/all_pn_headers/. Hierzu wird der bereits erhaltene JWT-Token und die ID von dem zuvor angelegten Suchprofil benötigt. Der Token wird mittels Authorization-Header mitgegeben. Die Suchprofil-ID mithilfe eines GET-Parameters wie folgt:

Diese Abfrage liefert nun, sofern vorhanden, die neuen Daten Ihres Suchprofils. Das Format der Daten kann mittels des Accept-Headers entschieden werden. Die folgenden Optionen stehen standardmässig zur Verfügung:

• Accept: application/xml
• Accept: application/json
• Accept: application/ld+json

Für neue Integrationen empfehlen wir die Nutzung des Formats application/json, da dieses Format in den meisten Programmiersprachen und Integrationsplattformen standardmässig unterstützt wird.

Bestätigung der Abholung

Der Web-Service liefert Ihnen die Daten Ihres Suchprofils und merkt sich dabei, was Sie bereits abgeholt haben. Standardmässig bekommen Sie 10 bzw. 20 Datensätze (Projekte bzw. Tenders) pro Aufruf der oben genannten Endpunkte. Damit eventuelle Fehler behandelt werden können, müssen Sie das Abholen jedoch bestätigen um an die nächsten 20 Datensätze zu kommen. Hierzu bieten wir Ihnen zwei Wege:

Wenn Sie keinen weiteren Endpunkt aufrufen wollen, können Sie direkt beim Abholen der Daten bestätigten, dass Sie die Daten erhalten haben. So bekommen Sie bei jedem Aufruf des o.g. Endpunktes neue Daten. Dies geschieht mithilfe des Headers X-AUTO-ACK. Dazu das passende Beispiel:

Der sicherste Weg keine Daten zu verlieren ist es, uns nach dem Abholen separat mitzuteilen, dass Sie die Daten sauber bekommen haben. Dies geschieht mithilfe des Endpunktes POST /web_service/acknowledge/. Hierzu wird ein JSON-Objekt erwartet, welches sowohl die Suchprofil-ID von Ihnen enthält als auch die IDs der Datensätze, welche Sie uns Bestätigen wollen. Hierzu ein Beispiel:

Datenstruktur

Wählen Sie unten aus, ob Sie die Datenstruktur für Projekte oder für Submissionen sehen möchten.

Anmerkung: Immer wenn Sie ein Datenfeld "Code" in der Datenstruktur sehen, können Sie eine entsprechende Liste mit allen verfügbaren Codes zusammen mit den dazugehörigen Namen als CSV über das Download-Symbol herunterladen.