B2bFatturazione-Dokumentation

Installation

Voraussetzungen

Magento 2.4.x — getestet mit 2.4.9, kompatibel mit vorherigen 2.4.*-Versionen. PHP 8.1–8.5. Kompatibel sowohl mit dem Standard-Luma-Theme als auch mit dem Hyvä-Theme.

Einrichtungsschritte

1. Fügen Sie die per E-Mail erhaltenen Zugangsdaten zu auth.json im Stammverzeichnis Ihres Magento-Projekts hinzu:

   { "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }

2. composer config repositories.codingrow composer https://repo.codingrow.com
3. composer require codingrow/module-b2bfatturazione
4. bin/magento module:enable Codingrow_B2bFatturazione
5. bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush
6. Fügen Sie Ihren Lizenzschlüssel in Admin → Stores → Configuration → Codingrow Extensions → B2bFatturazione → License → License Key ein, speichern Sie, dann bin/magento cache:flush. Der Schlüssel ist an die beim Kauf angegebene Domain gebunden — auf jeder anderen Domain bleibt das Modul installiert, aber seine Felder bleiben deaktiviert.
7. Wenn die Seite im production-Modus läuft, stellen Sie zusätzlich den statischen Inhalt erneut bereit: bin/magento setup:static-content:deploy -f.

Deinstallation

composer remove codingrow/module-b2bfatturazione dann bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush.

Dokumentation

Was es tut

Dies ist ein bewusst kleines, fokussiertes Modul: Es fügt fünf Felder hinzu — Kundentyp (Unternehmen/Privatperson), USt-IdNr., SDI-Code, PEC (zertifizierte E-Mail) und Steuernummer — zum Adressbuch des Kunden und zum Checkout (Rechnungs- und Lieferadresse), sowohl im Standard-Luma-Theme als auch in Hyvä. Es gibt keine Konfiguration über die Installation und das Einfügen des Lizenzschlüssels hinaus; es funktioniert direkt nach der Installation.

The same fields appear in checkout (billing and shipping) and in the admin customer address book.

Admin-Konfiguration

Es gibt keine Verhaltens-Konfiguration – die einzige Admin-Einstellung ist der Lizenzschlüssel. Alles Übrige (welche Felder erscheinen, wann sie Pflicht sind) ist automatisch.

GraphQL-/Headless- & React-Checkout-Kompatibilität

Die fünf B2B-Felder werden über die Core-GraphQL-Typen und -Mutations von Magento bereitgestellt — keine eigene API. Wenn Ihr Storefront auf GraphQL basiert (React Checkout oder ein beliebiges anderes Headless-/GraphQL-Frontend), lesen und schreiben Sie diese Felder genau wie jedes andere native Adressfeld, über die Mutations, die Sie bereits verwenden.

Felder lesen

customer_type, sdi, pec, codice_fiscale und fattura_richiesta werden direkt zu den Magento-eigenen Typen BillingCartAddress, ShippingCartAddress und CustomerAddress hinzugefügt:

{
  customerCart {
    billing_address {
      customer_type
      sdi
      pec
      codice_fiscale
      fattura_richiesta
    }
  }
}

{
  customer {
    addresses {
      customer_type
      sdi
      pec
      codice_fiscale
      fattura_richiesta
    }
  }
}

Felder schreiben

Dieselben fünf Felder werden zum Magento-eigenen Core-Typ CartAddressInput hinzugefügt, sodass sie zusammen mit den normalen Adressfeldern in den Standard-Warenkorb-Mutations übergeben werden — keine separate Mutation nötig:

mutation {
  setShippingAddressesOnCart(
    input: {
      cart_id: "abc123"
      shipping_addresses: [
        {
          address: {
            firstname: "Mario"
            lastname: "Rossi"
            street: ["Via Roma 1"]
            city: "Milano"
            postcode: "20100"
            country_code: "IT"
            telephone: "+390000000"
            customer_type: "azienda"
            sdi: "ABC1234"
            pec: "mario.rossi@pec.it"
            codice_fiscale: "RSSMRA80A01F205X"
          }
        }
      ]
    }
  ) {
    cart { id }
  }
}

Hinweise zur Implementierung

• All dies geschieht über offizielle Magento-Erweiterungspunkte (di.xml-Plugins auf Core-Schnittstellen wie Magento\QuoteGraphQl\Model\Cart\QuoteAddressFactory und Magento\CustomerGraphQl\Model\Customer\Address\ExtractCustomerAddressData) — nichts patcht oder kopiert den Core-GraphQL-Resolver-Code.
• Die serverseitige Validierung (z. B. „SDI oder PEC ist für einen Firmenkunden erforderlich") funktioniert unabhängig davon, welches Storefront die Mutation aufruft — REST, GraphQL oder der Standard-Luma- Checkout.
• fattura_richiesta (Rechnung angefordert) gilt nur für Privatkunden — Firmenkunden erhalten gesetzlich immer eine Rechnung, daher ist das Feld speziell für den Fall „privato" sinnvoll.

Genaue Adressanzeige im Admin

Die Standardzusammenfassung der Rechnungs-/Lieferadresse des Kunden unter Customers → All Customers → [customer] → Addresses sowie im Tab Customer View enthält jetzt auch die B2B-Felder — nicht nur die Basisadresse:

React Checkout: sofort einsatzbereit, ohne zusätzliche Entwicklung

Codingrow pflegt außerdem codingrow/module-react-checkout, ein kleines Begleitpaket, das das eigentliche B2B-Rechnungsformular (Kundentyp, USt-IdNr., SDI, PEC, Steuernummer) zum React Checkout von Hyvä hinzufügt — die Oberfläche über den oben dokumentierten GraphQL-Feldern. Installieren Sie beide zusammen, und das Rechnungsformular funktioniert sofort, ohne eigene Entwicklung.

React Checkout mit B2B-Unterstützung installieren

1. Beide Pakete anfordern:

   composer require hyva-themes/magento2-react-checkout codingrow/module-react-checkout

2. Fügen Sie den PHP-8.4/8.5-Kompatibilitäts-Patch zur composer.json im Projekt-Stammverzeichnis hinzu und führen Sie dann composer update --lock aus, damit er erfasst wird:

   "extra": {
       "patches": {
           "hyva-themes/magento2-react-checkout": {
               "PHP 8.4/8.5 compat": "vendor/codingrow/module-react-checkout/patches/react-checkout-php84-compat.patch"
           }
       }
   }

   (Erfordert cweagans/composer-patches; führen Sie zuerst composer require cweagans/composer-patches aus, falls noch nicht vorhanden.)
3. Aktivieren Sie die Module:

   bin/magento module:enable Codingrow_ReactCheckout Hyva_ReactCheckout
   bin/magento setup:upgrade

4. React Checkout aktivieren: bin/magento config:set hyva_react_checkout/general/enable 1
5. Die React-App bauen:

   cd vendor/codingrow/module-react-checkout/reactapp
   npm install
   npm run build

6. Statischen Inhalt neu bereitstellen — jedes Mal erforderlich, auch außerhalb des production-Modus; sonst kann der Browser weiterhin ein veraltetes Bundle laden:

   bin/magento setup:static-content:deploy -f en_US --theme <your-theme>

7. bin/magento cache:flush

Voraussetzungen: Magento 2.4.9, PHP 8.1–8.5 (einschließlich 8.4/8.5, über den enthaltenen Patch).