Search by

beliq / shopware-beliq

beliq-eu

Generate compliant EN 16931 e-invoices from Shopware orders through the beliq API.

Package info

github.com/beliq-eu/shopware-beliq

Type:shopware-platform-plugin

pkg:composer/beliq/shopware-beliq

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 1

0.1.0 2026-11-05 17:28 UTC

Requires

Requires (Dev)

Suggests

None

Provides

None

Conflicts

None

Replaces

None

MIT c81641ae56f90e9ad5ce93ea82a514169aa10fda

  • beliq <hello.woop@beliq.eu>

Published on Packagist.org on 2026-11-05 18:05 UTC

This package is auto-updated.

Last update: 2026-11-05 18:12:41 UTC

README

A Shopware 6 plugin that turns store orders into compliant EN 16931 e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) through the beliq API. beliq produces and checks the compliant document; transmission, archiving, and tax-authority reporting stay with your access point.

Status

Version 0.1.0 is on Packagist as beliq/shopware-beliq, built from the tag v0.1.0. It is not in the Shopware Store.

Built and unit tested:

  • The framework-agnostic core: the order-to-EN 16931 mapper (VAT category derivation, tax breakdown, EN 16931 rounding and totals) and the beliq API client.
  • The Shopware runtime wiring. An order-state subscriber listens for payment paid and order completed. On the one the merchant picked, it asks Shopware's DocumentGenerator for a beliq_invoice document. That document type's renderer reloads the order, applies the business-only gate, maps the order, calls the beliq API, and hands back the bytes, which Shopware stores as an order document.

Every pull request and push to main runs the PHPUnit suite on PHP 8.2, 8.3 and 8.4, plus the Shopware Store check (shopware-cli extension validate --store-compliance). The Store check also runs weekly. It includes PHPStan, which phpstan.neon sets to level 8 over the plugin code outside tests/, on top of shopware-cli's own Shopware deprecation and disallowed-call rules.

Verified end to end on a local Shopware 6.7 (Dockware) instance talking to a local beliq API and engine. A business order's paid transition fired the subscriber and produced a beliq_invoice document with its file on disk, for both XML and hybrid-PDF output. Generating again from the admin produced a second document with its own number. Separately, XRechnung and German Peppol BIS invoices built by the plugin's mapper and client validated with zero errors against the same local API and engine (LiveGenerateSmokeTest, which runs only when BELIQ_API_KEY is set). On 2026-11-05 the same test passed 3 of 3 against the production API, a Peppol BIS invoice from a non-German order included.

Still open:

  • The Dockware run has not been repeated against the production API (api.beliq.eu).
  • Non-standard VAT categories (reverse charge, intra-community, export) carry no exemption reason. The beliq API accepts one; the plugin does not send it.

What it does

  • Reads a completed order and builds a valid EN 16931 invoice from its lines, shipping, taxes, parties, and totals. Shipping becomes its own line, split per VAT rate when the shipping method spreads its tax across the cart's rates.
  • Sends it to beliq to generate the document in the format you choose, and can validate it against the authority-pinned rules.
  • Stores the resulting document on the order.

The plugin generates and validates; it does not transmit. Peppol delivery, e-mail, and filing remain with the merchant.

Scope of generation

By default the plugin generates a structured invoice for business orders (the buyer carries a VAT ID, or the order is flagged business at checkout). This matches where a structured e-invoice is legally meaningful. A merchant can widen generation to all orders.

Lines taxed at a standard rate are mapped to VAT category S. A zero-rated line takes a merchant-configured category (default Z). Cross-border reverse charge and intra-community supply are the merchant's call to configure. They are not auto-detected: a wrong guess in a compliance tool is worse than none.

Install

In the root of your Shopware 6.7 project:

composer require beliq/shopware-beliq
bin/console plugin:refresh
bin/console plugin:install --activate BeliqShopware
bin/console cache:clear

BeliqShopware is the plugin's name in Shopware, taken from its plugin class. Then configure it as described under Setup.

Setup

In the plugin settings (Extensions -> beliq e-invoicing -> Configure):

  • Enter your beliq API key.
  • Fill in the seller legal details (name, VAT ID, address). EN 16931 requires them, so the seller block is the merchant's to complete.
  • Pick the document format (ZUGFeRD / Factur-X hybrid PDF by default), profile, and whether to output a hybrid PDF or XML only.
  • Choose when to generate: on payment paid (default) or on order completed.
  • Turn on Generate invoices automatically. Generation is off until you do.

The generated document is stored as a beliq e-invoice document on the order (its Documents tab), with its file kept as private media. It is downloadable there as XML or a hybrid PDF, depending on the format you chose.

Requirements

  • Shopware 6.7. 6.6 is not supported: the document renderer targets the 6.7 RenderedDocument constructor, which dropped a leading parameter 6.6 still has.
  • PHP 8.2 or newer with the curl and json extensions.
  • A beliq account and API key. The free tier is enough to evaluate the plugin.

Development

composer install
composer test          # PHPUnit
composer scrub:check   # fail on em-dash
shopware-cli extension validate . --store-compliance   # Store check, PHPStan at level 8

The mapper and client tests run without a Shopware install. A live smoke against /v1/generate and /v1/validate is gated on a BELIQ_API_KEY environment variable.

License

MIT. See LICENSE.