Madcoders Sylius E-Invoicing KSeF Plugin

KSeF adapter for the madcoders Sylius e-invoicing plugin: submits e-invoices generated by the core plugin to KSeF (Krajowy System e-Faktur), the Polish national e-invoicing system, as FA(3) structured invoices.

This plugin is an optional extension - the core plugin works standalone. Install this adapter when your shop must report invoices to KSeF (mandatory in Poland since February/April 2026).

How it fits together

The core plugin defines a submission port (EInvoiceSubmitterInterface); this adapter implements it and overrides the madcoders_sylius_einvoicing.submitter service:

SubmitEInvoiceProcessor (core)
    └── EInvoiceSubmitterInterface        <- port
            └── KsefSubmitter (this plugin)
                    ├── Fa3XmlBuilder     -> FA(3) invoice XML
                    └── HttpKsefApiClient -> KSeF API

Outcomes map onto the core lifecycle: KSeF reference number -> accepted, content rejection -> rejected, transport failure -> failed (re-queueable).

Requirements

	Version
PHP	^8.3
Sylius	^2.0
madcoders/sylius-einvoicing-plugin	^0.1

Installation

composer require madcoders/sylius-einvoicing-ksef-plugin

1. Register both plugins in config/bundles.php - the core plugin first:

   Madcoders\SyliusEinvoicingPlugin\MadcodersSyliusEinvoicingPlugin::class => ['all' => true],
   Madcoders\SyliusEinvoicingKsefPlugin\MadcodersSyliusEinvoicingKsefPlugin::class => ['all' => true],

2. Import the configuration (config/packages/madcoders_sylius_einvoicing_ksef.yaml):

   imports:
       - { resource: "@MadcodersSyliusEinvoicingKsefPlugin/config/config.yaml" }
   
   madcoders_sylius_einvoicing_ksef:
       environment: prod        # test | demo | prod
       token: "%env(KSEF_TOKEN)%"

3. Set KSEF_TOKEN in your environment.

No extra database tables - the adapter is stateless; all invoice state lives in the core plugin.

Configuration reference

Key	Default	Description
environment	test	KSeF environment (test, demo, prod); selects the API base URL
api_url	derived	Explicit API base URL override
token	%env(default::KSEF_TOKEN)%	KSeF authorisation token

Status

Skeleton stage: the submission path (FA(3) envelope, token-authenticated send, outcome mapping) is wired and tested, but the FA(3) field mapping and the full KSeF 2.0 session flow are not production-complete yet - see ai/tasks/ for the roadmap.

Development

Docker + Make, same as the core repo:

make init      # containers + dependencies + assets + database
make static    # PHPStan + ECS
make phpunit   # PHPUnit
make verify    # everything

For cross-repo development (recommended), bootstrap the workspace from the core repo: make init-workspace there clones this repo as a sibling; composer then symlinks your local core checkout into this repo via a path repository. See the core repo's docs/workspace.md.

Documentation

• docs/adr-log/ - adapter-specific decisions; ecosystem-wide decisions live in the core ADR log
• ai/architecture.md - structural map
• AGENTS.md - orientation for AI agents and contributors

License

Licensed under the European Union Public Licence v1.2 (EUPL-1.2).