Die Ereignisse-API liefert die Ereignisse eines Vorgangs bzw. eines Antrags inkl. Zeitpunkt, Typ, Ersteller, Text und ggf. verlinkter Dokumente zurück.
Aktuelle Version: 2.0.0
Diese Schnittstelle wird kontinuierlich weiterentwickelt. Daher erwarten wir von allen Nutzern dieser Schnittstelle, dass sie das “Tolerant Reader Pattern” nutzen, d.h. tolerant gegenüber kompatiblen API-Änderungen beim Lesen und Prozessieren der Daten sind:
unbekannte Felder dürfen keine Fehler verursachen
Strings mit eingeschränktem Wertebereich (Enums) müssen mit neuen, unbekannten Werten umgehen können
sinnvoller Umgang mit HTTP-Statuscodes, die nicht explizit dokumentiert sind
Für einen Schnelleinstieg, siehe Tools
Für jeden Request ist eine Authentifizierung erforderlich. Die Authentifizierung erfolgt über den OAuth 2.0 Client-Credentials Flow.
| Request Header Name | Beschreibung |
|---|---|
| Authorization | OAuth 2.0 Bearer Token |
Das Bearer Token kann über die Authorization-API angefordert werden. Dazu wird ein Client benötigt der vorher von einer berechtigten Person über das Partnermanagement angelegt wurde, eine Anleitung dafür befindet sich im Help Center.
Damit der Client für diese API genutzt werden kann, müssen im Partnermanagement die folgenden Berechtigungen aktiviert werden
| Name | Hintergrund |
|---|---|
| Baufinanzierungsereignisse lesen | Grundsätzlich zum Auslesen von Ereignissen benötigt |
| Baufinanzierung-Echtgeschäft bearbeiten | sonst sind nur Ereignisse zu Testvorgängen lesbar |
| Darf Partner-Daten lesen | sonst sind werden nur PartnerIds ausgegeben |
| Dokumente lesen | sonst werden keine Dokumente ausgegeben |
Schlägt die Authentifizierung fehl, erhält der Aufrufer eine HTTP Response mit Statuscode 401 UNAUTHORIZED.
Hat der Client nicht die benötigte Berechtigung um die Resource abzurufen, erhält der Aufrufer eine HTTP Response mit Statuscode 403 FORBIDDEN.
Für jeden Request soll eine eindeutige ID generiert werden, die den Request im EUROPACE 2 System nachverfolgbar macht und so bei etwaigen Problemen oder Fehlern die systemübergreifende Analyse erleichtert.
Die Übermittlung der X-TraceId erfolgt über einen HTTP-Header. Dieser Header ist optional,
wenn er nicht gesetzt ist, wird eine ID vom System generiert.
| Request Header Name | Beschreibung | Beispiel |
|---|---|---|
| X-TraceId | eindeutige Id für jeden Request | sys12345678 |
Die Schnittstelle akzeptiert Daten mit Content-Type application/json.
Entsprechend muss im Request der Content-Type Header gesetzt werden. Zusätzlich das Encoding, wenn es nicht UTF-8 ist.
| Request Header Name | Header Value |
|---|---|
| Content-Type | application/json |
| Fehlercode | Nachricht | weitere Attribute | Erklärung |
|---|---|---|---|
| 401 | Unauthorized | - | Authentifizierung ist fehlgeschlagen |
| Fehlercode | Nachricht | Erklärung |
|---|---|---|
| 403 | Insufficient access rights | Es wird versucht auf eine Ressource zuzugreifen, die die Vertriebsorganisation nicht lesen darf |
| 404 | Ressource not found | Es wird versucht auf eine nicht existierende Ressource zuzugreifen |
| 503 | Service temporarily unavailable | Informationen zu Partner, Dokumenten oder dem Vorgang sind aktuell nicht verfügbar |
Die API ist vollständig in Swagger definiert und steht im YAML-Format zur Verfügung. Für die Generierung eines Clients empfehlen wir Swagger Codegen.
Siehe Swagger
Ereignisse zu einem Vorgang auslesen. Beispiel:
curl -X GET \
'https://baufismart.api.europace.de/v2/ereignisse/DM2902' \
-H 'Authorization: Bearer eyJj...GVkA' \
-H 'X-TraceID: myTest123' \
-H 'cache-control: no-cache'
Ereignisse zu einem Ereignis auslesen. Beispiel:
curl -X GET \
'https://baufismart.api.europace.de/v2/ereignisse/DM2902/1/1' \
-H 'Authorization: Bearer eyJj...GVkA' \
-H 'X-TraceID: myTest123' \
-H 'cache-control: no-cache'
https://developer.europace.de/faq/
Für Postman stellen wir im Schnellstarter-Projekt auch eine Collection mit einem Beispiel für die Ereignisse-API zur Verfügung.
Kontakt für Support: devsupport@europace2.de
Nur Bei Bedarf
Die APIs werden unter folgenden Nutzungsbedingungen zur Verfügung gestellt.