build_transmission_header

Instructions

Implementation Reference

• tools/header_tools.py:55-148 (handler)

  The main handler function that builds the DatiTrasmissione block. It validates inputs (formato_trasmissione, progressivo_invio, pec_destinatario requirement), constructs the result dict, and returns it.

  def build_transmission_header(
      id_paese: Annotated[
          str,
          Field(
              description=(
                  "Two-letter ISO 3166-1 country code of the transmitter (e.g. 'IT'). "
                  "Usually 'IT' for Italian entities."
              )
          ),
      ],
      id_codice: Annotated[
          str,
          Field(
              description=(
                  "Tax identifier of the transmitter: Partita IVA (11 digits) for Italian "
                  "entities, or foreign tax ID (max 28 chars) for cross-border."
              )
          ),
      ],
      progressivo_invio: Annotated[
          str,
          Field(
              description=(
                  "Unique sequential send identifier, max 10 alphanumeric characters. "
                  "Use generate_progressivo_invio() to obtain one automatically."
              )
          ),
      ],
      formato_trasmissione: Annotated[
          str,
          Field(
              description=(
                  "Transmission format: 'FPA12' for invoices to Public Administration (PA), "
                  "'FPR12' for invoices to private parties (B2B / B2C)."
              )
          ),
      ],
      codice_destinatario: Annotated[
          str,
          Field(
              description=(
                  "6-character alphanumeric SDI recipient code assigned to the buyer's "
                  "intermediary. Use '0000000' (7 zeros) when routing via PEC email instead."
              )
          ),
      ],
      pec_destinatario: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "PEC (certified email) address of the recipient. "
                  "Required only when codice_destinatario is '0000000'."
              ),
          ),
      ] = None,
  ) -> dict:
      """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': '<reason>'} — do not proceed to XML generation.
      """
      if formato_trasmissione not in ("FPA12", "FPR12"):
          return {"error": f"Invalid formato_trasmissione '{formato_trasmissione}'. Must be 'FPA12' or 'FPR12'."}
  
      if len(progressivo_invio) > 10 or not re.match(r"^[A-Za-z0-9]+$", progressivo_invio):
          return {"error": "progressivo_invio must be 1–10 alphanumeric characters."}
  
      if codice_destinatario == "0000000" and not pec_destinatario:
          return {"error": "pec_destinatario is required when codice_destinatario is '0000000'."}
  
      result: dict = {
          "DatiTrasmissione": {
              "IdTrasmittente": {
                  "IdPaese": id_paese.upper(),
                  "IdCodice": id_codice,
              },
              "ProgressivoInvio": progressivo_invio,
              "FormatoTrasmissione": formato_trasmissione,
              "CodiceDestinatario": codice_destinatario,
          }
      }
      if pec_destinatario:
          result["DatiTrasmissione"]["PECDestinatario"] = pec_destinatario
  
      return result

• tools/header_tools.py:55-111 (schema)

  The input schema/type definitions for the tool, using Pydantic Field annotations to describe each parameter (5 required + 1 optional).

  def build_transmission_header(
      id_paese: Annotated[
          str,
          Field(
              description=(
                  "Two-letter ISO 3166-1 country code of the transmitter (e.g. 'IT'). "
                  "Usually 'IT' for Italian entities."
              )
          ),
      ],
      id_codice: Annotated[
          str,
          Field(
              description=(
                  "Tax identifier of the transmitter: Partita IVA (11 digits) for Italian "
                  "entities, or foreign tax ID (max 28 chars) for cross-border."
              )
          ),
      ],
      progressivo_invio: Annotated[
          str,
          Field(
              description=(
                  "Unique sequential send identifier, max 10 alphanumeric characters. "
                  "Use generate_progressivo_invio() to obtain one automatically."
              )
          ),
      ],
      formato_trasmissione: Annotated[
          str,
          Field(
              description=(
                  "Transmission format: 'FPA12' for invoices to Public Administration (PA), "
                  "'FPR12' for invoices to private parties (B2B / B2C)."
              )
          ),
      ],
      codice_destinatario: Annotated[
          str,
          Field(
              description=(
                  "6-character alphanumeric SDI recipient code assigned to the buyer's "
                  "intermediary. Use '0000000' (7 zeros) when routing via PEC email instead."
              )
          ),
      ],
      pec_destinatario: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "PEC (certified email) address of the recipient. "
                  "Required only when codice_destinatario is '0000000'."
              ),
          ),
      ] = None,
  ) -> dict:

• tools/header_tools.py:54-55 (registration)

  Tool is registered via the @mcp.tool() decorator inside register_header_tools() which is called from server.py.

  @mcp.tool()
  def build_transmission_header(

• tools/header_tools.py:51-52 (registration)

  Registration wrapper function that decorates build_transmission_header (and 6 other tools) with @mcp.tool().

  def register_header_tools(mcp: FastMCP) -> None:
      """Register the 7 FatturaElettronicaHeader tools on the FastMCP instance."""

• tools/global_tools.py:95-148 (helper)

  The output of build_transmission_header() is consumed by generate_fattura_xml() as the dati_trasmissione parameter.

              "DatiTrasmissione block from build_transmission_header(). "
              "Must contain IdTrasmittente, ProgressivoInvio, FormatoTrasmissione, "
              "and CodiceDestinatario."
          )
      ),
  ],
  cedente_prestatore: Annotated[
      dict,
      Field(
          description=(
              "CedentePrestatore block from validate_cedente_prestatore(). "
              "Contains seller's tax ID, name, address, and fiscal regime."
          )
      ),
  ],
  cessionario_committente: Annotated[
      dict,
      Field(
          description=(
              "CessionarioCommittente block from validate_cessionario(). "
              "Contains buyer's tax ID, name, and address."
          )
      ),
  ],
  dati_generali: Annotated[
      dict,
      Field(
          description=(
              "DatiGenerali block from build_dati_generali(). "
              "Contains document type, date, number, and currency."
          )
      ),
  ],
  dettaglio_linee: Annotated[
      list,
      Field(
          description=(
              "List of DettaglioLinee dicts from add_linea_dettaglio(). "
              "Each entry must have NumeroLinea, Descrizione, PrezzoUnitario, "
              "PrezzoTotale, and AliquotaIVA."
          )
      ),
  ],
  dati_riepilogo: Annotated[
      list,
      Field(
          description=(
              "List of DatiRiepilogo dicts from compute_totali(). "
              "Contains VAT summary grouped by AliquotaIVA."
          )
      ),
  ],
  dati_pagamento: Annotated[
      Optional[dict],