mcp-facturacion-electronica-es

# mcp-facturacion-electronica-es 🇪🇸

[English](README.md) | [Espanol](README.es.md)

<!-- mcp-name: io.github.cmendezs/mcp-facturacion-electronica-es -->

![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)
[![PyPI version](https://img.shields.io/pypi/v/mcp-facturacion-electronica-es.svg)](https://pypi.org/project/mcp-facturacion-electronica-es/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-facturacion-electronica-es.svg)](https://pypi.org/project/mcp-facturacion-electronica-es/) [![mcp-facturacion-electronica-es MCP server](https://glama.ai/mcp/servers/cmendezs/mcp-facturacion-electronica-es/badges/score.svg)](https://glama.ai/mcp/servers/cmendezs/mcp-facturacion-electronica-es)

---

## Introduction

**mcp-facturacion-electronica-es** is an MCP (Model Context Protocol) server specialized
in Spanish e-invoicing. It provides tools to generate, validate, and submit electronic
invoices under the six coexisting systems in Spain: VERI\*FACTU, Facturae/FACe,
SII, TicketBAI (Basque Country), NaTicket (Navarre), and the B2B obligations of Ley 18/2022
"Crea y Crece". The server is built on `mcp-einvoicing-core`, the shared base library
used by `mcp-facture-electronique-fr` (France, XP Z12-013) and `mcp-einvoicing-be`
(Belgium, Peppol BIS 3.0).

Spain operates one of the most complex e-invoicing landscapes in Europe, with six overlapping
systems that apply depending on taxpayer size, sector, and region. VERI\*FACTU
(Royal Decree 1007/2023, Order HAC/1177/2024) is the forthcoming mandatory real-time invoice
registry for non-SII taxpayers, with hard deadlines in January and July 2027 (RD-ley 15/2025).
SII (Suministro Inmediato de Informacion, Immediate Information Supply) already applies to
large taxpayers (>6M EUR turnover). The Basque Country runs TicketBAI and Navarre runs NaTicket,
both independent of the national AEAT framework. B2G invoicing via Facturae XML on the FACe
portal has been mandatory since 2015 (Ley 25/2013).

---

## Built on

This package is built on [**mcp-einvoicing-core**](https://github.com/cmendezs/mcp-einvoicing-core),
the shared base library used by all MCP servers in the `mcp-einvoicing` ecosystem. It provides
common models, validation abstractions, XML utilities, and the exception hierarchy.

`mcp-einvoicing-core` is installed automatically as a transitive dependency, no additional
steps are required.

---

## Overview

The Spanish e-invoicing ecosystem has **six coexisting systems** with distinct scopes,
formats, and timelines. VERI\*FACTU introduces tamper-proof chained invoice records
submitted in real time to the AEAT (Agencia Estatal de Administracion Tributaria),
applicable to most businesses from 2027 (RD-ley 15/2025). SII is already mandatory for
large taxpayers under a 4-day communication window. Facturae XML with XAdES-EPES signing
covers all B2G invoicing through the FACe portal. The Basque Country applies TicketBAI
independently, with three provincial authorities each maintaining their own XSD schemas and
endpoints. Navarre operates NaTicket. The Ley Crea y Crece mandates B2B e-invoicing for
all businesses; RD 238/2026 (BOE-A-2026-7295) confirms the admitted formats (EN 16931:
CII/UBL/EDIFACT/Facturae), while the Orden Ministerial developing the public-solution
technical package is still pending. Regime detection
based on tax domicile and turnover is a prerequisite to all other operations: use
`es__detect_regional_regime` first.

---

## Regulatory coverage

| System | Scope | Format | Mandatory from | Status |
|---|---|---|---|---|
| **VERI\*FACTU** | All non-SII businesses | Proprietary XML (XSD v1.0 HAC/1177/2024) | IS: Jan 2027 / Others: Jul 2027 (RD-ley 15/2025) | Implemented (pending regulatory confirmation) |
| **Facturae / FACe** | B2G (public sector) | Facturae 3.2.2 + XAdES-EPES | Mandatory since 2015 (Ley 25/2013) | Implemented (pending regulatory confirmation) |
| **SII** | Turnover >6M EUR, VAT groups, REDEME | XML SOAP/REST AEAT | Already mandatory (RD 596/2016) | Implemented (pending regulatory confirmation) |
| **TicketBAI** | Araba, Gipuzkoa, Bizkaia | Provincial XML + XAdES + QR | By province, 2022-2023 | Removed from scope (v0.2.0) |
| **Crea y Crece (B2B)** | All businesses (12/24 months after OM, by turnover) | UBL 2.1 or Facturae 3.2.2 (EN 16931); CII/EDIFACT also admitted, not implemented | RD 238/2026 published; Orden Ministerial (public solution) pending | Implemented (formats confirmed by RD 238/2026; public-solution wiring deferred to OM) |
| **NaTicket** | Navarre | Foral XML + signature | Foral mandate (phased rollout) | Partial (via `es__detect_regional_regime`) |

> **SII / VERI\*FACTU mutual exclusion (Real Decreto 254/2025):** Taxpayers enrolled in
> SII are exempt from VERI\*FACTU. Use `es__check_b2b_mandate_applicability`
> before generating any record.

---

## Tools

### VERI\*FACTU

#### `es__generate_verifactu_record`

Generates a tamper-proof invoice record (Orden HAC/1177/2024) with SHA-256 `Huella`
chaining that links it to the previous record.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `invoice` | `InvoiceDocument` | Yes | Core invoice model (seller, buyer, lines, VAT) |
| `previous_hash` | `string` | No | SHA-256 `Huella` of the preceding record (`null` = first in chain) |
| `software_id` | `string` | Yes | `IDSistemaInformatico` of the certified software |
| `software_nif` | `string` | Yes | NIF of the software manufacturer |
| `invoice_type` | `string` | Yes | `F1`, `F2`, `R1`-`R5` or `F3` |

```json
{
  "tool": "es__generate_verifactu_record",
  "arguments": {
    "invoice": { "date": "2025-03-15", "number": "2025-0042", "currency": "EUR",
      "seller": { "tax_id": { "country_code": "ES", "identifier": "B12345678" }, "name": "Empresa SL" },
      "buyer":  { "tax_id": { "country_code": "ES", "identifier": "A98765432" }, "name": "Cliente SA" },
      "lines": [{ "line_number": 1, "description": "Servicios", "quantity": 10, "unit_price": 100.00, "vat_rate": 21.0 }]
    },
    "previous_hash": "3C4A9B...", "software_id": "SW-001", "software_nif": "B87654321", "invoice_type": "F1"
  }
}
```

> The `Huella` chaining algorithm (SHA-256 over the keyed `campo=valor&` canonical string) is
> confirmed byte-for-byte against AEAT's own huella specification and its worked examples
> (`specs/verifactu/documentation/Veri-Factu_especificaciones_huella_hash_registros.pdf`).
> ⚠️ Still pending: full XSD v1.0 validation against a live AEAT test-environment acknowledgement.

---

#### `es__validate_verifactu_record`

Validates a VERI\*FACTU XML record against the official XSD published with Orden HAC/1177/2024
(BOE-A-2024-22138).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `xml` | `string` | Yes | Raw VERI\*FACTU XML record |
| `schema_version` | `string` | No | Schema version (default: `"1.0"`) |

```json
{ "tool": "es__validate_verifactu_record", "arguments": { "xml": "<RegistroFacturacion>...</RegistroFacturacion>" } }
```

> Structural checks now branch correctly on `RegistroAlta` vs. `RegistroAnulacion` (a prior version
> false-flagged valid `RegistroAnulacion` documents as missing `TipoFactura`/`CuotaTotal`/`ImporteTotal`,
> fields that only apply to `RegistroAlta`). Full XSD-mode validation (`SuministroLR.xsd`, bundled
> under `specs/verifactu/xsd/`) requires network access at runtime — it imports the W3C xmldsig-core
> schema by remote URL — and falls back to the structural checks above when that import can't
> resolve.

---

#### `es__submit_verifactu_to_aeat`

Submits a signed VERI\*FACTU record to the AEAT real-time endpoint via MTLS
(FNMT-RCM Class 1 certificate) or, if `EINVOICING_SIGNER_SOCKET` is configured, via the
signer microservice. Respects `AEAT_ENV=sandbox|production`. The submission endpoint
(`.../SistemaFacturacion/VerifactuSOAP`) is confirmed from the official AEAT WSDL and shared
by both the alta/anulación submission and the `es__query_verifactu_status` query operation.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `xml` | `string` | Yes | Signed VERI\*FACTU XML |
| `nif` | `string` | Yes | Sender NIF |

```json
{ "tool": "es__submit_verifactu_to_aeat", "arguments": { "xml": "<RegistroFacturacion>...</RegistroFacturacion>", "nif": "B12345678" } }
```

The response includes a `chain` object implementing the accepted-only chain contract:
`chain.safe_to_chain_from` (the submitted record's own `emisor_nif`/`num_serie`/`fecha`/`huella`)
is populated only when AEAT's `EstadoRegistro` is `Correcto` or `AceptadoConErrores` — both mean
the record was actually stored under that `Huella`. Otherwise `safe_to_chain_from` is `null` with
an explicit `warning` not to use this record's `Huella` as the next record's `previous_hash`, or
(for a `deferred` result) a `note` to call `es__query_verifactu_status` first.

---

#### `es__generate_qr_verifactu`

Generates the mandatory VERI\*FACTU QR code (HAC/1177/2024 Art. 10) as a base64-encoded PNG.
Encodes the AEAT verification URL with the text "Factura verificable en la sede
electronica de la AEAT". Candidate for promotion to `mcp-einvoicing-core` (QR generation).
URL format (host, path, `nif`/`numserie`/`fecha`/`importe` query parameters, and per-parameter
URL-encoding) is confirmed against the official AEAT QR specification
(`specs/verifactu/documentation/DetalleEspecificacTecnCodigoQRfactura.pdf`); the URL switches
between the sandbox and production `ValidarQR` host based on `AEAT_ENV`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `nif` | `string` | Yes | Issuer NIF |
| `invoice_number` | `string` | Yes | `NumSerieFactura` |
| `invoice_date` | `string` | Yes | `FechaExpedicionFactura` (YYYY-MM-DD) |
| `total_amount` | `number` | Yes | Invoice total including VAT |
| `size_px` | `integer` | No | QR size in pixels (default: 200) |

```json
{ "tool": "es__generate_qr_verifactu", "arguments": { "nif": "B12345678", "invoice_number": "2025-0042", "invoice_date": "2025-03-15", "total_