Développeur

L'extension propose trois points d'extension permettant de raccorder vos propres modules ou des modules tiers – pour les remises, pour les montants déjà réglés et pour les données de prélèvement SEPA. Les deux interfaces d'adaptateur sont enregistrées dans un pool par injection de dépendances, le point d'extension de prélèvement via une preference.

Types d'intégration

Domaine	Point d'extension	Traitement
Bons, avoirs, points de fidélité	`PrepaidAdapterInterface`	BT-113 (acompte)
Remises supplémentaires	`AllowanceAdapterInterface`	Remise au niveau du document (BG-20)
Prélèvement SEPA	`DirectDebitDataProviderInterface`	BG-19 (BT-89/90/91)
Extensions PDF pour les documents de facture	Plugin (sans interface dédiée)	PDF ZUGFeRD hybride avec XML intégré

L'intégration dans le PDF fonctionne avec le PDF standard de Magento ainsi qu'avec plusieurs extensions PDF courantes ; rien n'est à implémenter de votre côté.

AllowanceAdapterInterface

Pour les montants qui doivent être représentés comme une remise au niveau du document.

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() fournit, pour chaque remise, un tableau avec les clés amount (float, hors TVA), vat_category (catégorie EN 16931, par ex. S), vat_rate (float, par ex. 19.0), reason (texte) et reason_code (par ex. DISCOUNT).

PrepaidAdapterInterface

Pour les montants déjà payés (BT-113) tels que bons, avoirs ou points de fidélité.

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

Les deux interfaces se trouvent dans l'espace de noms Geissweb\ElectronicInvoicing\Api. getPriority() pilote l'ordre d'exécution – valeurs plus petites = priorité plus élevée (par défaut 100).

DirectDebitDataProviderInterface

Pour les données de prélèvement SEPA (BG-19). Magento ne connaît pas de paiement par prélèvement natif ; l'extension ne peut donc pas déterminer elle-même la référence de mandat, l'identifiant du créancier ni le compte à débiter. Si vous exploitez votre propre solution de prélèvement, fournissez les valeurs via ce point d'extension.

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

L'objet DirectDebitData retourné est créé via la fabrique générée DirectDebitDataFactory :

Argument	Terme métier	Obligatoire
`debtorIban`	BT-91 – compte à débiter, doit être un IBAN valide (BR-DE-20)	oui
`creditorReferenceId`	BT-90 – identifiant du créancier	oui
`mandateReference`	BT-89 – référence de mandat	non

Contrairement aux deux adaptateurs, ce point d'extension s'enregistre comme preference :

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

XRechnung considère le groupe BG-19 comme présent dès qu'un seul des trois champs est écrit – et exige alors impérativement BT-90 et BT-91 (BR-DE-30, BR-DE-31). Retournez donc soit des données complètes, soit null.

Sans implémentation enregistrée, la variante par défaut livrée s'applique et retourne toujours null : les factures sont alors établies comme un virement, comme auparavant. Il en va de même lorsqu'une implémentation fournit des données incomplètes – le document reste ainsi conforme dans tous les cas. Le motif est consigné dans le journal.

Enregistrer son propre adaptateur

Implémentez l'interface adaptée et enregistrez la classe dans le pool correspondant dans le fichier etc/di.xml de votre 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>

Pour les adaptateurs d'acompte, utilisez de manière analogue Geissweb\ElectronicInvoicing\Model\Adapter\PrepaidAdapterPool.

Via isEnabled(), l'adaptateur peut vérifier si le module cible est installé/actif et activé dans la configuration. L'intégration reste ainsi inactive tant qu'elle n'est pas nécessaire.