FIT-Connect JavaScript SDK

The FIT-Connect JavaScript SDK enables simple and secure integration of FIT-Connect into modern web applications. It supports the creation, encryption, and transmission of submissions as well as secure end-to-end encrypted communication with the FIT-Connect backend.

Target Audience

• Developers who want to use FIT-Connect in JavaScript/TypeScript projects
• Government agencies and service providers implementing digital application processes

Features

• Create and validate submissions
• Encryption and signing of business data and metadata
• Sending attachments
• Communication with FIT-Connect endpoints (Send Submission, Retrieve Public Key)

Installation

npm install @fitko/fit-connect

Quick Start

1. Create and Send a Submission

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

// 1. Initialize Submission Builder
const submission = Submission.builder()
  // Target authority (Destination ID)
  .setDestination('404d5b8f-c0b8-4ef7-916a-48da53f06570')
  // Service Type from LeiKa catalog
  .setServiceType('urn:de:fim:leika:leistung:99400048079000', 'My Service')
  // JSON data with schema validation
  .setJsonData({ data: 'Application data' }, 'https://my-schema.de/schema.json')
  // Optional: Add attachments
  .addAttachments([file])
  .build();

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

// 3. Send submission
const sentSubmission = await sender.sendSubmission(submission);
console.log('Submission-Response:', sentSubmission);

2. Using XML Data

// Alternative: XML data instead of JSON
const submission = Submission.builder()
  .setDestination('404d5b8f-c0b8-4ef7-916a-48da53f06570')
  .setServiceType('urn:de:fim:leika:leistung:99400048079000', 'My Service')
  .setXmlData('<root><data>Application data</data></root>', 'https://my-schema.de/schema.xml')
  .build();

Configuration

SubmissionSender Configuration

The SubmissionSender offers various configuration options:

interface BackendConfig {
  // Required fields
  publicKeyUrl: string;             // URL for the GET endpoint to retrieve the Destination's encryption key
  submissionUrl: string;            // URL for the POST endpoint to send a submission

  // Optional configurations
  timeout?: number;                 // Timeout in milliseconds (Default: 30000)
  retryAttempts?: number;           // Number of retry attempts (Default: 3)
  retryDelay?: number;              // Delay between retries in ms (Default: 1000)
}

Example: Complete Configuration

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

  timeout: 60000,            // 60 seconds timeout
  retryAttempts: 5,          // 5 retry attempts
  retryDelay: 2000,          // 2 seconds between retries
});

Configuration Options in Detail

| Option | Type | Default | Description | |--------|-----|---------|------------------------------------------------------------------------| | publicKeyUrl | string | - | URL for the GET endpoint to retrieve the destination's encryption key. | | submissionUrl | string | - | URL for the POST endpoint to send a submission. | | timeout | number | 30000 | Maximum wait time for HTTP requests in milliseconds. | | retryAttempts | number | 3 | Number of retry attempts for failed requests. | | retryDelay | number | 1000 | Wait time between retry attempts in milliseconds. |

Custom Headers

You can add custom headers to your submission request by passing them to the sendSubmission method:

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

// Send submission with custom headers
const sentSubmission = await sender.sendSubmission(submission, {
    headers: {
        'X-Custom-Header': 'custom-value',
        'Authorization': 'Bearer your-token'
    }
});

The headers will be added to the submission request. This is useful for:

• Adding authentication tokens
• Setting custom tracking headers
• Adding organization-specific identifiers

Backend Integration with FIT-Connect

Due to CORS restrictions (Cross-Origin Resource Sharing), the frontend cannot communicate directly with the FIT-Connect backend. Therefore, a separate backend is required to act as a proxy between the frontend and the FIT-Connect backend.

Backend Requirements

The backend must provide endpoint paths with the following pattern:

• GET /keys/{destinationId} - Retrieve the Public Key
• POST /submit - Submit the submission as multipart/form

An OpenAPI specification of the required backend endpoints can be found under /docs/openapi.yaml.

Reference Backend

FITKO provides a reference backend application that serves as a reference implementation:

• Repository: Java Reference Online Service
• This implementation demonstrates how a backend can provide the necessary endpoints and communicate with the FIT-Connect backend
• The reference application can be used as a basis for your own backend implementations

:warning: The reference backend application is provided as a demonstration. When using it in production, ensure all security measures are properly implemented and configured

For further information on the integration with a backend application see the official documentation.

Further Documentation

• FIT-Connect Documentation (official)
• FIT-Connect Submission API Reference
• Example for Metadata and Attachments
• FIT-Connect Security Concept
• Service Catalog (LeiKa)

Important Notes

• For production use: Please observe the security notices and current FIT-Connect documentation.
• For questions or issues, please contact the FIT-Connect team or use the official support channels.
• Ensure you are using the latest version of the SDK.
• Thoroughly test your integration in the test environment before going into production.

License

Source code is licensed under the EUPL.

Legal Notice: This Software Development Kit (SDK) is intended to enable the connection of software to the FIT-Connect infrastructure. For this purpose, the SDK can be integrated into the software to be connected. If the SDK is integrated in unmodified form, there is no adaptation within the meaning of the EUPL or German copyright law. The manner of linking the SDK does not create a derivative work in particular. The unmodified adoption of the SDK into software to be connected does not therefore mean that the software to be connected must be licensed under the terms of the EUPL. For the distribution of the SDK itself - in unmodified or modified form, as source code or executable program - the license terms of the EUPL apply unchanged.