Build the DatiTrasmissione block required in every FatturaPA header.

Use this as step 3 in the invoice generation workflow, after generate_progressivo_invio() and before validate_cedente_prestatore(). Use lookup_codice_destinatario() first to confirm the recipient code format.

Validates: formato_trasmissione must be 'FPA12' or 'FPR12'; progressivo_invio must be 1–10 alphanumeric characters; pec_destinatario is required when codice_destinatario is '0000000'.

On success returns {'DatiTrasmissione': {...}} ready to pass to generate_fattura_xml(). On failure returns {'error': ''} — do not proceed to XML generation.

Validate and build the CedentePrestatore (seller) block for FatturaPA.

Use this as step 4 in the invoice generation workflow, after build_transmission_header() and before validate_cessionario(). Call get_regime_fiscale_codes() first if you need to look up the RF code.

Gruppo IVA (VAT-group) sellers: when id_codice is a VAT-group IdFiscaleIVA, pass codice_fiscale set to the Codice Fiscale of the specific participating member company issuing this invoice, never the group's own CF. This mirrors the buyer-side rule enforced by SdI scarto code 00327 (see mcp_fattura_elettronica_it.sdi.notifications.SCARTO_CODE_REFERENCE); SdI does not publish an equivalent seller-side control code, but the same distinction applies structurally.

Validates: either denominazione or both nome+cognome must be provided (mutually exclusive); regime_fiscale must be a valid RF01–RF19 code; Italian Partita IVA (id_paese='IT') must be exactly 11 digits; codice_fiscale, if provided, must be 16 alphanumeric characters (individuals) or 11 digits (companies/VAT groups).

On success returns {'CedentePrestatore': {...}} ready to pass to generate_fattura_xml(). On failure returns {'error': ''} listing all validation issues joined by '; '.

Validate and build the CessionarioCommittente (buyer) block for FatturaPA.

Use this as step 5 in the invoice generation workflow, after validate_cedente_prestatore() and before build_dati_generali().

Validates: either denominazione or both nome+cognome must be provided (mutually exclusive); at least one tax identifier (id_codice with id_paese, or codice_fiscale) is required; id_codice requires id_paese to be set.

Italian B2C buyers with only a CodiceFiscale: set codice_fiscale and leave id_paese/id_codice empty. Foreign B2B buyers: set id_paese + id_codice. For B2G invoices (FPA12): routing to the Public Administration is via a 6-char IPA office CodiceDestinatario in build_transmission_header(), not via this tool — look up the code at https://www.indicepa.gov.it.

Gruppo IVA (VAT-group) buyers: when id_paese/id_codice are omitted and codice_fiscale is an 11-digit (company-format) code, this may be a VAT-group's own CF rather than a participating member's. SdI rejects that combination with scarto code 00327 (see mcp_fattura_elettronica_it.sdi.notifications. SCARTO_CODE_REFERENCE) — this tool cannot validate VAT-group membership offline, so it only warns on the detectable structural precondition (IdFiscaleIVA absent

• 11-digit codice_fiscale); the returned 'warnings' list flags this case. Confirm codice_fiscale identifies the specific member company, not the group itself.

On success returns {'CessionarioCommittente': {...}} ready for generate_fattura_xml(), plus 'warnings' (list[str]) when the 00327 structural precondition is detected. On failure returns {'error': ''} listing all issues joined by '; '.

Return the complete list of RegimeFiscale codes (RF01–RF19) with descriptions.

Call this to look up the correct fiscal regime code before calling validate_cedente_prestatore(). Every Italian seller must declare a regime: RF01 (ordinary) covers most companies; RF19 (forfettario) covers flat-rate sole traders; all other codes cover specialised VAT regimes.

Always succeeds. Returns {'codes': [{'code': str, 'description': str}, ...], 'total': int}.

Validate an Italian Partita IVA for format (11 digits) and modulo-10 checksum.

Call this as an early sanity check on the seller's VAT number before passing it to validate_cedente_prestatore(). Strips whitespace before validation.

Applies the official Agenzia delle Entrate control algorithm: odd-position digits are taken as-is; even-position digits are doubled (subtract 9 if > 9); the last digit must equal (10 - sum % 10) % 10.

On success returns {'valid': true, 'value': ''}. On failure returns {'valid': false, 'value': '', 'error': ''}.

Generate a ProgressivoInvio identifier for the DatiTrasmissione block.

Use this as step 2 in the invoice generation workflow, before build_transmission_header(). The SDI requires each ProgressivoInvio to be unique per transmitter Partita IVA — in production, pass an explicit monotonically increasing sequence number; use the random default only for testing.

prefix (optional): alphabetic 1–3 char prefix, e.g. 'INV' → 'INV00001'. sequence (optional): integer 1–9999999; random 5-digit value if omitted. Total length must not exceed 10 characters.

On success returns {'progressivo_invio': str, 'length': int}. On failure (invalid prefix) returns {'error': ''}.

Validate the format of a CodiceDestinatario (SDI recipient code) or PEC address.

Call this before build_transmission_header() to confirm the recipient routing type and that the code or PEC address is correctly formatted. At least one of codice or pec must be provided.

Routing rules:

• codice is 6 alphanumeric chars (e.g. 'A1B2C3') → routing_type: 'SDI_CODE' (PA/IPA, FPA12)

• codice is 7 alphanumeric chars (e.g. 'X1Y2Z3W') → routing_type: 'SDI_CODE' (B2B intermediary, FPR12)

• codice is '0000000' (7 zeros) → routing_type: 'PEC'; pec_destinatario is then mandatory in build_transmission_header()

• pec only (no codice) → validates email format, routing_type: 'PEC'

IPA note: 6-char = IPA code (PA), 7-char = B2B intermediary code (FPR12 routing). PA office codes can be looked up at https://www.indicepa.gov.it. This tool performs format validation only, no live query against the SDI SOAP directory service or the IPA registry (planned for a future release).

Per-channel cap (reference only, not enforced here — this tool validates the format of a single code, not channel-wide allocation): per AdE Specifiche Tecniche 1.9.1 (in force 2026-05-15), an accredited reception channel (WS or SFTP) may request a maximum of 300 CodiceDestinatario codes via the Sistema di Accreditamento once it has passed to production. This cap is unrelated to, and does not change, the per-invoice 6/7-character format validated above.

On success returns a dict with 'routing_type', 'codice_destinatario' and/or 'pec_destinatario', and a 'note' with usage guidance. On invalid input returns {'error': ''}.

Build the DatiGenerali block required in every FatturaElettronicaBody.

Use this as step 6 in the invoice generation workflow, after validate_cessionario() and before add_linea_dettaglio(). Call get_tipo_documento_codes() first to select the correct TD code (most invoices use TD01; credit notes use TD04; professional fee invoices use TD06).

For credit notes (TD04) or debit notes (TD05), set id_documento_riferimento to the original invoice number and data_documento_riferimento to its issue date.

Validates: tipo_documento must be a valid TD01–TD28 code; data must be YYYY-MM-DD; numero must not exceed 20 characters.

On success returns {'DatiGenerali': {...}} ready for generate_fattura_xml(). On failure returns {'error': ''}.

Return the complete list of document type codes (TD01–TD28) with descriptions and use cases.

Call this to choose the correct TipoDocumento before calling build_dati_generali(). Common codes: TD01 (standard invoice), TD04 (credit note), TD05 (debit note), TD06 (professional fee), TD16–TD19 (reverse charge self-invoices), TD28 (San Marino).

Always succeeds. Returns {'codes': [{'code', 'description', 'use_case'}, ...], 'total': int}.

Build a single DettaglioLinee (line item) entry for the FatturaElettronicaBody.

Use this as step 7 in the invoice generation workflow — call once per line item after build_dati_generali(). Collect all returned dicts into a list and pass it to compute_totali() (step 8) and then generate_fattura_xml() (step 10).

numero_linea must be sequential starting at 1; do not reuse numbers in the same invoice. prezzo_totale must be provided explicitly (not computed); use negative values for credit notes. When aliquota_iva is 0.0, natura is required — call get_natura_codes() to select the code. Set ritenuta='SI' on lines subject to withholding tax and include the DatiRitenuta block from check_ritenuta_acconto() when generating XML. altri_dati_gestionali (optional): structured management data entries, emitted after Natura in the XSD element order. See build_sport_worker_exemption_dato_gestionale() for the codifica introduced by Specifiche Tecniche 1.9.1.

On success returns {'DettaglioLinee': {...}}, plus 'warnings' (list[str]) when aliquota_iva is a non-standard IT VAT rate (outside 4, 5, 10, 22). On failure returns {'error': ''}.

Build the AltriDatiGestionali entry for the sport-worker IRPEF exemption codifica.

Covers compensation under art. 36, comma 6, D.Lgs. 36/2021 (lavoro sportivo dilettantistico), exempt from the taxable base up to EUR 15,000/year. Sets TipoDato to 'ESENZSPORT' — verified against AdE Allegato A – Specifiche Tecniche 1.9.1 (in force 2026-05-15). RiferimentoTesto/RiferimentoNumero are not mandated for this codifica (unlike e.g. 'ALI-COMP', which requires RiferimentoNumero); both are left to the caller's discretion here.

Pass the returned dict's 'AltriDatiGestionali' value inside a list to add_linea_dettaglio()'s altri_dati_gestionali parameter — or pass the dict itself if you are constructing the list manually.

On success returns {'AltriDatiGestionali': {'TipoDato': 'ESENZSPORT', ...}}. On failure (invalid riferimento_data) returns {'error': ''}.

Compute DatiRiepilogo VAT summary totals grouped by AliquotaIVA and Natura.

Use this as step 8 in the invoice generation workflow, after all add_linea_dettaglio() calls and before generate_fattura_xml(). Pass the raw line values (not the DettaglioLinee dicts): each item needs 'prezzo_totale' (float), 'aliquota_iva' (float), and optionally 'natura' (str).

Groups lines by (aliquota_iva, natura) pair, sums imponibile, and computes imposta = imponibile × aliquota / 100 (rounded HALF_UP to 2 decimal places). EsigibilitaIVA defaults to 'I' (immediata) for all groups.

Always succeeds (empty list produces empty DatiRiepilogo). Returns: {'DatiRiepilogo': [...], 'totale_imponibile': str, 'totale_imposta': str, 'totale_fattura': str}. Pass 'DatiRiepilogo' directly to generate_fattura_xml() as dati_riepilogo.

Return the complete list of valid Natura exemption codes with legal references.

Call this when add_linea_dettaglio() requires a Natura code (i.e. aliquota_iva is 0.0). Common codes: N1 (excluded, art. 15), N2.1 (out-of-scope, territoriality), N3.1 (exports), N3.2 (intra-EU supplies), N4 (VAT-exempt), N6.x (reverse charge), N7 (OSS/IOSS — VAT paid in another EU state). Note: parent codes N2, N3, N6 were removed from the FatturaPA XSD enumeration effective 1 January 2021. Use sub-codes (N2.1, N2.2, N3.1–N3.6, N6.1–N6.9) instead.

Always succeeds. Returns {'codes': [{'code', 'description', 'legal_ref'}, ...], 'total': int}.

Build the DatiPagamento block for the FatturaElettronicaBody.

Use this as step 9 in the invoice generation workflow, after compute_totali() and before generate_fattura_xml(). The block is optional in the XML but strongly recommended for B2B invoices.

condizioni_pagamento: TP01 = instalments, TP02 = single full payment, TP03 = advance. modalita_pagamento: MP05 (bank transfer) is most common for B2B; include iban when using MP05. importo_pagamento: for TP02 this should equal totale_fattura from compute_totali(); for TP01 (instalments) call this tool once per instalment tranche.

Validates: condizioni_pagamento in {TP01, TP02, TP03}; modalita_pagamento in MP01–MP23; IBAN format (letters + digits, max 34 chars); data_scadenza_pagamento is YYYY-MM-DD.

On success returns {'DatiPagamento': {...}} ready for generate_fattura_xml(). On failure returns {'error': ''}.

Build an Allegati (attachment) entry to include in a FatturaPA document.

Use this when you need to attach supporting documents (e.g. DDT, contract, PDF) to the invoice. Call once per file, collect results in a list, and pass it to generate_fattura_xml() as the allegati parameter.

attachment_base64 must be valid standard base64 (RFC 4648); the tool verifies decodability. nome_allegato must include the file extension (e.g. 'contract.pdf'). formato_allegato (e.g. 'PDF', 'XML', 'ZIP') is optional but recommended for recipients to identify the content without decoding.

On success returns {'Allegati': {'NomeAllegato', 'Attachment', 'size_bytes', ...}}. On failure returns {'error': ''} (invalid base64 or name > 60 chars).

Assemble a complete FatturaPA v1.2.3 XML document from all prepared blocks.

Use this as step 10 in the invoice generation workflow — the final assembly step. All required blocks must come from their respective builder/validator tools; pass the full dict returned by each tool (the function unwraps the top-level key).

Required: dati_trasmissione, cedente_prestatore, cessionario_committente, dati_generali, dettaglio_linee (list), dati_riepilogo (list from compute_totali()). Optional: dati_pagamento, allegati (list), dati_ritenuta.

Does NOT validate against the XSD schema — call validate_fattura_xsd() (step 11) on the returned 'xml' string immediately after to confirm conformance.

On success returns {'xml': str, 'filename': str, 'formato_trasmissione': str, 'length_bytes': int}. On unexpected error returns {'error': ''}.

Validate a FatturaPA XML string against the official Agenzia delle Entrate XSD v1.2.3.

Use this as step 11 — always call immediately after generate_fattura_xml() before storing or transmitting the document. Also use to verify third-party invoices received from suppliers.

Automatically selects the correct XSD based on the document's versione attribute: FPR12 (B2B/B2C) uses FatturaPA_FPR12_v1.2.3.xsd; FPA12 (B2G) uses FatturaPA_FPA12_v1.2.3.xsd. FATTURA_XSD_PATH env var overrides both.

Requires lxml. Validates namespace, element structure, data types, and cardinality.

On success returns {'valid': true, 'formato_trasmissione': 'FPR12'|'FPA12', 'errors': []}. On failure returns {'valid': false, 'errors': ['', ...]}. On setup error (missing lxml or XSD file) returns {'error': ''}.

Parse a FatturaPA XML string into a structured Python dict.

Use this to inspect or process invoices received from counterparties, or to verify the output of generate_fattura_xml(). Accepts both FPR12 (B2B) and FPA12 (PA) formats. The result can be passed directly to export_to_json().

Extracts: versione, transmission data, seller/buyer identity and address, document type/date/number/causale, all DettaglioLinee, DatiRiepilogo, and DatiPagamento if present. Fields not found in the XML are returned as null.

On success returns {'versione': str, 'header': {...}, 'body': {...}}. On XML parse error returns {'error': 'XML parse error: '}. On missing lxml returns {'error': 'lxml is not installed...'}.

Serialize a parsed FatturaPA dict to a clean, indented JSON string.

Call this after parse_fattura_xml() when you need a human-readable or machine-transferable representation of the invoice. By default, null/empty fields are omitted (include_empty=False) to reduce noise in the output.

indent controls JSON indentation (0 = compact, 2 = standard readable, 4 = wide). include_empty=True retains all keys even when their value is null or empty string.

Always succeeds. Returns {'json_string': str, 'size_chars': int}.

Validate an Italian Partita IVA for format (11 digits) and modulo-10 checksum.

Use this as step 1 in the invoice generation workflow before any other tool. Equivalent to validate_partita_iva() in header tools — use this standalone version when you only need the validation result without importing header tools.

Strips whitespace, checks for exactly 11 digits, then applies the official Agenzia delle Entrate control algorithm to verify the check digit.

On success returns {'valid': true, 'value': ''}. On failure returns {'valid': false, 'value': '', 'error': ''}.

Generate the canonical SDI filename for a FatturaPA document.

Use this when you need the official filename independently of generate_fattura_xml() (which also produces the filename). The SDI specification requires the format: IT{PartitaIVA}_{ProgressivoInvio}.xml, e.g. IT01234567890_00001.xml.

Validates: partita_iva_cedente must be exactly 11 digits; progressivo_invio must be 1–10 alphanumeric characters. Purely numeric progressivo shorter than 5 digits is zero-padded to 5 digits (e.g. '1' → '00001').

On success returns {'filename': str, 'partita_iva': str, 'progressivo_invio': str, 'length': int}. On failure returns {'error': ''}.

Compute ritenuta d'acconto (withholding tax) for professional invoices.

Use this when issuing professional service invoices (TD01 or TD06) that are subject to withholding tax — typically for self-employed professionals, agents, or freelancers. Also mark the relevant line items with ritenuta='SI' in add_linea_dettaglio(), and pass the returned 'DatiRitenuta' dict to generate_fattura_xml() as dati_ritenuta.

tipo_ritenuta determines the rate: RT01/RT02 = 20% (ritenuta d'acconto, statutory default). RT03 (INPS), RT04 (ENASARCO), RT05 (ENPAM), RT06 (other) have variable rates: aliquota_override or importo_override is required for all of them. causale_pagamento: income category code for Mod. 770 (e.g. 'A' professional fees, 'O' occasional). aliquota_override: supply the actual rate (%) for RT03-RT06, or to override the 20% default for RT01/RT02. importo_override: supply the exact withholding amount when rate-based computation is imprecise.

Validates: tipo_ritenuta must be in RT01-RT06. RT03-RT06 require aliquota_override or importo_override.

On success returns {'DatiRitenuta': {...}, 'importo_ritenuta': str, 'aliquota_applicata': str, 'imponibile_ritenuta': str, 'description': str, 'legal_ref': str}. On failure returns {'error': ''}.

Assemble a complete FatturaSemplificata VFSM10 XML document.

Use this for simplified invoices (TD07), simplified credit notes (TD08), and simplified debit notes (TD09) per art. 21-bis DPR 633/72. These are valid for transactions up to EUR 400 (tax-inclusive).

The simplified format has a flatter structure than the ordinary FatturaPA: no per-line VAT breakdown (DettaglioLinee/DatiRiepilogo), no DatiPagamento in the body. Each DatiBeniServizi entry carries its own Descrizione, Importo, and DatiIVA.

On success returns {'xml': str, 'filename': str, 'length_bytes': int}. On error returns {'error': ''}.

Validate a FatturaSemplificata XML string against the VFSM10 XSD v1.0.2.

Call this immediately after generate_fattura_semplificata() to confirm XSD conformance. Also use to verify third-party simplified invoices.

Requires lxml. Validates namespace, element structure, data types, and cardinality.

On success returns {'valid': true, 'errors': []}. On failure returns {'valid': false, 'errors': ['...']}. On setup error returns {'error': ''}.

Parse a FatturaSemplificata XML string into a structured Python dict.

Use this to inspect simplified invoices (TD07/TD08/TD09) received from counterparties or to verify output of generate_fattura_semplificata().

Extracts: versione, transmission data, seller identity and address, buyer fiscal identifiers and optional address, document type/date/number, all DatiBeniServizi entries, and DatiFatturaRettificata if present.

On success returns {'versione': str, 'header': {...}, 'body': {...}}. On error returns {'error': ''}.

Generate a UBL 2.1 Invoice XML document from an ItalianInvoice dict.

Use this for cross-border B2B invoices or Peppol-routed documents. This tool does NOT produce FatturaPA XML; use generate_fattura_xml() for SdI submission.

Italian national fields (progressivo_invio, codice_destinatario, regime_fiscale) are accepted in the input dict but are not emitted in the UBL output — they belong in the FatturaPA DatiTrasmissione header.

profile (BT-24) should be the Peppol BIS Billing 3.0 customisation ID ('urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0') or the EN 16931 core profile ('urn:cen.eu:en16931:2017') for non-Peppol use. [Inference: FatturaPA-specific CIUS URN not yet standardised for UBL; verify with AdE if UBL submission to an IT-specific platform is intended.]

On success returns {'xml': str, 'length_bytes': int, 'format': 'UBL-2.1'}. On validation error returns {'error': str, 'details': list[str]}. On unexpected error returns {'error': str}.

Generate a CII CrossIndustryInvoice XML document from an ItalianInvoice dict.

Use this when a CII (UN/CEFACT) wire format is required — for example, for Factur-X embedded XML or ZUGFeRD-compatible output. This tool does NOT produce FatturaPA XML; use generate_fattura_xml() for SdI submission.

Italian national fields are accepted but not emitted (same policy as generate_ubl_invoice).

On success returns {'xml': str, 'length_bytes': int, 'format': 'CII-D16B'}. On validation error returns {'error': str, 'details': list[str]}. On unexpected error returns {'error': str}.

Validate a UBL 2.1 invoice XML string for structural correctness.

Performs structural validation by parsing the XML into an EN16931Invoice and checking that required core fields (invoice_number, invoice_date, seller, buyer, at least one line item) are present and non-empty.

Note: this tool does NOT validate against the normative UBL 2.1 XSD schema (the UBL XSD files are not bundled with this package). For full XSD validation use a dedicated UBL validator or the Peppol Validator tool.

On success returns {'valid': true, 'warnings': list[str]}. On failure returns {'valid': false, 'errors': list[str]}. On parse error returns {'valid': false, 'errors': ['XML parse error: ...']}.

Parse a UBL 2.1 invoice XML string into an EN 16931 structured dict.

Extracts the EN 16931 core field set. Italian national fields (progressivo_invio, regime_fiscale, etc.) are returned with their ItalianInvoice defaults since UBL 2.1 does not carry them.

Use this to inspect cross-border invoices received in UBL format, or to round-trip the output of generate_ubl_invoice() for verification.

On success returns the ItalianInvoice fields as a JSON-serialisable dict. On failure returns {'error': str}.

Validate a CII CrossIndustryInvoice XML string for structural correctness.

Performs structural validation by parsing the XML into an EN16931Invoice and checking that required core fields are present and non-empty.

Note: this tool does NOT validate against the normative CII D16B XSD schema. For full schema validation use a dedicated CII or ZUGFeRD validator.

On success returns {'valid': true, 'warnings': list[str]}. On failure returns {'valid': false, 'errors': list[str]}. On parse error returns {'valid': false, 'errors': ['XML parse error: ...']}.

Parse a CII CrossIndustryInvoice XML string into an EN 16931 structured dict.

Extracts the EN 16931 core field set. Italian national fields are returned with their ItalianInvoice defaults since CII does not carry them.

Use this to inspect Factur-X / ZUGFeRD invoices, or to round-trip the output of generate_cii_invoice() for verification.

On success returns the ItalianInvoice fields as a JSON-serialisable dict. On failure returns {'error': str}.

Apply an XAdES-BES enveloped XML signature to a FatturaPA XML document. The signed XML retains the .xml extension. Requires a qualified PKCS#12 certificate. Uses the signer microservice when available, falls back to direct signing. Requires confirmation (irreversible).

Apply a CAdES-BES (CMS/PKCS#7) attached signature to a FatturaPA XML document. The output is a DER-encoded .xml.p7m file (base64-encoded in the response). Requires a qualified PKCS#12 certificate. Uses the signer microservice when available, falls back to direct signing. Requires confirmation (irreversible).

Submit a signed FatturaPA invoice to SDI via SDICoop. The invoice must be signed (XAdES-BES or CAdES-BES) before submission. Requires mTLS certificate configuration. Returns the IdentificativoSDI assigned by SDI. Requires confirmation (irreversible).

Check the status of a previously submitted invoice by its IdentificativoSDI. SDI communicates status asynchronously via notifications; this returns the last known local status.

Parse an SDI notification XML into a structured dict. Supports all notification types: RC (delivery receipt), NS (rejection with error codes), MC (delivery failure), NE (seller outcome), EC (buyer acceptance/rejection), SE (outcome rejection), DT (deadline expiry), MT (metadata), AT (undeliverable attestation).

Send an acceptance (EC01) or rejection (EC02) notification to SDI for a received invoice. The esito XML must conform to the NotificaEsitoCommittente schema (MessaggiTypes_v1.1.xsd). Requires confirmation (irreversible).

Show current SDI channel configuration: environment, channel type, channel ID, endpoint URL, and certificate status. Does not expose sensitive values (cert_password).

Archive a signed invoice for conservazione sostitutiva. Stores the document with SHA-256 hash, timestamp, and retention metadata per AgID circolare 65/2014. Returns the archive metadata including document_id and retention_until date.

Retrieve an archived invoice by its document_id. Returns the document content (base64-encoded) and its archive metadata.

Verify the integrity of an archived document by recomputing its SHA-256 hash and comparing against the stored hash.

List all archived invoices. Returns a list of archive metadata records sorted by archive date.

Build a Pacchetto di Versamento (PdV) ZIP archive containing one or more signed invoices and an XML index (IPdV). The PdV is the unit of transfer to an AgID-accredited conservazione provider.