Italy Invoices (FatturaPA / SdI via Invoicetronic)

Official2 toolsLive

by junter1989k-ai · JavaScript

Italy FatturaPA invoices for AI agents: build FPR12 XML, transmit to the SdI, query status.

Topics

ai-agentclaudee-invoiceinvoiceitalymcpmcp-servertaxwishpool

Captured live from the server via tools/list.

create_invoice

Issue an Italy B2B electronic invoice (fattura elettronica) in FatturaPA format (FPR12) and transmit it to the national SdI (Sistema di Interscambio) via Invoicetronic. Builds the FatturaPA XML (seller/buyer P.IVA + optional Codice Fiscale, address, line items, IVA breakdown) and uploads it under your own Invoicetronic API key. Bring your own credential as header x-invoicetronic-key — ik_test_ keys are free sandbox (no fiscal effect), ik_live_ keys transmit real invoices to the SdI (same base URL; the key prefix selects the environment). Italian IVA rates supported: 22 (ordinaria), 10, 5, 4 (ridotte). Amounts are in EUR. Transmission is asynchronous: this returns a send id — poll query_invoice with it to learn the SdI outcome (SENT / DELIVERED / REJECTED / NOT_DELIVERED). There is no cancel at the SdI level: to reverse an invoice you issue a credit note (nota di credito) as a new invoice.

Parameters23

seller_name	string	required	Seller legal name / denominazione (CedentePrestatore).
seller_vat	string	required	Seller Partita IVA (P.IVA), 11 digits, e.g. 12345678903. IT prefix optional.
seller_tax_code	string	optional	Optional seller Codice Fiscale (11 digits for companies or 16 chars for individuals).
seller_address	string	required	Seller street address (Sede/Indirizzo).
seller_cap	string	required	Seller postal code / CAP, 5 digits.
seller_city	string	required	Seller city / Comune.
seller_province	string	optional	Optional seller province, 2-letter code (e.g. MI, RM).
seller_regime	string	optional	Seller tax regime code (RegimeFiscale). Default RF01 (ordinario). Others: RF19 (forfettario), etc.
customer_name	string	required	Buyer legal name / denominazione (CessionarioCommittente).
customer_vat	string	optional	Buyer Partita IVA (P.IVA), 11 digits. Provide this and/or customer_tax_code.
customer_tax_code	string	optional	Buyer Codice Fiscale (16 chars for individuals, 11 digits for companies). Provide this and/or customer_vat.
customer_address	string	required	Buyer street address (Sede/Indirizzo).
customer_cap	string	required	Buyer postal code / CAP, 5 digits.
customer_city	string	required	Buyer city / Comune.
customer_province	string	optional	Optional buyer province, 2-letter code.
customer_country	string	optional	Buyer country code (Nazione). Default IT.
codice_destinatario	string	optional	Recipient SdI Codice Destinatario, 7 chars. Default 0000000 (recipient retrieves from the tax drawer / cassetto fiscale, or set pec_destinatario).
pec_destinatario	string	optional	Optional recipient PEC email — used when codice_destinatario is 0000000 to route the invoice by certified email.
invoice_number	string	optional	Invoice number (Numero). Auto-generated if omitted.
issue_date	string	optional	Invoice date (Data), YYYY-MM-DD. Default: today (UTC).
document_type	string	optional	FatturaPA TipoDocumento. Default TD01 (fattura). Use TD04 for a credit note (nota di credito).
currency	string	optional	Document currency (Divisa). Default EUR.
lines	array	required	Invoice line items. Each: description, unit_price (net, IVA-exclusive, EUR), vat_rate (22\|10\|5\|4), optional quantity (default 1).

Raw schema

{
  "type": "object",
  "properties": {
    "seller_name": {
      "type": "string",
      "description": "Seller legal name / denominazione (CedentePrestatore)."
    },
    "seller_vat": {
      "type": "string",
      "description": "Seller Partita IVA (P.IVA), 11 digits, e.g. 12345678903. IT prefix optional."
    },
    "seller_tax_code": {
      "type": "string",
      "description": "Optional seller Codice Fiscale (11 digits for companies or 16 chars for individuals)."
    },
    "seller_address": {
      "type": "string",
      "description": "Seller street address (Sede/Indirizzo)."
    },
    "seller_cap": {
      "type": "string",
      "description": "Seller postal code / CAP, 5 digits."
    },
    "seller_city": {
      "type": "string",
      "description": "Seller city / Comune."
    },
    "seller_province": {
      "type": "string",
      "description": "Optional seller province, 2-letter code (e.g. MI, RM)."
    },
    "seller_regime": {
      "type": "string",
      "description": "Seller tax regime code (RegimeFiscale). Default RF01 (ordinario). Others: RF19 (forfettario), etc."
    },
    "customer_name": {
      "type": "string",
      "description": "Buyer legal name / denominazione (CessionarioCommittente)."
    },
    "customer_vat": {
      "type": "string",
      "description": "Buyer Partita IVA (P.IVA), 11 digits. Provide this and/or customer_tax_code."
    },
    "customer_tax_code": {
      "type": "string",
      "description": "Buyer Codice Fiscale (16 chars for individuals, 11 digits for companies). Provide this and/or customer_vat."
    },
    "customer_address": {
      "type": "string",
      "description": "Buyer street address (Sede/Indirizzo)."
    },
    "customer_cap": {
      "type": "string",
      "description": "Buyer postal code / CAP, 5 digits."
    },
    "customer_city": {
      "type": "string",
      "description": "Buyer city / Comune."
    },
    "customer_province": {
      "type": "string",
      "description": "Optional buyer province, 2-letter code."
    },
    "customer_country": {
      "type": "string",
      "description": "Buyer country code (Nazione). Default IT."
    },
    "codice_destinatario": {
      "type": "string",
      "description": "Recipient SdI Codice Destinatario, 7 chars. Default 0000000 (recipient retrieves from the tax drawer / cassetto fiscale, or set pec_destinatario)."
    },
    "pec_destinatario": {
      "type": "string",
      "description": "Optional recipient PEC email — used when codice_destinatario is 0000000 to route the invoice by certified email."
    },
    "invoice_number": {
      "type": "string",
      "description": "Invoice number (Numero). Auto-generated if omitted."
    },
    "issue_date": {
      "type": "string",
      "description": "Invoice date (Data), YYYY-MM-DD. Default: today (UTC)."
    },
    "document_type": {
      "type": "string",
      "description": "FatturaPA TipoDocumento. Default TD01 (fattura). Use TD04 for a credit note (nota di credito)."
    },
    "currency": {
      "type": "string",
      "description": "Document currency (Divisa). Default EUR."
    },
    "lines": {
      "type": "array",
      "minItems": 1,
      "description": "Invoice line items. Each: description, unit_price (net, IVA-exclusive, EUR), vat_rate (22|10|5|4), optional quantity (default 1).",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "Line description (Descrizione)."
          },
          "unit_price": {
            "type": "number",
            "description": "Net unit price in EUR, IVA-exclusive (PrezzoUnitario)."
          },
          "vat_rate": {
            "type": "number",
            "description": "IVA rate percent: 22 (ordinaria), 10, 5, or 4 (ridotte)."
          },
          "quantity": {
            "type": "number",
            "description": "Quantity (Quantita). Default 1."
          }
        },
        "required": [
          "description",
          "unit_price",
          "vat_rate"
        ]
      }
    }
  },
  "required": [
    "seller_name",
    "seller_vat",
    "seller_address",
    "seller_cap",
    "seller_city",
    "customer_name",
    "customer_address",
    "customer_cap",
    "customer_city",
    "lines"
  ]
}

query_invoice

Check the SdI processing status of an invoice sent by create_invoice, using its send id. FatturaPA transmission is asynchronous. Status values: SENT (Inviato — accepted by the SdI, not yet delivered to the recipient; poll again shortly); DELIVERED (Consegnato — delivered to the recipient, the invoice is fiscally complete); REJECTED (Scartato — the SdI rejected it for a validation error; fix the data and create_invoice again); NOT_DELIVERED (ImpossibilitaDiRecapito / MancataConsegna — the invoice is legally valid and available in the recipient's tax drawer, but could not be pushed to their receiving system); PROCESSING (no SdI notification yet — poll again shortly). Safe to call anytime.

Parameters1

send_id

string

required

The send id returned by create_invoice.

Raw schema

{
  "type": "object",
  "properties": {
    "send_id": {
      "type": "string",
      "description": "The send id returned by create_invoice."
    }
  },
  "required": [
    "send_id"
  ]
}

README.md5 KBView on GitHub

Italy Invoice MCP 🇮🇹 — How can my AI agent issue a FatturaPA fattura elettronica in Italy?

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "italy-invoice": {
      "type": "http",
      "url": "https://inv-it.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/italy-invoice-mcp && cd italy-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent issue Italy FatturaPA electronic invoices (fattura elettronica) and transmit them to the national SdI (Sistema di Interscambio) via Invoicetronic. It builds FatturaPA FPR12 XML (Agenzia delle Entrate v1.2 schema) and sends it under the merchant's own Invoicetronic API key. Stateless, bring-your-own credentials, never stores anything.

Live endpoint: https://inv-it.wishpool.app/mcp · Registry: app.wishpool/italy-invoice-mcp

Quick start

json

{
  "mcpServers": {
    "italy-invoice": {
      "type": "http",
      "url": "https://inv-it.wishpool.app/mcp",
      "headers": {
        "x-invoicetronic-key": "ik_test_<your Invoicetronic key>"
      }
    }
  }
}

Sign up at invoicetronic.com for a free ik_test_ sandbox key (no fiscal effect). An ik_live_ key transmits real invoices to the SdI — the base URL is the same, the key prefix selects the environment. Authentication is HTTP Basic with the key as the username (empty password). Your key stays with you and travels per-request; this server never stores it.

Tools

Tool	What it does
`create_invoice`	Build a FatturaPA FPR12 invoice from seller + buyer (P.IVA / Codice Fiscale, address) and line items (description, net unit price, IVA rate 22/10/5/4, quantity), then transmit to the SdI via Invoicetronic. Returns `send_id` + computed IVA totals (`imponibile`, `imposta`, `totale`).
`query_invoice`	Poll SdI status by `send_id`: `SENT` (Inviato), `DELIVERED` (Consegnato), `REJECTED` (Scartato), `NOT_DELIVERED` (ImpossibilitaDiRecapito), or `PROCESSING` (no notification yet).

Amounts are in EUR. Italian IVA rates: 22 (ordinaria), 10, 5, 4 (ridotte). Seller/buyer identified by Partita IVA and/or Codice Fiscale.

No cancel at the SdI level — to reverse an invoice you issue a credit note (nota di credito, TipoDocumento TD04) as a new invoice. Zero-rated / exempt IVA (needs a Natura code) is out of scope in v1.

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them.

IVA math (deterministic)

Per line PrezzoTotale = round2(quantity × unit_price); grouped by rate into DatiRiepilogo (ImponibileImporto, Imposta = round2(imponibile × rate / 100)); document total ImportoTotaleDocumento = imponibile + imposta. Examples:

100 + 50 both @22% → imponibile 150.00 / imposta 33.00 / totale 183.00
200 @22% + 100 @10% → imponibile 300.00 / imposta 54.00 (44 + 10) / totale 354.00
2×50 @22% + 3×10 @10% + 1×25 @4% → imponibile 155.00 / imposta 26.00 (22 + 3 + 1) / totale 181.00

Endpoints wrapped (Invoicetronic REST)

Base: https://api.invoicetronic.com/v1 (single base URL; auth = HTTP Basic, username = API key, empty password)
Send: POST /send — JSON { file_name, payload (base64 FatturaPA XML), encoding: "base64", meta_data } → { id, ... }
Query: GET /update?send_id={id} — SdI notification history (state: Inviato / Consegnato / Scartato / ImpossibilitaDiRecapito)
Pre-flight validation: POST /send may reply 422 Unprocessable Entity for a FatturaPA rule violation
(Inbound GET /receive exists for received invoices; not wrapped as a tool in v1.)

Develop

bash

node test/serve.js   # local server on :3234
node test/e2e.js     # IVA math + FatturaPA XML structure + protocol + validation + policy + fake-key live probe

Safety

Pure stateless translation layer over the Invoicetronic REST API (which wraps the national SdI). The API key travels per-request in a header, nothing is stored, and funds are never touched — this issues tax invoices, it does not move money. Privacy policy.

Sister servers

Local invoices, one family: Mexico CFDI (inv-mx) · Romania e-Factura (inv-ro) · Brazil NF-e (inv-br) · Chile DTE (inv-cl) · India GST (inv-in). Local payments in 81 countries: mcp.wishpool.app.

MIT licensed.

Install

Tools (2)

create_invoicequery_invoice

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-it.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "italy-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-it.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.