Entwickler

Die Erweiterung stellt drei Erweiterungspunkte bereit, über die eigene oder fremde Module angebunden werden – für Nachlässe, für bereits gezahlte Beträge und für SEPA-Lastschriftdaten. Die beiden Adapter-Interfaces werden per Dependency Injection in einen Pool registriert, der Lastschrift-Erweiterungspunkt über eine Preference.

Integrationsarten im Überblick

Bereich	Erweiterungspunkt	Behandlung
Gutscheine, Guthaben, Bonuspunkte	`PrepaidAdapterInterface`	BT-113 (Vorauszahlung)
Zusätzliche Nachlässe	`AllowanceAdapterInterface`	Nachlass auf Belegebene (BG-20)
SEPA-Lastschrift	`DirectDebitDataProviderInterface`	BG-19 (BT-89/90/91)
PDF-Erweiterungen für Rechnungsdokumente	Plugin (ohne eigenes Interface)	Hybrides ZUGFeRD-PDF mit eingebettetem XML

Das Einbetten in das PDF funktioniert mit dem Standard-PDF von Magento sowie mit mehreren gängigen PDF-Erweiterungen; dafür ist auf Ihrer Seite nichts zu implementieren.

AllowanceAdapterInterface

Für Beträge, die als Nachlass auf Belegebene abgebildet werden sollen.

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() liefert je Nachlass ein Array mit den Schlüsseln amount (float, ohne USt.), vat_category (EN-16931-Kategorie, z. B. S), vat_rate (float, z. B. 19.0), reason (Text) und reason_code (z. B. DISCOUNT).

PrepaidAdapterInterface

Für bereits gezahlte Beträge (BT-113) wie Gutscheine, Guthaben oder Bonuspunkte.

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;
}

Beide Interfaces liegen im Namespace Geissweb\ElectronicInvoicing\Api. getPriority() steuert die Ausführungsreihenfolge – kleinere Werte = höhere Priorität (Standard 100).

DirectDebitDataProviderInterface

Für die SEPA-Lastschriftangaben (BG-19). Magento kennt keine eigene Lastschriftzahlung, daher kann die Erweiterung Mandatsreferenz, Gläubiger-Identifikationsnummer und die zu belastende IBAN nicht selbst ermitteln. Betreiben Sie eine eigene Lastschriftlösung, liefern Sie die Werte über diesen Erweiterungspunkt.

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;
}

Das zurückgegebene DirectDebitData wird über die generierte DirectDebitDataFactory erzeugt:

Argument	Geschäftsbegriff	Pflicht
`debtorIban`	BT-91 – zu belastendes Konto, muss eine gültige IBAN sein (BR-DE-20)	ja
`creditorReferenceId`	BT-90 – Gläubiger-Identifikationsnummer	ja
`mandateReference`	BT-89 – Mandatsreferenz	nein

Anders als die beiden Adapter wird dieser Erweiterungspunkt als Preference registriert:

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

XRechnung wertet die Gruppe BG-19 bereits als vorhanden, sobald eines der drei Felder geschrieben wird – und verlangt dann zwingend BT-90 und BT-91 (BR-DE-30, BR-DE-31). Liefern Sie deshalb entweder vollständige Daten oder null.

Ohne registrierte Implementierung greift die mitgelieferte Standardvariante, die immer null zurückgibt: Rechnungen werden dann wie bisher als Überweisung ausgewiesen. Dasselbe passiert, wenn eine Implementierung unvollständige Daten liefert – so bleibt das Dokument in jedem Fall regelkonform. Der Grund wird protokolliert.

Eigenen Adapter registrieren

Implementieren Sie das passende Interface und registrieren Sie die Klasse im jeweiligen Pool in der etc/di.xml Ihres Moduls:

<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>

Für Vorauszahlungs-Adapter verwenden Sie analog Geissweb\ElectronicInvoicing\Model\Adapter\PrepaidAdapterPool.

Über isEnabled() kann der Adapter prüfen, ob das Zielmodul installiert/aktiv und in der Konfiguration freigeschaltet ist. So bleibt die Integration inaktiv, solange sie nicht gebraucht wird.