add_linea_dettaglio
Add a single line item to an Italian e-invoice, specifying VAT rate, exemption nature, pricing, quantity, and optional data for XML generation.
Instructions
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': ''}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| natura | No | Natura exemption code: N1, N2.1, N2.2, N3.1–N3.6, N4, N5, N6.1–N6.9, N7. Parent codes N2, N3, N6 are invalid since Jan 2021 and are not accepted. Required when aliquota_iva is 0.0. Use get_natura_codes() for the full list. | |
| quantita | No | Quantity (Quantita). Optional for services billed as a lump sum. When provided, unit_price × quantita should equal prezzo_totale. | |
| ritenuta | No | Withholding tax flag: 'SI' to indicate that this line is subject to ritenuta d'acconto. Use check_ritenuta_acconto() to compute the amount. | |
| descrizione | Yes | Description of the good or service (max 1000 chars). | |
| aliquota_iva | No | VAT rate as a percentage (e.g. 22.0 for 22%, 10.0 for 10%, 0.0 for exempt). Use 0.0 together with a Natura code for exempt/out-of-scope supplies. | |
| numero_linea | Yes | Sequential line number starting at 1. Each DettaglioLinee entry must have a unique NumeroLinea. | |
| unita_misura | No | Unit of measure (e.g. 'PZ', 'KG', 'ORE', 'M2'). Optional. | |
| prezzo_totale | No | Total line amount before VAT (PrezzoTotale = quantita × prezzo_unitario). Must be provided explicitly; the tool does not auto-compute it. | |
| prezzo_unitario | No | Unit price before VAT (PrezzoUnitario). Negative for credit notes. | |
| altri_dati_gestionali | No | Optional list of AltriDatiGestionali entries (DettaglioLinee, XSD maxOccurs unbounded). Each entry is a dict with XSD-cased keys: 'TipoDato' (str, required, max 10 chars), 'RiferimentoTesto' (str, optional, max 60 chars), 'RiferimentoNumero' (str/float, optional), 'RiferimentoData' (str YYYY-MM-DD, optional) — the same shape returned by build_sport_worker_exemption_dato_gestionale()['AltriDatiGestionali'], which can be passed straight through in this list for the sport-worker IRPEF exemption codifica ('ESENZSPORT'). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||