API-Version 5

Veröffentlicht: 14.05.2022

Dieser Artikel beschreibt die Neuerungen und Änderungen der API-Version 5 im Vergleich zur vorherigen API-Version 4

Eine Einführung einer neuen Version erfolgt, wenn durch eine Änderung die Abwärtskompatibilität der API nicht mehr sichergestellt werden kann. Bitte prüfen Sie vor dem Wechsel auf diese API-Version ob die Änderungen Auswirkungen auf Ihr System haben und führen Sie die notwendigen Anpassungen durch.

Neue API-Endpunkte

Mit der API-Version 5.0 erfolgt die Einführung neuer API-Endpunkte. Folgende Endpunkte wurden hinzugefügt oder um neue Funktionalitäten erweitert:

Neue/erweiterte API-Endpunkte	Kurzbeschreibung	API-Dokumentation
`Account`	Dieser Endpunkt erlaubt nun auch die Verwaltung von anderen Mandanten, d.h. unter anderem die Anlage, Bearbeitung oder Löschung von Mandanten. Die Nutzung der neuen API-Endpunkte zur Erstellung und Verwaltung anderer Mandanten ist Integrationspartnern der windata GmbH voraus. Zur nutzung ist eine vorherige Freischaltung Ihres Mandanten erforderlich. Für weitere Informationen hierzu, wenden Sie sich bitte an den windata Kundenservice.	konfipay api dokumentation - Account
`User`	Dieser neue Endpunkt macht die Nutzerverwaltung innerhalb eines Mandanten per API möglich. Von Anlage über Datenänderung bis zur Einladung von Nutzern stehen nun die meisten Funktionen zur Verfügung, die auch in der konfipay-Weboberfläche verfügbar sind.	konfipay api dokumentation - User
`UserGroup`	Dieser neue Endpunkt erlaubt den Abruf der vorhandenen Benutzergruppen und deren Mitglieder. Die Berechtigungen der Benutzergruppen werden im aktuellen Umfang der API nicht abgedeckt (weder lesend noch schreibend).	konfipay api dokumentation - UserGroup

Vorhandene API-Schlüssel verfügen nicht über die Berechtigungen für die neuen API-Endpunkte. Diese müssen für jeden Schlüssel erst aktiviert werden.

Anpassungen im Bereich der Bankkonten

Die Informationen zum Kontoinhaber eines Bankkontos werden ab dieser Version im neuen Unterelement accountHolder dargestellt. Dazu gehören der Name (Element: name) des Kontoinhabers, die Gläubiger-ID (Element: creditorId) und die Adresse (Element: postalAddress). Im Rahmen der Angleichung an den ISO 20022-Standard wurde die Adresse zudem in deren Bestandteile untergliedert:

Straße (Element: street)
Hausnummer (Element: buildingNumber)
Postfach (Element: postBox)
Postleitzahl (Element: postCode)
Ort (Element: town)
Land (Element: country)

Das Bankkonto selbst wurde ebenfalls um weitere Felder ergänzt:

Kontonummer (Element: accountNumber)
Bankleitzahl (Element: bankCodeNational)
BIC (bankCodeInternational) ergänzt.

Beispiel:

API-Version 4

API-Version 5

JSON

{
"iban": "DE12345678901234567890",
"description": "Description1",
"creditorId": "DE98ZZZ09999999999",
"accountHolderName": "Alice Mayer",
"postalAddress": "Example street 1, 12345 Somewhere",
"additionalInformation": "Additional information 1"
}

JSON

{
  "iban": "DE12345678901234567890",
  "accountNumber": "12345678",
  "bankCodeNational": "11223344",
  "bankCodeInternational": "ABCDEFG1CBA",
  "description": "Description1",
  "additionalInformation": "Additional information 1",
  "accountHolder": {
    "name": "Alice Mayer",
    "creditorId": "DE98ZZZ09999999999",
    "postalAddress": {
      "street": "Examplestreet1",
      "postBox": "12 45 68",
      "buildingNumber": "12",
      "postCode": "12345",
      "town": "ExampleTown1",
      "country": "DE"
    }
  }
}

Alle aktuell in konfipay hinterlegten Adressen für Kontoinhaber werden über die API nicht mehr abgebildet. Diese Änderung gilt auch rückwirkend für die API-Versionen 2.0 bis 4.0.

Das für die API-Versionen 2.0 und 4.0 verwendete ElementpostalAddress wird bei [POST] und [PUT]-Requests ignoriert und somit nicht gespeichert. In den Antwortnachrichten wird das Feld ebenfalls nicht mehr zurückgegeben.