JavaScript-SDK

Einführung

TL;DR – Das JavaScript-SDK übernimmt die Ende-zu-Ende-Verschlüsselung von Antragsdaten direkt im Browser. Es ersetzt kein Backend, sondern ergänzt es: Ein Java- oder .NET-Backend übermittelt die bereits verschlüsselte Einreichung an FIT-Connect.

Das FIT-Connect JavaScript SDK ermöglicht die einfache und sichere Integration von FIT-Connect in moderne Webanwendungen. Es wurde speziell für die Entwicklung von Onlinediensten konzipiert, die Anträge über FIT-Connect an Verwaltungssysteme senden möchten.

Ende-zu-Ende-Verschlüsselung

Die Verschlüsselung der Antragsdaten findet bereits im Browser der Antragsstellenden statt.

Zielgruppe

Entwickler:innen, die FIT-Connect in JavaScript/TypeScript-Projekten nutzen möchten
Behörden und Dienstleister, die digitale Antragsprozesse umsetzen
Betreiber von Onlinediensten, die mit Verwaltungssystemen kommunizieren möchten
Systemintegratoren, die bestehende Systeme an FIT-Connect anbinden möchten

Vorteile des SDKs

Vereinfachte Integration von FIT-Connect in Webanwendungen
Automatisierte Verschlüsselung und Signatur von Antragsdaten
Kapselung der FIT-Connect REST-API
Reduzierung des Entwicklungsaufwands
Sicherheitsrelevante Aufgaben werden vom SDK übernommen
Unterstützung für moderne Web-Technologien
Fehlerbehandlung und Retry-Mechanismen

Installation

Voraussetzungen

Bevor Sie das SDK installieren, stellen Sie sicher, dass Sie:

Node.js Version 21 oder höher installiert haben
TypeScript 4.0 oder höher installiert ist
NPM oder Yarn als Paketmanager verfügbar ist

Installation über NPM

Die FIT-Connect library ist auf npmjs verfügbar:

# Standardinstallation
npm install @fitko/fit-connect

# Installation mit spezifischer Version
npm install @fitko/fit-connect@1.0.0

# Installation als Entwicklungsabhängigkeit
npm install --save-dev @fitko/fit-connect

:::Hinweis: Bitte verwenden Sie ausschließlich die offiziell von FIT-Connect bereitgestellten Download-Links für die SDKs und zugehörigen Artefakte.:::

Funktionsumfang

Das JavaScript-SDK bietet folgende Hauptfunktionen:

Fluent-Submission-Builder zum Setzen der Antragsdaten und der Leistung der Zielbehörde
Verschlüsselung von Fachdaten (JSON, XML) und Anhängen (Binärdaten, Text) mittels JWE (JSON Web Encryption)
Korrekte Erzeugung eines Metadatensatzes inklusive der Hashwerte
Logging

Besonderheiten

Verschlüsselung der Antragsdaten bereits im Browser der Antragsstellenden
Keine direkte Kommunikation mit FIT-Connect (Backend erforderlich)

1. Submission erstellen und versenden

import { Submission, SubmissionSender } from '@fitko/fit-connect'

// 1. Submission Builder initialisieren
const submission = Submission.builder()
  // Zielbehörde (Destination ID)
  .setDestination('404d5b8f-c0b8-4ef7-916a-48da53f06570')
  // Service Type aus dem LeiKa-Katalog
  .setServiceType('urn:de:fim:leika:leistung:99400048079000', 'Mein Service')
  // JSON-Daten mit Schema-Validierung
  .setJsonData({ data: 'Antragsdaten' }, 'https://mein-schema.de/schema.json')
  // Optional: Anhänge hinzufügen
  .addAttachments([file])
  .build()

// 2. SubmissionSender konfigurieren
const sender = new SubmissionSender({
  publicKeyUrl:
    'https://fit-connect-backend.net/api/keys?destinationId={destinationId}',
  submissionUrl: 'https://fit-connect-backend.net/api/submit',
})

// 3. Submission senden
const sentSubmission = await sender.sendSubmission(submission)
console.log('Submission erfolgreich gesendet:', sentSubmission)

2. XML-Daten verwenden

// Alternative: XML-Daten statt JSON
const submission = Submission.builder()
  .setDestination('404d5b8f-c0b8-4ef7-916a-48da53f06570')
  .setServiceType('urn:de:fim:leika:leistung:99400048079000', 'Mein Service')
  .setXmlData(
    '<root><data>Antragsdaten</data></root>',
    'https://mein-schema.de/schema.xml'
  )
  .build()

3. Anhänge verarbeiten

// Einzelne Datei hinzufügen
const file = new File(['Inhalt'], 'dokument.pdf', { type: 'application/pdf' })
submission.addAttachment(file)

// Mehrere Dateien hinzufügen
const files = [
  new File(['Inhalt 1'], 'dokument1.pdf', { type: 'application/pdf' }),
  new File(['Inhalt 2'], 'dokument2.pdf', { type: 'application/pdf' }),
]
submission.addAttachments(files)

Konfiguration

SubmissionSender Konfiguration

Der SubmissionSender bietet verschiedene Konfigurationsmöglichkeiten:

interface BackendConfig {
  // Pflichtfelder
  publicKeyUrl: string // URL für den GET Endpunkt zum Abruf des Encryption-Keys der Destination
  submissionUrl: string // URL für den POST Endpunkt zum senden einer Submission

  // Optionale Konfigurationen
  timeout?: number // Timeout in Millisekunden (Default: 30000)
  retryAttempts?: number // Anzahl der Wiederholungsversuche (Default: 3)
  retryDelay?: number // Verzögerung zwischen Wiederholungen in ms (Default: 1000)
}

Konfigurationsoptionen im Detail

Option	Typ	Default	Beschreibung
`publicKeyUrl`	`string`	-	URL für den GET Endpunkt zum Abruf des Encryption-Keys der Destination
`submissionUrl`	`string`	-	URL für den POST Endpunkt zum senden einer Submission
`timeout`	`number`	30000	Maximale Wartezeit für HTTP-Anfragen in Millisekunden
`retryAttempts`	`number`	3	Anzahl der Wiederholungsversuche bei fehlgeschlagenen Anfragen
`retryDelay`	`number`	1000	Wartezeit zwischen Wiederholungsversuchen in Millisekunden

Beispiel: Vollständige Konfiguration

const sender = new SubmissionSender({
  publicKeyUrl: 'https://fit-connect-backend.net/api/keys/{destinationId}',
  submissionUrl: 'https://fit-connect-backend.net/api/submit',
  timeout: 60000, // 60 Sekunden Timeout
  retryAttempts: 5, // 5 Wiederholungsversuche
  retryDelay: 2000, // 2 Sekunden zwischen Wiederholungen
})

Benutzerdefinierte Header

Das JavaScript SDK ermöglicht es Ihnen, benutzerdefinierte Header für Ihre Anfragen zu definieren. Diese Header können für verschiedene Zwecke verwendet werden, wie zum Beispiel:

Authentifizierung
Tracking
Debugging

Verwendung benutzerdefinierter Header

Benutzerdefinierte Header werden über die Methode sendSubmission übergeben:

const sender = new SubmissionSender({
  publicKeyUrl: 'https://fit-connect-backend.net/api/keys/{destinationId}',
  submissionUrl: 'https://fit-connect-backend.net/api/submit',
})

// Submission mit benutzerdefiniertem Header senden
const sentSubmission = await sender.sendSubmission(submission, {
  headers: {
    'X-Custom-Header': 'custom-value',
    Authorization: 'Bearer your-token',
  },
})

Wichtige Hinweise

Benutzerdefinierte Header werden zu allen Anfragen hinzugefügt
Header für einzelne Anfragen überschreiben globale Header

Backend-Integration

Wichtiger Hinweis

Aufgrund von CORS-Restriktionen (Cross-Origin Resource Sharing) ist es nicht möglich, dass das Frontend direkt mit dem FIT-Connect-Backend kommuniziert. Daher ist ein eigenes Backend erforderlich, das als Proxy zwischen dem Frontend und dem FIT-Connect-Backend fungiert.

Zudem dient das Backend auch dazu, die ClientId und das ClientSecret zu schützen und nicht im Frontend offenzulegen. Die Fit-Connect-API Credentials dürfen nicht an den User/Browser weitergegeben werden, sondern müssen in der sicheren Umgebung des Backends verborgen bleiben.

Backend-Anforderungen

Das Backend muss folgende Endpunkte bereitstellen:

GET /api/keys?destinationId={destinationId} - Abruf des Public Keys
POST /api/submit - Übermittlung der Submission als multipart/form

Eine OpenAPI Spec für diese Endpunkte finden sich im JavaScript SDK Repo unter docs/openapi.yaml

Hinweis: Bitte verwenden Sie ausschließlich die offiziell von FIT-Connect bereitgestellten Download-Links für die SDKs und zugehörigen Artefakte.

Muster-Anwendung

Die FITKO stellt eine Muster-Anwendung zur Verfügung, die als Referenzimplementierung für die Backend-Integration dient. Diese Implementierung zeigt, wie ein Backend die notwendigen Endpunkte bereitstellen und mit dem FIT-Connect-Backend kommunizieren kann.

Repository

Java Musteranwendung für einen Onlinedienst

Die Muster-Anwendung ist eine Java-basierte Implementierung, die:

Die notwendigen Backend-Endpunkte bereitstellt
Die Kommunikation mit dem FIT-Connect-Backend handhabt
Eine Beispiel-Implementierung für die Integration bietet
Als Basis für eigene Backend-Implementierungen dienen kann

Sicherheit der Demo-Anwendung

Die Referenz-Backend-Anwendung wird als Demonstrations- und Ausgangspunkt bereitgestellt. Bei der Verwendung in Produktionsumgebungen:

Stellen Sie sicher, dass alle Sicherheitsmaßnahmen ordnungsgemäß implementiert und konfiguriert sind
Überprüfen und passen Sie die Sicherheitseinstellungen entsprechend Ihrer spezifischen Anforderungen an

Kommunikationsfluss

Das Frontend kommuniziert ausschließlich mit dem eigenen Backend
Das Backend übernimmt die Kommunikation mit dem FIT-Connect-Backend
Alle sensiblen Operationen (z.B. Verschlüsselung) finden im Frontend statt
Das Backend dient als Proxy für die FIT-Connect-API-Aufrufe

Häufige Stolperfallen

CORS-Fehler beim direkten API-Aufruf — Das SDK kommuniziert nie direkt mit FIT-Connect. Stellen Sie sicher, dass alle Requests über Ihr eigenes Backend laufen und dieses die korrekten CORS-Header setzt. Endpunkte lassen sich mit Postman oder curl unabhängig vom SDK testen.

Verschlüsselung schlägt fehl — Häufigste Ursache ist eine falsche oder nicht erreichbare publicKeyUrl. Prüfen Sie, ob der Endpunkt den Public Key als gültiges JWK zurückgibt und ob keyOps den Eintrag "encryption" enthält.

Timeout beim Senden — Erhöhen Sie timeout in der SubmissionSender-Konfiguration (Standard: 30 000 ms). Aktivieren Sie retryAttempts, damit das SDK transiente Netzwerkfehler selbstständig wiederholt.

Status einer Submission abfragen — Das JavaScript-SDK gibt keinen direkten Zugriff auf den Eventlog. Lassen Sie Ihr Backend den Eventlog über das Java- oder .NET-SDK abrufen und das Ergebnis als Teil der SentSubmission-Antwort an das Frontend durchreichen.

Wo geht's weiter?

Sie wollen loslegen? Schauen Sie sich die Muster-Anwendung als lauffähige Referenz an.
Backend einrichten? Die SDK-Übersicht zeigt, welches Java- oder .NET-Modul als Backend-Partner passt.
Submission senden (Backend-Seite)? Siehe Antrag senden.
Fragen oder Bugs? Das FIT-Connect-Team erreichen Sie über die Kontaktseite.

Lizenz

Hinweis zur Lizenz

Der Quellcode ist lizenziert unter der EUPL (European Union Public License). Die unveränderte Integration des SDKs in Ihre Anwendung erzeugt kein abgeleitetes Werk im Sinne der EUPL – Ihre Anwendung muss damit nicht selbst unter der EUPL lizenziert werden. Für eine Weitergabe des SDKs in unveränderter oder bearbeiteter Form gilt die EUPL.

Einführung​

Zielgruppe​

Installation​

Voraussetzungen​

Installation über NPM​

Funktionsumfang​

1. Submission erstellen und versenden​

2. XML-Daten verwenden​

3. Anhänge verarbeiten​

Konfiguration​

SubmissionSender Konfiguration​

Konfigurationsoptionen im Detail​

Beispiel: Vollständige Konfiguration​

Benutzerdefinierte Header​

Verwendung benutzerdefinierter Header​

Wichtige Hinweise​

Backend-Integration​

Backend-Anforderungen​

Muster-Anwendung​

Kommunikationsfluss​

Häufige Stolperfallen​

Wo geht's weiter?​

Lizenz​