Zum Hauptinhalt springen

JavaScript-SDK

Inhaltsverzeichnis​

  1. Einführung
  2. Installation
  3. Funktionsumfang
  4. Konfiguration
  5. Backend-Integration
  6. Muster-Anwendung
  7. Sicherheitshinweise
  8. Häufig gestellte Fragen
  9. Troubleshooting

Einführung​

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:

  1. Node.js Version 21 oder höher installiert haben
  2. TypeScript 4.0 oder höher installiert ist
  3. 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

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​

OptionTypDefaultBeschreibung
publicKeyUrlstring-URL für den GET Endpunkt zum Abruf des Encryption-Keys der Destination
submissionUrlstring-URL für den POST Endpunkt zum senden einer Submission
timeoutnumber30000Maximale Wartezeit für HTTP-Anfragen in Millisekunden
retryAttemptsnumber3Anzahl der Wiederholungsversuche bei fehlgeschlagenen Anfragen
retryDelaynumber1000Wartezeit 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.

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

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​

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

Sicherheitshinweise​

  • Alle sensiblen Operationen finden im Frontend statt
  • Verschlüsselung erfolgt clientseitig
  • Keine unverschlüsselten Daten im Backend
  • Validierung aller Eingabedaten

Häufig gestellte Fragen​

Allgemeine Fragen​

F: Muss ich ein eigenes Backend implementieren? A: Ja, aufgrund von CORS-Restriktionen ist ein eigenes Backend als Proxy erforderlich.

F: Welche Datenformate werden unterstützt? A: Das SDK unterstützt sowohl JSON als auch XML als Datenformate.

F: Wie sicher ist die Kommunikation? A: Alle sensiblen Daten werden clientseitig verschlüsselt und die Kommunikation erfolgt über gesicherte Kanäle.

Technische Fragen​

F: Wie handle ich Fehler? A: Das SDK bietet umfangreiche Fehlerbehandlung und Retry-Mechanismen.

F: Wie kann ich den Status einer Submission abfragen? A: Über das Backend können Sie den Status und Event-Log einer Submission abfragen. Dieser kann in der SentSubmission als optionaler Status an das Frontend übertragen werden.

F: Welche Browser werden unterstützt? A: Das SDK unterstützt moderne Browser wie Chrome, Firefox, Safari und Edge.

Troubleshooting​

Häufige Probleme und Lösungen​

  1. CORS-Fehler
  • Stellen Sie sicher, dass Ihr Backend die korrekten CORS-Header setzt
  • Überprüfen Sie die Backend-Konfiguration
  • Testen Sie die Endpunkte mit Postman oder curl
  1. Verschlüsselungsfehler
  • Überprüfen Sie die Public-Key-URL
  • Stellen Sie sicher, dass der Public Key gültig ist
  • Überprüfen Sie die Datenformate
  1. Timeout-Fehler
  • Erhöhen Sie den Timeout-Wert
  • Überprüfen Sie die Netzwerkverbindung
  • Implementieren Sie Retry-Mechanismen

Weiterführende Informationen​

Support​

Bei Fragen oder Problemen wenden Sie sich bitte an:

  • Das FIT-Connect-Team - Kontakt
  • Die offiziellen Support-Kanäle
  • Die Dokumentation auf docs.fitko.de

Lizenz​

Der Quellcode ist lizenziert unter der EUPL (European Union Public License).

Rechtlicher Hinweis​

Dieses Software Development Kit (SDK) ist dazu bestimmt, die Anbindung einer Software an die FIT-Connect-Infrastruktur zu ermöglichen. Hierfür kann das SDK in die anzubindende Software integriert werden. Erfolgt die Integration des SDK in unveränderter Form, liegt keine Bearbeitung im Sinne der EUPL bzw. des deutschen Urheberrechts vor. Die Art und Weise der Verlinkung des SDK führt insbesondere nicht zur Schaffung eines abgeleiteten Werkes. Die unveränderte Übernahme des SDK in eine anzubindende Software führt damit nicht dazu, dass die anzubindende Software unter den Bedingungen der EUPL zu lizenzieren ist. Für die Weitergabe des SDK selbst - in unveränderter oder bearbeiteter Form, als Quellcode oder ausführbares Programm - gelten die Lizenzbedingungen der EUPL in unveränderter Weise.