diff --git a/README.md b/README.md index 2e8252e..bf16c61 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,120 @@ # Baufismart Ereignisse-API - 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* +* [Release Notes](https://github.com/hypoport/ep-ereignisse-api/releases) + +> :warning: Diese Schnittstelle wird kontinuierlich weiterentwickelt. Daher erwarten wir +> von allen Nutzern dieser Schnittstelle, dass sie das "[Tolerant Reader Pattern](https://martinfowler.com/bliki/TolerantReader.html)" nutzen, d.h. +> tolerant gegenüber kompatiblen API-Änderungen beim Lesen und Prozessieren der Daten sind: +> +> 1. unbekannte Felder dürfen keine Fehler verursachen +> +> 2. Strings mit eingeschränktem Wertebereich (Enums) müssen mit neuen, unbekannten Werten umgehen können +> +> 3. sinnvoller Umgang mit HTTP-Statuscodes, die nicht explizit dokumentiert sind +> + + + +# Inhaltsverzeichnis + +* [Allgemeines](#allgemeines) +* [Authentifizierung](#authentifizierung) +* [TraceId zur Nachverfolgbarkeit von Requests](#traceid-zur-nachverfolgbarkeit-von-requests) +* [Content-Type](#content-type) +* [Fehlercodes](#fehlercodes) + * [HTTP-Status Errors](#http-status-errors) + * [weitere Fehler](#weitere-fehler) +* [API-Spezifikation](#api-spezifikation) +* [API-Referenz](#api-referenz) +* [Beispiel](#beispiel) +* [FAQs](#faqs) +* [Tools](#tools) +* [Kontakt](#kontakt) +* [Nutzungsbedingungen](#nutzungsbedingungen) + # Dokumentation -*Aktuelle Version: 1.2.0 +## Allgemeines + +Für einen Schnelleinstieg, siehe [Tools](#tools) + +## Authentifizierung + +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](https://github.com/europace/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](https://europace2.zendesk.com/hc/de/articles/360012514780). + +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**. + +## TraceId zur Nachverfolgbarkeit von Requests + +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 | + +## Content-Type + +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 | + +## Fehlercodes + +### HTTP-Status Errors + +| Fehlercode | Nachricht | weitere Attribute | Erklärung | +|------------|-----------------|----------------------------|--------------------------------------| +| 401 | Unauthorized | - | Authentifizierung ist fehlgeschlagen | + +### Weitere Fehler + +| Fehlercode | Nachricht | Erklärung | +|------------|----------------------------|-------------------------------------------------------------------------------------------------| +| 403 | Insufficient access rights | Es wird versucht auf eine Ressource zuzugreifen, die die Vertriebsorganisation nicht lesen darf | + +## API Spezifikation 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. * [Swagger.yaml](https://github.com/hypoport/ep-ereignisse-api/blob/master/swagger.yaml) -* [Release Notes](https://github.com/hypoport/ep-ereignisse-api/releases) -### API Docs +## API Referenz -[API Docs](https://ereignisse-api-12.api-docs.io/1.2.0/ereignisse/) +Siehe Swagger -## Wichtigste Features +## Beispiel Ereignisse zu einem Vorgang auslesen. Beispiel: ``` curl -X GET \ - 'https://api.europace.de/v1/ereignisse/DM2902' \ + 'https://baufismart.api.europace.de/v2/ereignisse/DM2902' \ -H 'Authorization: Bearer eyJj...GVkA' \ -H 'X-TraceID: myTest123' \ -H 'cache-control: no-cache' @@ -30,36 +124,25 @@ Ereignisse zu einem Ereignis auslesen. Beispiel: ``` curl -X GET \ - 'https://api.europace.de/v1/ereignisse/DM2902/1/1' \ + 'https://baufismart.api.europace.de/v2/ereignisse/DM2902/1/1' \ -H 'Authorization: Bearer eyJj...GVkA' \ -H 'X-TraceID: myTest123' \ -H 'cache-control: no-cache' ``` -### Authentifizierung - -Die Authentifizierung läuft über den [OAuth2](https://oauth.net/2/) Flow vom Typ *ressource owner password credentials flow*. -https://tools.ietf.org/html/rfc6749#section-1.3.3 - -##### Credentials -Um die Credentials zu erhalten, erfragen Sie beim Helpdesk der Plattform die Zugangsdaten zur Auslesen API, bzw. bitten Ihren Auftraggeber dies zu tun. +## FAQs +[https://developer.europace.de/faq/](https://developer.europace.de/faq/) -##### Schritte -1. Absenden eines POST Requests auf den [Login-Endpunkt](https://htmlpreview.github.io/?https://raw.githubusercontent.com/hypoport/antraege-auslesen-api/master/Dokumentation/index.html#_oauth2) mit Username und Password. Der Username entspricht der PartnerId und das Password ist der API-Key. Alternativ kann ein Login auch über einen GET Aufruf mit HTTP Basic Auth auf den Login-Endpunkt erfolgen. -2. Aus der JSON-Antwort das JWToken (access_token) entnehmen -3. Bei weiteren Requests muss dieses JWToken als Authorization Header mitgeschickt werden. +## Tools -##### Beispiel Implementierung für die Authentifizierung mit einem Java Client und Retrofit +Für [Postman](https://www.getpostman.com/) stellen wir im [Schnellstarter-Projekt](https://github.com/europace/api-schnellstart/) +auch eine Collection mit einem Beispiel für die Ereignisse-API zur Verfügung. -Den API client nicht mit dem Default Konstruktor, sondern dem credentials Kontruktor erzeugen. Z.B: +## Kontakt +Kontakt für Support: devsupport@europace2.de -``` - api = new ApiClient("oauth2","partnerID", "api-key").createService(AntraegeApi.class); -``` - -## Fragen und Anregungen -Bei Fragen und Anregungen entweder ein Issue in GitHub anlegen oder an [helpdesk@europace2.de](mailto:helpdesk@europace2.de) schreiben. +## Requirements +Nur Bei Bedarf ## Nutzungsbedingungen -Die APIs werden unter folgenden [Nutzungsbedingungen](https://developer.europace.de/terms/) zur Verfügung gestellt - +Die APIs werden unter folgenden [Nutzungsbedingungen](https://developer.europace.de/terms/) zur Verfügung gestellt. \ No newline at end of file diff --git a/swagger.yaml b/swagger.yaml index b491f2b..df133f7 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -1,7 +1,7 @@ openapi: 3.0.0 info: description: API für Ereignisse in BaufiSmart-Vorgängen. - version: 1.2.1 + version: 2.0.0 title: Ereignisse API contact: name: Europace AG @@ -11,9 +11,7 @@ tags: - name: Vorgangsereignisse description: Diese Endpunkte repräsentieren die Vertriebssicht auf einen Baufismart Vorgang. - name: Antragsereignisse - description: Diese Endpunkte repräsentieren des Kreditentscheidersicht auf einen Baufismart Antrag. - - name: Webhooks - description: Diese Endpunkte dienen der Konfiguration von Webhooks. Damit können sie über Ereignisänderungen direkt benachrichtigt werden. + description: Diese Endpunkte repräsentieren die Kreditentscheidersicht auf einen Baufismart Antrag. paths: /ereignisse: get: @@ -82,7 +80,7 @@ paths: $ref: "#/components/schemas/Error" security: - oauth2: - - API + - "baufinanzierung:ereignis:lesen" "/ereignisse/{vorgangsNummer}": get: tags: @@ -151,7 +149,7 @@ paths: $ref: "#/components/schemas/Error" security: - oauth2: - - API + - "baufinanzierung:ereignis:lesen" "/ereignisse/{vorgangsNummer}/{antragsNummer}/{teilAntragsNummer}": get: tags: @@ -233,82 +231,18 @@ paths: $ref: "#/components/schemas/Error" security: - oauth2: - - API - /ereignisse/subscribe: - post: - tags: - - Webhooks - summary: Dieser Endpunkt ist work in progress und noch nicht Funktional. Erstellen der Ereignisbenachrichtigung. Als Kreditentscheider werden Sie über Ereignisse zu Anträgen benachrichtigt. - requestBody: - required: true - content: - application/json;charset=UTF-8: - schema: - type: object - properties: - callbackUrl: # Callback URL - type: string - format: uri - example: https://myserver.com/send/callback/here - secret: - type: string - description: secret Token mit dem Ereignisänderungen-Requests signiert werden. Dadurch können Sie prüfen, das der Request von dieser Webhook Registrierung stammt. - resourceType: - type: string - description: Angabe, für welche Art von Ereignisänderung benachrichtigt werden soll - enum: - - "NACHRICHTEN_ZUM_ANTRAG" - required: - - callbackUrl - - secret - - resourceType - callbacks: - ereignisUpdate: - '{$request.body#/callbackUrl}': - post: - requestBody: - required: true - content: - application/json;charset=UTF-8: - schema: - $ref: '#/components/schemas/EreignisUpdateBenachrichtigung' - parameters: - - name: X-EREIGNISSE-API-SIGNATURE - in: header - schema: - type: string - required: true - description: 'HMAC aus Requestbody und {$request.body#/secret}' - responses: - '200': - description: OK - Ereignisänderung erfolgreich verarbeitet - responses: - '201': - description: Ereignisbenachrichtigung eingerichtet - security: - - oauth2: - - API - delete: - tags: - - Webhooks - summary: Dieser Endpunkt ist work in progress und noch nicht Funktional. Löschen der Ereignisbenachrichtigung. - responses: - '200': - description: OK - Ereignisbenachrichtigung wurde gelöscht. - security: - - oauth2: - - API + - "baufinanzierung:ereignis:lesen" servers: - - url: https://baufismart.api.europace.de/v1/ + - url: https://baufismart.api.europace.de/v2/ components: securitySchemes: oauth2: type: oauth2 flows: - password: - tokenUrl: https://api.europace.de/login + implicit: + authorizationUrl: https://api.europace.de/auth/token scopes: - API: Authorisation Scope für die gesamte API. + "baufinanzierung:ereignis:lesen": Leseberechtigung für Ereignisse schemas: Partner: type: object @@ -469,31 +403,4 @@ components: - BEANTRAGT - UNTERSCHRIEBEN - NICHT_ANGENOMMEN - - WIDERRUFEN - EreignisUpdateBenachrichtigung: - type: object - properties: - antragsNummer: - type: "string" - description: 'nur bei resourceType=[ANTRAG_NACHRICHTEN] gesetzt' - antragsReferenz: - type: "string" - description: "Nummer des Antrags in Ihrem System (änderbar). Nur bei resourceType=[ANTRAG_NACHRICHTEN] gesetzt." - erstellerPartnerId: - type: "string" - description: "Der Ersteller der Nachricht" - resourceUrl: - type: "string" - description: 'URL zur Resource, bei der es ein Update gab' - resourceUrlDataType: - $ref: '#/components/schemas/EreignisUpdateResourceType' - required: - - resourceUrl - - resourceType - EreignisUpdateResourceType: - type: string - description: > - Resourcetyp passend zur resourceUrl: - * 'ANTRAG_NACHRICHTEN' - resource Url zeigt auf Nachrichten Resource der Nachrichten API. z.b. - enum: - - "ANTRAG_NACHRICHTEN" \ No newline at end of file + - WIDERRUFEN \ No newline at end of file