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.

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.

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.

On success returns {'CessionarioCommittente': {...}} ready for generate_fattura_xml(). 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': '<cleaned_piva>'}. 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. 'ABC123') → routing_type: 'SDI_CODE'

• 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'

Limitation: performs format validation only — no live query against the SDI SOAP directory service (planned for a future release).

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.

On success returns {'DettaglioLinee': {...}}. On failure 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 Natura exemption codes (N1–N7 and sub-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).

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.6.1 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.6.1.

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.

Requires lxml to be installed and the bundled XSD schema file to be present (or FATTURA_XSD_PATH env var to point to it). Validates namespace, element structure, data types, and cardinality constraints.

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': '<cleaned_piva>'}. 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% (natural person, professional/occasional), RT03/RT04 = 23.20% (agent commissions), RT05 = 4% (condominium), RT06 = 30% (employment). causale_pagamento: income category code for Mod. 770 (e.g. 'A' professional fees, 'O' occasional).

Validates: tipo_ritenuta must be in RT01–RT06. imponibile is typically the net invoice total.

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