FINcheck API Dokumentation

Wie nutzt man die FINcheck API?

Die folgende Beschreibung richtet sich an den IT Umsetzer.

Wie man mit der REST API genau interagieren kann und welche JSON Daten man dabei inkludieren muss wird auf der Endpunkt Dokumentation gezeigt, welche auch verwendet werden kann, um direkt Anfragen an die API zu senden. In weiterer Folge wird die genaue Reihenfolge der Schritte zur Nutzung der API erklärt

Benutzerkonto und Authentifizierung

Registrierung

Um mit der API kommunizieren muss zunächst ein neues Benutzerkonto erstellt werden. Hierfür muss ein Request an den /register Endpunkt gesendet werden, mit dem von uns erhaltenen Registrierungscode, sowie den Zugangsdaten, welche in der Endpunkt Dokumentation zu sehen sind.

SEHR WICHTIG: Bei der ersten Registrierung erhalten Sie einen Security-Code. Diesen Code, sowie die verwendeten Userdaten müssen sie unbedingt sicher aufbewahren.

Zugriffstoken

Sobald das Benutzerkonto erstellt wurde, kann unter dem /token Endpunkt ein Zugriffstoken requested werden. Dieses Token gilt für die begrenzte Zeitdauer von 1h und muss bei allen anderen Requests im HTTP Authorization header als Bearer Token beigefügt werden.

Info: Beim Request des Tokens sind nur username und passwort erforderlich. Die anderen Werte wie grant_type, scope, client_id und client_secret, die in der Dokumentationsseite erscheinen entfallen.

FIN Datensatz - Bestandteile

Ein FIN-Datensatz enthällt folgende Werte

FIN: Fahrzeugidentifikationsnummer
Start Datum: Start und Enddatum begrenzen den Antragszeitraum für eine FIN. Das Startdatum gibt dabei den Zeitpunkt der erstmaligen Ladung des E-Fahrzeugs an einer nicht-öffentlichen Ladestelle im Antragsjahr an.
Enddatum: Start und Enddatum begrenzen den Antragszeitraum für eine FIN. Das Enddatum gibt den Zeitpunkt an, an dem im Antragsjahr das E-Fahrzeug letztmalig an einer nicht-öffentlichen Ladestelle geladen wurde oder voraussichtlich wird.
Registrierungszeitpunkt: Der Registrierungszeitpunkt ist das Datum und der Zeitpunkt, an dem das registrierte Unternehmen die Vereinbarung mit dem begünstigten E-Fahrzeug-Zulassungsbesitzer abgeschlossen hat. Zulässige Eingabewerte sind sowohl ISO 8601-Daten als auch Unix-Timestamps. Wird eine Zeitzone angegeben, erfolgt automatisch eine Umwandlung in die lokale Zeitzone (UTC+2) in der Datenbank.

Info: Start und Enddatum müssen dabei innerhalb des selben Kalenderjahres liegen. Alle Daten müssen bei einer Abfrage oder einem Eintrag vorliegen.

FINs checken und hinzufügen (create)

Request

Um aktiv an der API teilzunehmen und sowohl die FINs zu überprüfen als auch diese zu speichern wird der /create Endpunkt für einzelne, sowie der /bulk_create für mehrere FINs verwendet. Neben dem Zugriffstoken muss hier auch der der security-code als x-security-code: 'CODE' als benutzerdefinierter HTTP Header hinzugefügt werden. Der HTTP Header soll somit folgendes beinhalten:


                { 'Authorization': 'Bearer TOKEN',

                'x-security-code': 'SECURITYCODE',

                'Content-Type': 'application/json' }

Bei verwendung der Create Endpunkte, gibt es ein paar Parameter, auf die hier näher eingegangen wird:

commit_on_overlapping_dates (default: false): Dieser Parameter kontrolliert, ob eine neue FIN auch zur Datenbank hinzugefügt werden soll, wenn diese FIN mit einer überlappenden Zeitspanne bereits in der Datenbank vorhanden ist. Bsp: Sie fügen ein FIN im Zeitraum 01.06.2024 - 31.12.2024 hinzu. Die selbe FIN ist für den Zeitraum 01.01.2024 - 31.12.2024 schon registriert und überlappt somit mit ihrer FIN. Wenn der Parameter auf True gesetzt ist, wird ihre FIN trotzdem zusätzlich in die Datenbank eingetragen, sonst nicht.

Hinweis: Kommt es zu Überlappungen werden alle registrierten Unternehmen darauf hingewiesen. Für den Fall, dass keine Anonymisierung gewünscht wurde, nur die spezifischen Unternehmen. Damit kann im o.g. Beispiel der Erstkunde kontaktiert werden. Auf Wunsch und Rückmeldung nehmen wir dann eine Änderung in der Datenbank vor.

commit_on_partial_success (default: false): Dieser Parameter muss nur bei bulk-create hinzugefügt werden. Kommt es bei einem Bulk-Create Request zu Fehlern bei einzelnen FINs oder zu Überlappungen, welche nicht eingetragen werden (commit_on_overlapping_dates=false), dann bestimmt dieser Parameter ob alle anderen validen FIN Datensätze, in die Datenbank gespeichert werden sollen oder nicht.

Response

Im Response sind folgende Datentypen enthalten:

created: Dies umfasst alle FIN-Datensätze die tatsächlich in der Datenbank gespeichert wurden.
overlapping_fins: Dis umfasst alle FIN-Datensätze, die mit den im Request gesendeten FINs überlappen, unabhängig davon, ob diese in die Datenbank eingetragen wurden oder nicht. Dabei wird für jede FIN bei der eine Überlappung besteht, ein FoundFin Objekt returniert, welches die Anzahl der Überlappungen mit dieser FIN, sowie die dabei eingetragenen Start- End- und Registrierungsdaten enthällt.
failed: Dies umfasst alle FIN-Datensätze die gesendet wurden, aber nicht in die Datenbank eingetragen wurden. Hierbei können auch FINs mit Überlappungen vorkommen, welche aufgrund von commit_on_overlapping_dates=false, nicht in die Datenbank eingetragen wurden.

FINs checken (search)

Wenn nur überprüft werden soll ob bestimmte FINs in der FINcheck-Datenbank vorhanden sind, diese aber nicht zur Datenbank hinzugefügt werden sollen, wird der /search Endpunkt für einzelne FINs und der /bulk_search Endpunkt für mehrere FINs verwendet. Dabei muss das zuvor beantragte Zugriffstoken in dem Authorization header vorhanden sein. Neben den FINs muss im Request auch das Kalenderjahr, welches zu möglichen Kollisionen überprüft werden soll, angegeben werden.
Die API antwortet als Response mit einem Boolschen Wert, ob die Einträge gefunden wurden. Ebenso werden FoundFin Objekte returniert, welche die Anzahl der Eintragungen zu dieser spezifischen FIN, sowie die zugehörigen Daten enthällt. Eine genaue Beschreibung der Endpunkte und Schema ist wie immer in der Endpunkt Dokumentation

FINs entfernen (delete)

Falls FIN-Datensätze fälschlicherweise eingetragen wurden und wieder entfernt werden sollen, kann der /delete Endpunkt verwendet werden. Dafür müssen die FIN, das Startdatum, das Enddatum sowie der bei der Erstellung verwendete Security-Code an die API übermittelt werden. Die API gibt als Antwort einen booleschen Wert zurück, der anzeigt, ob die gewünschte FIN erfolgreich gelöscht wurde. Zusätzlich liefert die API ein FoundFin-Objekt mit allen Informationen zu den gelöschten FIN-Datensätzen. Dies kann auch mehrere Einträge umfassen, falls derselbe Datensatz mehrfach von Ihnen eingetragen wurde.

Nutzungsmodelle

Zur Verwendung der API gibt es drei Benutzer-Modelle, welche unterschiedlich funktionieren und unterschiedlich abgerechnet werden. Generell wird die Verwendung der API nach Lese und Schreibzugriffen verrechnet.

Standard-Teilnehmer: Teilnehmer der FINcheck API, verwenden die /create und /bulk_create Endpunkte, welche einen gleichzeitigen Lese und Schreibzugriff ermöglichen. Beim Standard-Teilnehmer wird dabei die Anzahl der Lese und Schreibzugriffe, direkt beim Useraccount gespeichert und zur Abrechnung verwendet.
Inkognito-Teilnehmer: Der Unterschied zum Standard-Teilnehmer ist, dass Lese und Schreibzugriffe, nicht direkt beim Benutzeraccount, sondern nur mittels einem globalen Counter gezählt werden. Somit, wird nicht gespeichert, wie viele FIN-Datensätze ein Benutzer in der Datenbank hat.
Lese-Benutzer: Dieser Benutzer nimmt nicht aktiv an der API teil, sondern verwendet nur die /search und /bulk_search Endpunkte um zu überprüfen, ob bestimmte FINs in der Datenbank vorhanden sind. Die Anzahl der Lesezugriffe wird, so wie beim Standard-Teilnehmer zum Benutzeraccount gespeichert.

Noch Fragen?

Wenn Sie ihre interne Software an die FINCheck-API anbinden wollen und dabei Hilfe benötigen, kann unsere IT gerne dabei helfen. Sie können uns unter office(at)i-invest.at, Betreff FINCheck, erreichen.