How cirfmf/ksef-client-csharp works
Project type and purpose
• This is a .NET-based SDK and demonstration suite for interacting with the Polish KSeF electronic invoicing API (REST).
• It consists of:
· A core library (KSeF.Client.Core) defining models, interfaces, and exceptions.
· A client library (KSeF.Client) implementing API-call logic, DI registration, HTTP transport, and cryptography coordination.
· A demo ASP.NET WebApp (KSeF.DemoWebApp) to showcase usage.
· A set of unit, functional, and E2E tests in several test projects.
File structure
Top-level directories:
• KSeF.Client.Core: shared models/interfaces/exceptions (.NET Standard 2.0)
• KSeF.Client: main library
· Api/Builders – builder objects for each API endpoint
· Api/Services – service classes (AuthCoordinator, CryptographyService, SignatureService, QrCodeService, VerificationLinkService)
· Clients – low-level HTTP client wrappers (CryptographyClient, KSeFClient, LimitsClient, TestDataClient)
· DI – extension methods & options for Microsoft.Extensions.DependencyInjection
· Http – RestClient, JsonUtil, HTTP-helper extensions
• KSeF.DemoWebApp: ASP.NET controllers and example XAdES certificate services
• KSeF.Client.Tests*, KSeF.Client.Tests.Utils: unit/E2E/integration/spec-style tests
• CertTestApp: console app demo for certificate creation
README for insights
• Confirms layered structure and technologies: .NET 8/9, DI, RestClient, builder pattern
• Shows registration snippets for AddKSeFClient and AddCryptographyClient
• Indicates test organization (E2E, unit, utility classes)
Main components & their interactions
A. Presentation layer (DemoWebApp)
· Controllers (InvoiceController, AuthController, etc.) inject IKSeFClient, ICryptographyService, etc.
B. Service layer (KSeF.Client.Api.Services)
· Implements business orchestration: builds requests via Builders, calls low-level Clients, handles responses, coordinates crypto.
C. Client transport (KSeF.Client.Clients & Http)
· RestClient wraps HttpClient
· Builders produce RestRequest objects (URL, headers, body)
· Clients send requests, parse JSON, handle errors (ApiException, rate-limit)
D. Core abstractions (KSeF.Client.Core)
· Interfaces define contracts (IKSeFClient, IRestClient, ICryptographyService…)
· Models define all request/response DTOs for: Authorization, Certificates, Invoices, Sessions, Permissions, QRCode, Peppol, Token
· Exceptions capture API and validation errors
E. External systems
· KSeF REST API endpoints (Test, Demo, Production URLs)
· XAdES cryptography (local key store / certificate fetcher)
Architectural patterns & principles
• Layered architecture (Presentation → Business Services → Transport → Core)
• Dependency Injection for all services/clients
• Builder pattern for request construction
• Separation of concerns: Models/Interfaces in Core, Implementation in Client
• Async I/O with HttpClient abstraction
• Test pyramid: unit tests, integration/E2E tests, demo app