Ralph Soika 11b28ef9c3 KSeF Impl and docu

2025-11-14 23:22:24 +01:00

4.7 KiB

Raw Blame History

KSeF API Integration

Java integration for the Polish Krajowy System e-Faktur (KSeF) - the national e-invoicing system for Poland.

Overview

This integration provides secure communication with the KSeF API to upload electronic invoices. It handles the complex multi-step authentication flow and encryption requirements mandated by the Polish tax authorities.

Components

1. KSeFAuthManager

Manages authentication and session lifecycle for the KSeF API.

Key Responsibilities:

Multi-step authentication flow
RSA certificate management
Session key generation and encryption
Access token lifecycle management
Session reuse and validation

2. KSeFAPIService

Provides business-level methods for invoice operations.

Key Responsibilities:

Invoice encryption (AES-256-CBC)
Invoice upload to KSeF
Hash calculation and validation
Error handling and reporting

Authentication Flow

The KSeF API requires a sophisticated multi-step authentication process:

1. Load Public Keys
   └─> GET /security/public-key-certificates

2. Challenge Request
   └─> POST /auth/challenge
   └─> Returns: challenge + timestamp

3. Token Authentication
   └─> POST /auth/ksef-token
   └─> Encrypts: token|timestamp with RSA-OAEP SHA-256
   └─> Returns: authToken + referenceNumber

4. Token Redemption
   └─> POST /auth/token/redeem
   └─> Returns: accessToken

5. Open Interactive Session
   └─> POST /sessions/online
   └─> Generates AES-256 key + IV
   └─> Encrypts session key with RSA
   └─> Returns: sessionRefNumber + validUntil

Invoice Upload Flow

Once authenticated, invoices can be uploaded:

1. Reuse or Create Session
   └─> Validates existing session or creates new one

2. Encrypt Invoice
   └─> AES-256-CBC encryption using session key

3. Calculate Hashes
   └─> SHA-256 of original XML
   └─> SHA-256 of encrypted XML

4. Upload Invoice
   └─> POST /sessions/online/{sessionRef}/invoices
   └─> Returns: referenceNumber

Security Features

Multi-Layer Encryption

RSA-OAEP SHA-256: Token encryption with timestamp binding
RSA-OAEP SHA-1: Session key encryption
AES-256-CBC: Invoice content encryption

Security Mechanisms

Replay Attack Protection: Timestamp-bound tokens
Session Management: Automatic session reuse and validation
Certificate Validation: Dynamic X.509 certificate loading
UTC Timezone Handling: Prevents timezone-related vulnerabilities

Usage Example

// Initialize Auth Manager
KSeFAuthManager authManager = new KSeFAuthManager();
authManager.setKsefToken("your-ksef-token");
authManager.setKsefNip("1234567890");
authManager.setKsefEndpoint("https://ksef-test.mf.gov.pl/api/v2");
authManager.init();

// Initialize API Service
KSeFAPIService apiService = new KSeFAPIService();
apiService.kseFAuthManager = authManager;

// Upload Invoice
ItemCollection workitem = new ItemCollection();
FileData fileData = new FileData("invoice.xml", xmlBytes, null, null);
workitem.addFileData(fileData);

String referenceNumber = apiService.uploadInvoice(workitem, "invoice.xml");
System.out.println("Invoice uploaded: " + referenceNumber);

Configuration

Required environment variables:

ksef.api.token=your-ksef-authentication-token
ksef.api.nip=your-company-nip-number
ksef.api.endpoint=https://ksef-test.mf.gov.pl/api/v2
ksef.api.debug=false

Session Management

The KSeFAuthManager automatically handles session lifecycle:

Session Reuse: Validates sessionValidUntil timestamp (UTC)
Auto-Renewal: Opens new session if current one expired
Thread-Safe: Uses @Lock(LockType.WRITE) for concurrent access

Testing

Test environment endpoint:

https://ksef-test.mf.gov.pl/api/v2

Production endpoint:

https://ksef.mf.gov.pl/api/v2

See KSeFAPIServiceTest.java for complete test examples.

Error Handling

The implementation uses PluginException for error handling with two error types:

CONFIG_ERROR: Configuration or setup issues
API_ERROR: API communication or response errors

Dependencies

Jakarta EE (EJB, JSON-B)
Java 11+ (HttpClient, Crypto APIs)
Imixs Workflow (for document management)

4.7 KiB Raw Blame History