Developer

The extension provides three extension points for connecting your own or third-party modules – for allowances, for amounts already paid and for SEPA direct debit data. The two adapter interfaces are registered into a pool via dependency injection, the direct debit extension point via a preference.

Types of integration

Area	Extension point	Handling
Vouchers, store credit, reward points	`PrepaidAdapterInterface`	BT-113 (prepaid amount)
Additional allowances	`AllowanceAdapterInterface`	Allowance at document level (BG-20)
SEPA direct debit	`DirectDebitDataProviderInterface`	BG-19 (BT-89/90/91)
PDF extensions for invoice documents	Plugin (no interface required)	Hybrid ZUGFeRD PDF with embedded XML

Embedding into the PDF works with the standard Magento PDF as well as with several common PDF extensions; nothing needs to be implemented on your side.

AllowanceAdapterInterface

For amounts that are to be represented as an allowance at document level.

namespace Geissweb\ElectronicInvoicing\Api;

use Magento\Sales\Api\Data\InvoiceInterface;
use Magento\Sales\Api\Data\CreditmemoInterface;

interface AllowanceAdapterInterface
{
    public function isEnabled(): bool;

    /**
     * @return array<int, array<string, mixed>>
     */
    public function extractAllowances(InvoiceInterface|CreditmemoInterface $document): array;

    public function getModuleName(): string;

    public function getPriority(): int;
}

extractAllowances() returns, per allowance, an array with the keys amount (float, excluding VAT), vat_category (EN 16931 category, e.g. S), vat_rate (float, e.g. 19.0), reason (text) and reason_code (e.g. DISCOUNT).

PrepaidAdapterInterface

For amounts already paid (BT-113) such as vouchers, store credit or reward points.

namespace Geissweb\ElectronicInvoicing\Api;

use Magento\Sales\Api\Data\CreditmemoInterface;
use Magento\Sales\Api\Data\InvoiceInterface;

interface PrepaidAdapterInterface
{
    public function isEnabled(): bool;

    /**
     * @return array{amount: float, reference: string}
     */
    public function extractPrepaidAmount(InvoiceInterface|CreditmemoInterface $document): array;

    public function getModuleName(): string;

    public function getPriority(): int;
}

Both interfaces reside in the namespace Geissweb\ElectronicInvoicing\Api. getPriority() controls the execution order – lower values = higher priority (default 100).

DirectDebitDataProviderInterface

For SEPA direct debit details (BG-19). Magento has no native direct debit payment, so the extension cannot determine the mandate reference, the creditor identifier or the account to be debited on its own. If you operate your own direct debit solution, supply the values through this extension point.

namespace Geissweb\ElectronicInvoicing\Api;

use Geissweb\ElectronicInvoicing\Model\Payment\DirectDebitData;
use Magento\Sales\Api\Data\CreditmemoInterface;
use Magento\Sales\Api\Data\InvoiceInterface;

interface DirectDebitDataProviderInterface
{
    public function getDirectDebitData(InvoiceInterface|CreditmemoInterface $document): ?DirectDebitData;
}

The returned DirectDebitData is created through the generated DirectDebitDataFactory:

Argument	Business term	Mandatory
`debtorIban`	BT-91 – account to be debited, must be a valid IBAN (BR-DE-20)	yes
`creditorReferenceId`	BT-90 – creditor identifier	yes
`mandateReference`	BT-89 – mandate reference	no

Unlike the two adapters, this extension point is registered as a preference:

<preference for="Geissweb\ElectronicInvoicing\Api\DirectDebitDataProviderInterface"
            type="Vendor\Module\Model\MyDirectDebitDataProvider"/>

XRechnung already considers the BG-19 group present as soon as one of the three fields is written – and then strictly requires BT-90 and BT-91 (BR-DE-30, BR-DE-31). Therefore return either complete data or null.

Without a registered implementation, the bundled default applies and always returns null: invoices are then written as a credit transfer as before. The same happens when an implementation returns incomplete data – this keeps the document compliant in any case. The reason is written to the log.

Register your own adapter

Implement the appropriate interface and register the class in the respective pool in the etc/di.xml of your module:

<type name="Geissweb\ElectronicInvoicing\Model\Adapter\AllowanceAdapterPool">
    <arguments>
        <argument name="adapters" xsi:type="array">
            <item name="custom" xsi:type="object">Vendor\Module\Model\Adapter\CustomAllowanceAdapter</item>
        </argument>
    </arguments>
</type>

For prepaid adapters, use Geissweb\ElectronicInvoicing\Model\Adapter\PrepaidAdapterPool analogously.

Via isEnabled(), the adapter can check whether the target module is installed/active and enabled in the configuration. This keeps the integration inactive as long as it is not needed.