office-alexander-logistics/doc/KSeF

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)

References

• KSeF Official Documentation
• KSeF API Specification
• Upload Invoice
• Facture Details
• XML Invoice Example