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:
Die ID des Suchprofils kann seiner URL entnommen werden, z.B
https://xplorer.ch/projects/21425/0
Wichtig:
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!
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.
Beispiel Login Abfrage:
Beispiel Login Ergebnis:
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.
Wichtig:
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.
Beispiel:
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:
Beispiel Refresh Abfrage:
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:
Endpunkt-Name
all_pn_headers
projects
Objekte
Ausschreibungen / Tenders
Projekte
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:
Beispiel Daten Abholen:
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
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:
Bestätigung per Header
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:
Beispiel Abholen Mit Auto-Ack:
Bestätigung per Endpunkt
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:
Beispiel Ack-Endpunkt:
Datenstruktur für Projekte
Wenn Sie den Endpunkt /web_service/projects/ abrufen, erhalten Sie die Projekte in der unten beschriebenen Datenstruktur.
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.
Hier ist die vollständige Datenstruktur:
Field
Type
Description
Example
id
int
Eindeutige Projekt-ID
312885
title
string
Projekt-Titel
Neubau Reservoir mit Leitungsersatz
subtitle
string
(Dieses Feld ist nicht verfügbar)
(Dieses Feld ist nicht verfügbar)
postcode
int
Postleitzahl
9053
country
string
Land
CHE
town
string
Stadt
Teufen AR
area
string
Gebietsbezeichnung
Les Planches
street
string
Strassenname und Hausnummer
Reservoir Häuslersegg
projectValue
double
Bausumme (in ganzen Währungseinheiten)
1340000
valueDescription
string
Bausummen Text
1.34 Mio CHF
startDate
datetime
Baustart
2023-05-21T22:00:00+00:00
startDateAccuracy
int
Wert zur Berechnung des Baustarts
12
startDescription
string
Baustart Text
Mai 2023
endDate
datetime
Bauende
2024-06-29T22:00:00+00:00
endDescription
string
Bauende Text
Juni 2024
firstPublished
datetime
Erstveröffentlichung
2023-01-20T10:49:16+00:00
lastPublished
datetime
Letzte Veröffentlichung
2023-05-23T09:13:44+00:00
lastUpdate
datetime
Nach Regeln definiertes letztes Update Datum eines Projektes
2023-05-23T09:13:44+00:00
topProject
int
ID des übergeordneten Projektes
1115
mainCategory
int
(Dieses Feld ist nicht verfügbar)
(Dieses Feld ist nicht verfügbar)
externalID
int
Referenz-ID zu Infopro Digital Projekten
3197834
projectRolePersons
Field
Type
Description
Example
projectRolePersonType
Field
Type
Description
Example
id
int
Eindeutige ID der Personenrolle
9
code
string
Eindeutiger Code der Personenrolle
CH_ARCHITECT
name
string
Name der Personenrolle
Architekt
sortOrder
int
Sortierung
130
deprecated
boolean
Zeigt an, ob der Typ noch gängig ist
0
person
Field
Type
Description
Example
id
int
Eindeutige ID der Person
1548945
salutationType
Field
Type
Description
Example
id
int
Eindeutige ID der Anrede
33
code
string
Anredecode
1
name
string
Name der Anrede
Herr
contactSpecifications
Field
Type
Description
Example
content
string
Telefon, Fax, E-Mail, oder URL, je nach Type
071 335 00 15
contactSpecificationType
Field
Type
Description
Example
code
string
Telefon
PHONE
name
string
Telefon
Phone
projectType
Field
Type
Description
Example
id
int
Eindeutige ID der Hauptkategorie
33
code
string
Eindeutiger Code der Hauptkategorie
11
name
string
Name der Hauptkategorie
Technische Anlagen
sortOrder
int
Sortierreihenfolge der Hauptkategorie
50
projectResearchType
Field
Type
Description
Example
id
int
Eindeutige ID des Recherchetyps
8
code
string
Recherchetyp-Code
1
infoText
string
Recherchetyp
Achtung: Dieses Projekt wird aufgrund des schnellen Baufortschritts nicht aktualisiert.
sortOrder
int
Sortierreihenfolge des Recherchetyps
0
purpose
Field
Type
Description
Example
id
int
Eindeutige ID des Verwendungszwecks
14
code
string
Verwendungszweckcode
CH_OWN_USE
name
string
Name des Verwendungszwecks
Eigenbedarf
planningStage
Field
Type
Description
Example
id
int
Eindeutige ID des Baustadiums
19
code
string
Eindeutiger Code des Baustadiums
CH_PASSED_IN
name
string
Name des Baustadiums
Baugesuch eingereicht
sortOrder
int
Sortierreihenfolge des Baustadiums
4
projectTexts
Field
Type
Description
Example
content
string
Text
Neubau Reservoir mit Leitungsersatz und Forststrasse/Zugangsweg Reservoir
projectTextType
Field
Type
Description
Example
code
string
Eindeutiger Code des Texttyps
1
name
string
Name der Textart
Beschreibung
sortOrder
int
Sortierreihenfolge der Textart
1
projectDetails
Field
Type
Description
Example
value
string
Wert des Details
15
negated
boolean
Zeigt an, ob der Wert negiert wird
true
projectDetailType
Field
Type
Description
Example
id
int
ID des Gebäudeausbaus
763
code
string
Code des Gebäudeausbaus
CH_STRUCTURES
name
string
Name des Gebäudeausbaus
Fenster
parentProjectDetailType
Field
Type
Description
Example
id
int
Einmalige ID
1
code
string
Code
Bestandteil
name
string
Name
Bestandteile
visible
boolean
ist in der Detailansicht sichtbar
true
unitType
Field
Type
Description
Example
id
int
Eindeutige interne ID
23
name
string
Name
Stk
toBaseFactor
float
Faktor
1
investmentType
Field
Type
Description
Example
id
int
Eindeutige interne ID
1
name
string
Name
creation
code
string
Code
CREATION
qualityType
Field
Type
Description
Example
id
int
Eindeutige interne ID
1
name
string
Name
Standard
code
string
Code
STANDARD
projectFiles
Field
Type
Description
Example
id
int
Eindeutige interne ID
123456
recordedDate
datetime
Erstelldatum
2019-01-22T08:53:39+00:00
file
Field
Type
Description
Example
id
int
Eindeutige interne ID
123456
name
string
Dateiname
ab3e5e98-3f83-4be1-affe-123456
mnemonicName
string
TypName
Lageplan
mimeType
string
MIME-Typ
image/jpeg
url
string
URL
https://url.jpg
fileType
Field
Type
Description
Example
code
string
Code
PROJECT_IMAGE
projectAttributes
Field
Type
Description
Example
id
int
Eindeutige ID des Attributs
7911848
value
string
Wert des Attributs
Gst. 1243, 2200, 848
projectAttributeType
Field
Type
Description
Example
id
int
Eindeutige ID des Attributs
120
code
string
Eindeutiger Code des Attributs
1
name
string
Name des Attributs
Einsprache
valueType
string
(Dieses Feld ist nicht verfügbar)
(Dieses Feld ist nicht verfügbar)
projectCrafts
Field
craft
Field
Type
Description
Example
id
int
Einmalige ID
1
code
string
Code
U110
name
string
Name
Erdarbeiten
craftState
Field
Type
Description
Example
id
int
Einmalige ID
1
code
string
Code
ASSIGNED
name
string
Name
vergeben
projectTexts
Field
Type
Description
Example
id
int
Eindeutige ID des Texts
97123
content
string
Text
Bewerbungen sind erst nach Veröffentlichung der Ausschreibungsankündigung möglich
projectTextType
Field
Type
Description
Example
id
int
Eindeutige ID des Texttyps
14
code
string
Eindeutiger Code des Texttyps
500
name
string
Name der Textart
Gewerkebemerkung
sortOrder
int
Sortierreihenfolge der Textart
0
planningStageDates
Field
Type
Description
Example
id
int
Eindeutige ID des Datensatzes
27447
project
string
URI zum Projekt
/projects/312885
planningStageDate
datetime
Datum des Baustadiums
2023-05-23T09:13:44+00:00
planningStage
Field
Type
Description
Example
id
int
Eindeutige ID des Baustadiums
19
code
string
Eindeutiger Code des Baustadiums
CH_PASSED_IN
name
string
Name des Baustadiums
Baugesuch eingereicht
sortOrder
int
Sortierreihenfolge des Baustadiums
4
projectCategories
Field
Type
Description
Example
main
boolean
Hauptkategorie JA/NEIN
true
projectCategoryType
Field
Type
Description
Example
id
int
Eindeutige ID der Unterkategorie
738
parentId
int
Eltern-Unterkategorie ID
679
code
string
Eindeutiger Code der Unterkategorie
520
name
string
Name der Unterkategorie
Wasseraufbereitungsanlagen
projectDevelopmentType
Field
Type
Description
Example
id
int
Eindeutige ID der Bauart
code
string
Bauartcode
CH_NEW_CONSTRUCTION
name
string
Bauartname
Neubau
sortOrder
int
Sortierreihenfolge der Bauart
1
deprecated
boolean
Zeigt an, ob der Typ noch gängig ist
0
filterable
boolean
Zeigt an, ob der Typ gefiltert werden kann
1
projectDevelopmentTypeGroup
Field
Type
Description
Example
id
int
Eindeutige interne ID
2
code
string
Code
MODIFICATION
name
string
Name
Umbau/Sanierung
sortOrder
int
Reihenfolge
20
deprecated
boolean
Typ abgelaufen JA/NEIN
false
filterable
boolean
Typ suchbar JA/NEIN
true
projectRoles
Field
Type
Description
Example
active
boolean
Zeigt an, ob die Firma noch aktiv ist
0
mainContact
boolean
Zeigt an, ob es sich um den Hauptkontakt handelt
1
projectRoleType
Field
Type
Description
Example
id
int
Eindeutige Rollen ID
162
code
string
Rollencode
1010
name
string
Name der Rollenbezeichnung
Bauherr
projectRoleTypeGroup
Field
Type
Description
Example
id
int
Eindeutige Role Type Group ID
1
code
string
Code
ARCHITECTS
name
string
Name
Architekten
teaserCompany
Field
Type
Description
Example
id
int
Eindeutige Firmen ID
198123
name1
string
Firmenname
Max
name2
string
Firmenname, Zeile 2
Mustermann GmbH
postcode
string
Postleitzahl
6850
town
string
Ort
Mendrisio
company
Field
Type
Description
Example
id
int
Eindeutige Firmen ID
215266
name1
string
Firmenname
Gemeinde Teufen
name2
string
Firmenname, Zeile 2
Wasserversorgung
street
string
Strassenname und Hausnummer
Krankenhausstrasse 1
town
string
Stadt
Teufen AR
postcode
int
Postleitzahl
9053
country
string
Ländercode
CHE
externalID
int
XOIS-Firmen-ID
1312979
parishPostcode
Field
parish
Field
district
Field
province
Field
Type
Description
Example
officialCode
string
Offizieller Code
NW
salutationType
Field
Type
Description
Example
id
int
Eindeutige ID der Anrede
33
code
string
Anredecode
1
name
string
Name der Anrede
Herr
contactSpecifications
Field
Type
Description
Example
content
string
Telefon, Fax, E-Mail, oder URL, je nach Type
071 335 00 15
contactSpecificationType
Field
Type
Description
Example
code
string
Telefon
PHONE
name
string
Telefon
Phone
projectRolePersons
Field
Type
Description
Example
projectRolePersonType
Field
Type
Description
Example
id
int
Eindeutige ID der Personenrolle
9
code
string
Eindeutiger Code der Personenrolle
CH_ARCHITECT
name
string
Name der Personenrolle
Architekt
sortOrder
int
Sortierung
130
deprecated
boolean
Zeigt an, ob der Typ noch gängig ist
0
person
Field
Type
Description
Example
id
int
Eindeutige ID der Person
1548945
salutationType
Field
Type
Description
Example
id
int
Eindeutige ID der Anrede
33
code
string
Anredecode
1
name
string
Name der Anrede
Herr
contactSpecifications
Field
Type
Description
Example
content
string
Telefon, Fax, E-Mail, oder URL, je nach Type
071 335 00 15
contactSpecificationType
Field
Type
Description
Example
code
string
Telefon
PHONE
name
string
Telefon
Phone
labelProjects
Field
Type
Description
Example
id
int
Einmalige ID
1
value
string
string Wert
true
floatValue
float
float Wert
12.03
dateTimeValue
date
date Wert
2025-01-01T00:00:00+00:00
label
Field
Type
Description
Example
id
int
Einmalige ID
1
name
string
Name
relevant
teamField
boolean
ist team label?
true
globalValue
boolean
ist global label?
false
createdAt
date
Erstelldatum
2025-01-01T00:00:00+00:00
updatedAt
date
Updatedatum
2025-01-01T00:00:00+00:00
color
string
Name der Farbe
orange
sortOrder
int
Sortierung
1
labelType
Field
Type
Description
Example
id
int
Einmalige ID
1
name
string
Name
Boolean
code
string
Code
BOOLEAN
labelAccounts
Field
Type
Description
Example
id
int
Einmalige ID
1
writePermission
int
Schreibrechte
1
sortOrder
int
Sortierung
1
account
Field
Type
Description
Example
id
int
Einmalige ID
1
firstName
string
Vorname
Max
lastName
string
Nachname
Mustermann
email
string
Email
max@mustermann.ch
account
Field
Type
Description
Example
id
int
Einmalige ID
1
firstName
string
Vorname
Max
lastName
string
Nachname
Mustermann
email
string
Email
max@mustermann.ch
Field
id
Type
int
Description
Eindeutige Projekt-ID
Example
312885
Field
title
Type
string
Description
Projekt-Titel
Example
Neubau Reservoir mit Leitungsersatz
Field
postcode
Type
int
Description
Postleitzahl
Example
9053
Field
country
Type
string
Description
Land
Example
CHE
Field
town
Type
string
Description
Stadt
Example
Teufen AR
Field
area
Type
string
Description
Gebietsbezeichnung
Example
Les Planches
Field
street
Type
string
Description
Strassenname und Hausnummer
Example
Reservoir Häuslersegg
Field
projectValue
Type
double
Description
Bausumme (in ganzen Währungseinheiten)
Example
1340000
Field
valueDescription
Type
string
Description
Bausummen Text
Example
1.34 Mio CHF
Field
startDate
Type
datetime
Description
Baustart
Example
2023-05-21T22:00:00+00:00
Field
startDateAccuracy
Type
int
Description
Wert zur Berechnung des Baustarts
Example
12
Field
startDescription
Type
string
Description
Baustart Text
Example
Mai 2023
Field
endDate
Type
datetime
Description
Bauende
Example
2024-06-29T22:00:00+00:00
Field
endDescription
Type
string
Description
Bauende Text
Example
Juni 2024
Field
firstPublished
Type
datetime
Description
Erstveröffentlichung
Example
2023-01-20T10:49:16+00:00
Field
lastPublished
Type
datetime
Description
Letzte Veröffentlichung
Example
2023-05-23T09:13:44+00:00
Field
lastUpdate
Type
datetime
Description
Nach Regeln definiertes letztes Update Datum eines Projektes
Example
2023-05-23T09:13:44+00:00
Field
topProject
Type
int
Description
ID des übergeordneten Projektes
Example
1115
Field
mainCategory
Type
int
Description
(Dieses Feld ist nicht verfügbar)
Example
(Dieses Feld ist nicht verfügbar)
Field
externalID
Type
int
Description
Referenz-ID zu Infopro Digital Projekten
Example
3197834
Field
projectRolePersons
Field
projectRolePersonType
Field
id
Type
int
Description
Eindeutige ID der Personenrolle
Example
9
Field
code
Type
string
Description
Eindeutiger Code der Personenrolle
Example
CH_ARCHITECT
Field
name
Type
string
Description
Name der Personenrolle
Example
Architekt
Field
sortOrder
Type
int
Description
Sortierung
Example
130
Field
deprecated
Type
boolean
Description
Zeigt an, ob der Typ noch gängig ist
Example
0
Field
person
Field
id
Type
int
Description
Eindeutige ID der Person
Example
1548945
Field
salutationType
Field
id
Type
int
Description
Eindeutige ID der Anrede
Example
33
Field
code
Type
string
Description
Anredecode
Example
1
Field
name
Type
string
Description
Name der Anrede
Example
Herr
Field
contactSpecifications
Field
content
Type
string
Description
Telefon, Fax, E-Mail, oder URL, je nach Type
Example
071 335 00 15
Field
contactSpecificationType
Field
code
Type
string
Description
Telefon
Example
PHONE
Field
name
Type
string
Description
Telefon
Example
Phone
Field
projectType
Field
id
Type
int
Description
Eindeutige ID der Hauptkategorie
Example
33
Field
code
Type
string
Description
Eindeutiger Code der Hauptkategorie
Example
11
Field
name
Type
string
Description
Name der Hauptkategorie
Example
Technische Anlagen
Field
sortOrder
Type
int
Description
Sortierreihenfolge der Hauptkategorie
Example
50
Field
projectResearchType
Field
id
Type
int
Description
Eindeutige ID des Recherchetyps
Example
8
Field
code
Type
string
Description
Recherchetyp-Code
Example
1
Field
infoText
Type
string
Description
Recherchetyp
Example
Achtung: Dieses Projekt wird aufgrund des schnellen Baufortschritts nicht aktualisiert.
Field
sortOrder
Type
int
Description
Sortierreihenfolge des Recherchetyps
Example
0
Field
purpose
Field
id
Type
int
Description
Eindeutige ID des Verwendungszwecks
Example
14
Field
code
Type
string
Description
Verwendungszweckcode
Example
CH_OWN_USE
Field
name
Type
string
Description
Name des Verwendungszwecks
Example
Eigenbedarf
Field
planningStage
Field
id
Type
int
Description
Eindeutige ID des Baustadiums
Example
19
Field
code
Type
string
Description
Eindeutiger Code des Baustadiums
Example
CH_PASSED_IN
Field
name
Type
string
Description
Name des Baustadiums
Example
Baugesuch eingereicht
Field
sortOrder
Type
int
Description
Sortierreihenfolge des Baustadiums
Example
4
Field
projectTexts
Field
content
Type
string
Description
Text
Example
Neubau Reservoir mit Leitungsersatz und Forststrasse/Zugangsweg Reservoir