FatturaPA SdI for WooCommerce — Italian FatturaPA e-invoices from orders, checked against the official XSD

FatturaPA SdI for WooCommerce is a plugin for shops in Italy that sell on WooCommerce and issue electronic invoices through the Sistema di Interscambio (SdI) of the Agenzia delle Entrate. It turns an order into an invoice in the official FatturaPA 1.2.3 format for the private sector (FPR12, “fattura ordinaria”), checks it against the official XSD schema and helps you get it to the SdI — with no paid invoicing service in between and no monthly subscription. The invoice register, the XML under its SdI file name and the SdI receipts stay in your shop.

How the invoice reaches the SdI. The plugin does not use the direct SdI channels (web service or SFTP): they need a separate accreditation that a shop usually does not have. In the free version you upload the finished XML to the SdI yourself — for example in “Fatture e corrispettivi” — and then upload the XML receipt the SdI returned to the plugin. In Pro the plugin sends the invoice from your own PEC mailbox (the channel open to every business) and reads the receipts from it, or hands the XML to your intermediary through a webhook.

What you need. An Italian company or sole trader with a Partita IVA; WooCommerce taxes with the Italian rates; prices in EUR. For sending in Pro — your PEC mailbox with SMTP and IMAP access from your provider, or an intermediary that accepts the XML at a webhook address.

Honestly about testing. The plugin was tested on a local WooCommerce shop on PHP 8.3 and 7.4: 153 browser checks, classic and block checkout, the admin in English and Italian. Every XML from the test orders — companies with an SDI code, customers with a CF, PEC, forfettario with stamp duty, credit notes, foreign customers — passed the official FatturaPA 1.2.3 XSD schema with two independent validators. The PEC channel was tested on a test mail server (real SMTP and IMAP), and the SdI receipts were built on the official message schema. The plugin has not yet worked with the real SdI or with real PEC providers: that takes the PEC mailbox of an Italian business. Start with the Pro trial on your own company — if the SdI answers differently from the specification, we fix it quickly.

Responsibility for the content of the invoice stays with the seller. The plugin builds the invoice from the WooCommerce order data and from the settings you choose: Natura codes for lines without VAT, legal references, stamp duty, when invoices are issued, foreign customers. These are decisions for your commercialista — show them the settings before the first real invoice.

What the admin gets

• WooCommerce → FatturaPA: the “Invoices”, “Settings” and “Licence” tabs.
• Invoice register: number and document type (invoice or credit note), order, customer with CF or P.IVA, total, status, file name and Id SdI; a status filter and search by number, file, Id SdI, customer or order. Links to the details with the full XML and to the file download.
• “Send / read receipts now” (Pro) sends the queue and reads the receipts right away, without waiting for cron.
• Notices at the top of the admin: how invoices currently reach the SdI, how many are not transmitted yet, rejected or undelivered invoices, the last transmission problem.

Every order has a “FatturaPA” box: invoice number, status, XML file name and the actions — “Details”, “XML”, “Mark as uploaded”, “Rebuild”, “Discard”. An order without an invoice shows a “Create FatturaPA” button or the reason no invoice was created. The order notes record every step: invoice created, transmitted, delivered or rejected with the error code.

An invoice the SdI rejected (an NS receipt) counts as not issued. The error list from the receipt is shown in the register and in the order notes. Once the order is fixed, “Rebuild and send” rebuilds the invoice with the same number and date and a new file name, as the SdI requires; an invoice you no longer need — “Discard”.

What the customer sees

The checkout gets an “I need an invoice (fattura elettronica)” checkbox. Until it is ticked, the invoice fields stay hidden and the order goes through as usual. Once ticked — Codice fiscale, Partita IVA, Codice destinatario SDI, PEC and, while WooCommerce hides its own “Company” field, “Company name (for the invoice)”. For an address outside Italy the SDI and PEC fields are hidden.

• The codice fiscale is checked by its check character, omocodia included; the Partita IVA by its check digit, with an IT prefix removed automatically.
• A Partita IVA without a company name does not pass; the SDI code must be exactly 7 letters or digits; the SdI address (@pec.fatturapa.it) is not accepted as the customer’s PEC.
• A CF typed in lower case appears in upper case on the invoice.
• Works on the classic and the block checkout. On the block checkout the fields stay hidden until the checkbox is ticked on WooCommerce 9.9+; on older versions they are always visible, with the same server-side checks.

If another plugin already collects the invoice data, the fields can be switched off: the plugin reads the known order meta fields with the CF, P.IVA, SDI code and PEC.

How it works — step by step

1. Seller. WooCommerce → FatturaPA → Settings: Partita IVA, company name or the name of a natural person, RegimeFiscale, address with CAP and province, REA for companies, IBAN for bank transfers.
2. Numbering. A number format such as WEB{N}/{YYYY} with a counter that restarts at 1 every year. The SdI refuses a second invoice with the same number in the same year, so keep the year in the format.
3. VAT and Natura. Rates come from the WooCommerce taxes of each order; for lines without VAT you choose the Natura code and, if needed, your own legal reference.
4. Channel. Free — manual upload. Pro — PEC: the address, your provider’s SMTP and IMAP servers, the password and the “Test the PEC connection” button. Or an intermediary: the webhook address and a token.
5. Order status. When the order becomes “Completed” (or “Processing” — your choice), the plugin checks the data against the offline SdI controls, builds the XML with the next number and validates it against the XSD. No number is spent until the data passes.
6. Delivery to the SdI. Free: you upload the XML to the SdI and click “Mark as uploaded”. Pro: the plugin sends an e-mail with the XML to the SdI address; the first invoice goes to sdi01@pec.fatturapa.it, the next ones to the address the SdI answered from.
7. Receipt. RC — invoice delivered; NS — rejected with an error list; MC — not delivered to the customer, the invoice is issued and waits in their reserved area. Free: you upload the XML receipts to the register (several at a time, matched by file name). Pro: the plugin reads them from the PEC mailbox by itself.
8. Failures. The PEC server is down — the invoice waits in the queue and is retried with pauses from 5 minutes to 12 hours. A wrong password — the invoice is marked as failed without retries, and a notice appears in the admin.

In the free version the register tells you what to do: upload each XML to the SdI, mark it “Mark as uploaded” and record the receipt. The same receipt uploaded twice changes nothing, and a late receipt for an old file does not override the status of the current one.

VAT and stamp duty. Several rates on one invoice, totals per rate and Natura code, rounding to the order total. For forfettario (RF19) and minimi (RF02) sellers every line goes without VAT with the N2.2 code and the legal reference. When the lines without VAT (N2.1, N2.2, N3.5, N3.6, N4) together exceed 77.47 EUR, a 2 EUR BolloVirtuale is added to the invoice — you pay the stamp duty itself quarterly with F24.

Pro. A WooCommerce refund — by item or by amount — produces a TD04 credit note linked to the invoice (DatiFattureCollegate). The credit note is created automatically once the invoice has an RC or MC receipt; otherwise with the “Create credit note” button on the order. Customers outside Italy get the code XXXXXXX, their foreign VAT number or the shop’s customer reference, CAP 00000 and the Natura codes you chose for sales to EU businesses, exports and services. Orders taxed at another EU country’s rate (OSS) are not invoiced, and the plugin explains why.

In My Account the customer sees the invoice sent through the SdI and downloads a courtesy copy (copia di cortesia) — only the owner of the order can. For a forfettario seller Pro can add the 2 EUR stamp duty to the cart as a separate line when the amount without VAT exceeds the threshold.

Under the hood

• FatturaPA 1.2.3, FPR12 following the Agenzia delle Entrate technical specifications 1.9.1: TD01 invoice and TD04 credit note. The official XSD schema ships with the plugin, so validation runs locally, without the network.
• Offline SdI controls before the number: Natura vs rate, amounts and rounding, buyer identifier, recipient code and PEC, the generic Natura codes the SdI refuses. Only after these does the invoice get a number and go through the XSD.
• File names — IT + codice fiscale of the transmitter + progressive; every resend gets a new name. The series letters of the progressive can be changed if another program uses the same codice fiscale.
• PEC in Pro: SMTP through WordPress’s PHPMailer, IMAP with the plugin’s own client (no php-imap extension needed), the PEC envelope unpacked down to the XML receipt. Mailbox passwords and tokens are stored encrypted (AES-256 with your site’s keys).
• Intermediary in Pro: the XML is POSTed to your address with a Bearer token and X-FatturaPA-* headers; receipts come back to the REST address /wp-json/ccfp/v1/receipt with a token.
• SdI receipts are stored in the shop database, not as files under wp-content/uploads, so there is no direct link to them. Only a shop manager can download them from the admin; a database backup is also a backup of the receipts.
• Locked numbering: two orders in the same second never get the same number; credit notes have their own counter.
• Simulation mode: the CCFP_SDI_MOCK constant in wp-config.php simulates SdI answers (rc, ns, mc, silent, down, auth) — nothing leaves the site.
• Uninstalling removes passwords, tokens and cron jobs; the invoice register and the receipts stay as accounting records. The CCFP_DELETE_DATA constant removes everything.

How to install

1. Plugins → Add New → Upload Plugin: choose fatturapa-sdi-for-woocommerce-1.0.0.zip and activate it (WooCommerce must be active).
2. WooCommerce → FatturaPA → Settings: seller data (Partita IVA, name, RegimeFiscale, address with CAP and province), numbering, VAT and Natura settings.
3. Choose which orders get an invoice: companies and customers who tick the box, every order, or data from another plugin.
4. Choose the channel: manual upload (Free) or PEC or an intermediary (Pro). For PEC — “Test the PEC connection”.
5. Switch on “Create FatturaPA invoices”, place a test order with the invoice box ticked and set it to “Completed” — the invoice shows up in the register and on the order.
6. Show the VAT, Natura and stamp duty settings to your accountant before the first real invoice.
7. For Pro: paste the licence key from the e-mail after payment or start the 7-day trial.