{
"markdown": "# mcp-facturacion-electronica-es ๐ช๐ธ\n\n[English](README.md) | [Espanol](README.es.md)\n\n\n\n\n[](https://pypi.org/project/mcp-facturacion-electronica-es/)\n[](https://pypi.org/project/mcp-facturacion-electronica-es/) [](https://glama.ai/mcp/servers/cmendezs/mcp-facturacion-electronica-es)\n\n---\n\n## Introduction\n\n**mcp-facturacion-electronica-es** is an MCP (Model Context Protocol) server specialized\nin Spanish e-invoicing. It provides tools to generate, validate, and submit electronic\ninvoices under the six coexisting systems in Spain: VERI\\*FACTU, Facturae/FACe,\nSII, TicketBAI (Basque Country), NaTicket (Navarre), and the B2B obligations of Ley 18/2022\n\"Crea y Crece\". The server is built on [**mcp-einvoicing-core**](https://github.com/cmendezs/mcp-einvoicing-core),\nthe shared base library used by `mcp-facture-electronique-fr` (France, XP Z12-013) and\n`mcp-einvoicing-be` (Belgium, Peppol BIS 3.0), which provides common models, validation\nabstractions, XML utilities, and the exception hierarchy. `mcp-einvoicing-core` is installed\nautomatically as a transitive dependency, no additional steps are required.\n\nSpain operates one of the most complex e-invoicing landscapes in Europe, with six overlapping\nsystems that apply depending on taxpayer size, sector, and region. VERI\\*FACTU\n(Royal Decree 1007/2023, Order HAC/1177/2024) is the forthcoming mandatory real-time invoice\nregistry for non-SII taxpayers, with hard deadlines in January and July 2027 (RD-ley 15/2025).\nSII (Suministro Inmediato de Informacion, Immediate Information Supply) already applies to\nlarge taxpayers (>6M EUR turnover). The Basque Country runs TicketBAI and Navarre runs NaTicket,\nboth independent of the national AEAT framework. B2G invoicing via Facturae XML on the FACe\nportal has been mandatory since 2015 (Ley 25/2013).\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\npip install mcp-facturacion-electronica-es\n```\n\nWithout prior installation, using `uvx`:\n\n```bash\nuvx mcp-facturacion-electronica-es\n```\n\n### From source\n\n```bash\ngit clone https://github.com/cmendezs/mcp-facturacion-electronica-es.git\ncd mcp-facturacion-electronica-es\nuv sync --all-extras\n```\n\n## Configuration\n\nAll configuration is done through environment variables or a `.env` file.\n\n### AEAT / VERI\\*FACTU / SII\n\n| Variable | Description | Required |\n|---|---|---|\n| `AEAT_ENV` | `sandbox` or `production` | Yes |\n| `AEAT_CERTIFICATE_PATH` | Path to FNMT-RCM PKCS#12 certificate | For submission |\n| `AEAT_CERTIFICATE_PASSWORD` | Certificate password | For submission |\n| `AEAT_NIF` | Taxpayer NIF | For submission |\n\n### FACe\n\n| Variable | Description | Required |\n|---|---|---|\n| `FACE_ENV` | `sandbox` or `production` | Yes |\n\nFACe authenticates via JWS using the same `AEAT_CERTIFICATE_PATH` / `AEAT_CERTIFICATE_PASSWORD`\ncertificate as VERI\\*FACTU/SII (see the AEAT section above); no separate FACe credentials are\nrequired.\n\n### TicketBAI\n\n| Variable | Description | Required |\n|---|---|---|\n| `TICKETBAI_ENV` | `sandbox` or `production` | Yes |\n| `TICKETBAI_CERTIFICATE_PATH` | Provincial signing certificate path | Yes |\n| `TICKETBAI_CERTIFICATE_PASSWORD` | Certificate password | Yes |\n\n### Common (inherited from `mcp-einvoicing-core`)\n\n| Variable | Description | Default |\n|---|---|---|\n| `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |\n\n## Claude Desktop integration\n\nTo use this server with Claude, add this configuration to your `claude_desktop_config.json` file:\n\n```json\n{\n \"mcpServers\": {\n \"facturacion-es\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-facturacion-electronica-es\"],\n \"env\": {\n \"AEAT_ENV\": \"sandbox\",\n \"AEAT_CERTIFICATE_PATH\": \"/path/to/cert.p12\",\n \"AEAT_CERTIFICATE_PASSWORD\": \"certificate-password\"\n }\n }\n }\n}\n```\n\n## Cursor integration\n\nCursor supports MCP servers via stdio. Add the configuration in:\n- **Global** (all projects): `~/.cursor/mcp.json`\n- **Project** (this repository only): `.cursor/mcp.json`\n\n```json\n{\n \"mcpServers\": {\n \"facturacion-es\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-facturacion-electronica-es\"],\n \"env\": {\n \"AEAT_ENV\": \"sandbox\",\n \"AEAT_CERTIFICATE_PATH\": \"/path/to/cert.p12\",\n \"AEAT_CERTIFICATE_PASSWORD\": \"certificate-password\"\n }\n }\n }\n}\n```\n\nReload the Cursor window (`Ctrl+Shift+P` then *Reload Window*) to apply the changes.\n\n## Kiro integration\n\nKiro supports MCP servers via its dedicated configuration file. Two levels are available:\n- **Global** (all projects): `~/.kiro/settings/mcp.json`\n- **Workspace** (this repository only): `.kiro/settings/mcp.json`\n\n```json\n{\n \"mcpServers\": {\n \"facturacion-es\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-facturacion-electronica-es\"],\n \"env\": {\n \"AEAT_ENV\": \"sandbox\",\n \"AEAT_CERTIFICATE_PATH\": \"/path/to/cert.p12\",\n \"AEAT_CERTIFICATE_PASSWORD\": \"certificate-password\"\n },\n \"disabled\": false,\n \"autoApprove\": []\n }\n }\n}\n```\n\nThe file is automatically reloaded on save. You can also open the config via the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) then *MCP*.\n\n> **Kiro security tip**: rather than writing secrets in plain text, use the syntax `\"AEAT_CERTIFICATE_PASSWORD\": \"${AEAT_CERTIFICATE_PASSWORD}\"`, Kiro resolves shell environment variables at startup.\n\n## Available tools\n\n### VERI\\*FACTU\n\n#### `es__generate_verifactu_record`\n\nGenerates a tamper-proof invoice record (Orden HAC/1177/2024) with SHA-256 `Huella`\nchaining that links it to the previous record.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `invoice` | `InvoiceDocument` | Yes | Core invoice model (seller, buyer, lines, VAT) |\n| `previous_hash` | `string` | No | SHA-256 `Huella` of the preceding record (`null` = first in chain) |\n| `software_id` | `string` | Yes | `IDSistemaInformatico` of the certified software |\n| `software_nif` | `string` | Yes | NIF of the software manufacturer |\n| `invoice_type` | `string` | Yes | `F1`, `F2`, `R1`-`R5` or `F3` |\n\n```json\n{\n \"tool\": \"es__generate_verifactu_record\",\n \"arguments\": {\n \"invoice\": { \"date\": \"2025-03-15\", \"number\": \"2025-0042\", \"currency\": \"EUR\",\n \"seller\": { \"tax_id\": { \"country_code\": \"ES\", \"identifier\": \"B12345678\" }, \"name\": \"Empresa SL\" },\n \"buyer\": { \"tax_id\": { \"country_code\": \"ES\", \"identifier\": \"A98765432\" }, \"name\": \"Cliente SA\" },\n \"lines\": [{ \"line_number\": 1, \"description\": \"Servicios\", \"quantity\": 10, \"unit_price\": 100.00, \"vat_rate\": 21.0 }]\n },\n \"previous_hash\": \"3C4A9B...\", \"software_id\": \"SW-001\", \"software_nif\": \"B87654321\", \"invoice_type\": \"F1\"\n }\n}\n```\n\n> The `Huella` chaining algorithm (SHA-256 over the keyed `campo=valor&` canonical string) is\n> confirmed byte-for-byte against AEAT's own huella specification and its worked examples\n> (`specs/verifactu/documentation/Veri-Factu_especificaciones_huella_hash_registros.pdf`).\n> โ ๏ธ Still pending: full XSD v1.0 validation against a live AEAT test-environment acknowledgement.\n\n---\n\n#### `es__validate_verifactu_record`\n\nValidates a VERI\\*FACTU XML record against the official XSD published with Orden HAC/1177/2024\n(BOE-A-2024-22138).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml` | `string` | Yes | Raw VERI\\*FACTU XML record |\n| `schema_version` | `string` | No | Schema version (default: `\"1.0\"`) |\n\n```json\n{ \"tool\": \"es__validate_verifactu_record\", \"arguments\": { \"xml\": \"...\" } }\n```\n\n> Structural checks now branch correctly on `RegistroAlta` vs. `RegistroAnulacion` (a prior version\n> false-flagged valid `RegistroAnulacion` documents as missing `TipoFactura`/`CuotaTotal`/`ImporteTotal`,\n> fields that only apply to `RegistroAlta`). Full XSD-mode validation (`SuministroLR.xsd`, bundled\n> under `specs/verifactu/xsd/`) requires network access at runtime โ it imports the W3C xmldsig-core\n> schema by remote URL โ and falls back to the structural checks above when that import can't\n> resolve.\n\n---\n\n#### `es__submit_verifactu_to_aeat`\n\nSubmits a signed VERI\\*FACTU record to the AEAT real-time endpoint via MTLS\n(FNMT-RCM Class 1 certificate) or, if `EINVOICING_SIGNER_SOCKET` is configured, via the\nsigner microservice. Respects `AEAT_ENV=sandbox|production`. The submission endpoint\n(`.../SistemaFacturacion/VerifactuSOAP`) is confirmed from the official AEAT WSDL and shared\nby both the alta/anulaciรณn submission and the `es__query_verifactu_status` query operation.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml` | `string` | Yes | Signed VERI\\*FACTU XML |\n| `nif` | `string` | Yes | Sender NIF |\n\n```json\n{ \"tool\": \"es__submit_verifactu_to_aeat\", \"arguments\": { \"xml\": \"...\", \"nif\": \"B12345678\" } }\n```\n\nThe response includes a `chain` object implementing the accepted-only chain contract:\n`chain.safe_to_chain_from` (the submitted record's own `emisor_nif`/`num_serie`/`fecha`/`huella`)\nis populated only when AEAT's `EstadoRegistro` is `Correcto` or `AceptadoConErrores` โ both mean\nthe record was actually stored under that `Huella`. Otherwise `safe_to_chain_from` is `null` with\nan explicit `warning` not to use this record's `Huella` as the next record's `previous_hash`, or\n(for a `deferred` result) a `note` to call `es__query_verifactu_status` first.\n\n---\n\n#### `es__generate_qr_verifactu`\n\nGenerates the mandatory VERI\\*FACTU QR code (HAC/1177/2024 Art. 10) as a base64-encoded PNG.\nEncodes the AEAT verification URL with the text \"Factura verificable en la sede\nelectronica de la AEAT\". Candidate for promotion to `mcp-einvoicing-core` (QR generation).\nURL format (host, path, `nif`/`numserie`/`fecha`/`importe` query parameters, and per-parameter\nURL-encoding) is confirmed against the official AEAT QR specification\n(`specs/verifactu/documentation/DetalleEspecificacTecnCodigoQRfactura.pdf`); the URL switches\nbetween the sandbox and production `ValidarQR` host based on `AEAT_ENV`.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `nif` | `string` | Yes | Issuer NIF |\n| `invoice_number` | `string` | Yes | `NumSerieFactura` |\n| `invoice_date` | `string` | Yes | `FechaExpedicionFactura` (YYYY-MM-DD) |\n| `total_amount` | `number` | Yes | Invoice total including VAT |\n| `size_px` | `integer` | No | QR size in pixels (default: 200) |\n\n```json\n{ \"tool\": \"es__generate_qr_verifactu\", \"arguments\": { \"nif\": \"B12345678\", \"invoice_number\": \"2025-0042\", \"invoice_date\": \"2025-03-15\", \"total_amount\": 1210.00 } }\n```\n\n---\n\n#### `es__cancel_verifactu_record`\n\nGenerates a VERI\\*FACTU cancellation record (`RegistroAnulacion`, `TipoHuella=01`) chained to\nthe current fingerprint sequence. Both the anulaciรณn `Huella` (SHA-256 over\n`IDEmisorFacturaAnulada`/`NumSerieFacturaAnulada`/`FechaExpedicionFacturaAnulada`/`Huella`/\n`FechaHoraHusoGenRegistro` โ a distinct field set from `RegistroAlta`'s, not a reduced copy of\nit) and the top-level `` block's element names are confirmed against the official AEAT\nhuella specification and `SuministroInformacion.xsd`.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `original_invoice_number` | `string` | Yes | `NumSerieFactura` to cancel |\n| `original_invoice_date` | `string` | Yes | `FechaExpedicionFactura` (YYYY-MM-DD) |\n| `issuer_nif` | `string` | Yes | Issuer NIF |\n| `previous_hash` | `string` | Yes | `Huella` of the last record in the chain |\n\n```json\n{ \"tool\": \"es__cancel_verifactu_record\", \"arguments\": { \"original_invoice_number\": \"2025-0042\", \"original_invoice_date\": \"2025-03-15\", \"issuer_nif\": \"B12345678\", \"previous_hash\": \"3C4A9B...\" } }\n```\n\n---\n\n#### `es__query_verifactu_status`\n\nQueries the `EstadoRegistro` of an already-submitted VERI\\*FACTU record\n(`ConsultaFactuSistemaFacturacion` / `ConsultaLR.xsd`). Use after a `deferred` result from\n`es__submit_verifactu_to_aeat`: wait `retry_after_seconds`, then call this tool to confirm\nthe final state (`Correcto` / `AceptadoConErrores` / `Anulado`) before chaining the next\nrecord. Requires `AEAT_ENV`, `AEAT_CERTIFICATE_PATH`, and `AEAT_CERTIFICATE_PASSWORD`, same\nas `es__submit_verifactu_to_aeat`.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `nif` | `string` | Yes | NIF of the `ObligadoEmision` |\n| `name` | `string` | Yes | Name/razรณn social of the `ObligadoEmision` |\n| `invoice_date` | `string` | Yes | Invoice date being queried, `YYYY-MM-DD` (determines `PeriodoImputacion`) |\n| `num_serie_factura` | `string` | No | `NumSerieFactura` filter (omit to query the whole period) |\n\n```json\n{ \"tool\": \"es__query_verifactu_status\", \"arguments\": { \"nif\": \"B12345678\", \"name\": \"Empresa SL\", \"invoice_date\": \"2025-03-15\", \"num_serie_factura\": \"2025-0042\" } }\n```\n\n> Root element name (`ConsultaFactuSistemaFacturacion`) and endpoint โ the same\n> `.../SistemaFacturacion/VerifactuSOAP` URL used by `es__submit_verifactu_to_aeat`, per the\n> official WSDL โ are both confirmed. โ ๏ธ Still pending: response parsing has not been validated\n> against a live AEAT sandbox acknowledgement.\n\n---\n\n### Facturae / FACe\n\n#### `es__generate_facturae_xml`\n\nGenerates a Facturae 3.2.2 compliant XML invoice for B2G submission. Uses\n`InvoiceDocument` from `mcp-einvoicing-core`.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `invoice` | `InvoiceDocument` | Yes | Core invoice model |\n| `schema_version` | `string` | No | Facturae schema version (default: `\"3.2.2\"`) |\n| `tax_type` | `string` | No | Indirect tax regime: `IVA` (peninsula/Baleares), `IPSI` (Ceuta/Melilla), or `IGIC` (Canarias). Mixing tax types on one invoice is not supported. Default: `\"IVA\"` |\n| `recargo_equivalencia_rate` | `number` | No | Recargo de Equivalencia rate (%), if applicable |\n| `recargo_equivalencia_amount` | `number` | No | Explicit Recargo de Equivalencia amount; if omitted, computed as `base_imponible * recargo_equivalencia_rate / 100` |\n| `irpf_rate` | `number` | No | IRPF withholding rate (%), emitted in `TaxesWithheld` |\n\n```json\n{ \"tool\": \"es__generate_facturae_xml\", \"arguments\": { \"invoice\": { \"date\": \"2025-03-15\", \"number\": \"2025-0042\", \"seller\": { \"tax_id\": { \"country_code\": \"ES\", \"identifier\": \"B12345678\" }, \"name\": \"Proveedor SL\" }, \"buyer\": { \"tax_id\": { \"country_code\": \"ES\", \"identifier\": \"S2800000D\" }, \"name\": \"Ayuntamiento de Madrid\" }, \"lines\": [{ \"line_number\": 1, \"description\": \"Suministro\", \"quantity\": 5, \"unit_price\": 200.00, \"vat_rate\": 21.0 }] } } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n#### `es__sign_facturae_xades`\n\nApplies an XAdES-EPES digital signature (ETSI EN 319 132-1) to a Facturae XML document.\nCandidate for promotion to `mcp-einvoicing-core` (XAdES signing, score 3/3).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml` | `string` | Yes | Unsigned Facturae XML |\n| `cert_path` | `string` | Yes | Path to PKCS#12 certificate (`.p12` / `.pfx`) |\n| `signature_policy_id` | `string` | No | Signature policy OID (default: Facturae standard) |\n\nThe certificate password is not accepted as a tool argument (ES-SH-6, avoids plaintext\ncredential exposure in LLM context/logs); set `AEAT_CERTIFICATE_PASSWORD` instead.\n\n```json\n{ \"tool\": \"es__sign_facturae_xades\", \"arguments\": { \"xml\": \"...\", \"cert_path\": \"/certs/empresa.p12\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n#### `es__submit_to_face`\n\nSubmits a signed Facturae XML to FACe (Punto General de Entrada de Facturas Electronicas)\nvia the FACe integrator REST API. Authenticates with a JWS-signed JWT (RS256, `x5c` header)\nminted from the same `AEAT_CERTIFICATE_PATH` / `AEAT_CERTIFICATE_PASSWORD` certificate used\nfor VERI\\*FACTU/SII, per `FACe-manual-api-integradores.pdf` s2.3.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml` | `string` | Yes | Facturae XML with XAdES signature |\n| `administrative_unit` | `string` | Yes | FACe `UnidadTramitadora` code |\n| `accounting_office` | `string` | Yes | FACe `OficinasContables` code |\n| `management_body` | `string` | Yes | FACe `OrganoGestor` code |\n\n```json\n{ \"tool\": \"es__submit_to_face\", \"arguments\": { \"xml\": \"...\", \"administrative_unit\": \"U00000038\", \"accounting_office\": \"U00000038\", \"management_body\": \"U00000038\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n#### `es__get_face_invoice_status`\n\nQueries the processing status of an invoice on FACe. Returns standard status codes:\n1200 (Registered), 2400 (Acknowledged), 3100 (Rejected), 4100 (Paid). The raw FACe\nresponse is never echoed to the LLM; only a structured, non-sensitive subset\n(`status_code`, `codigo`, `descripcion`, `numeroRegistro`) is returned (ES-SH-7).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `invoice_id` | `string` | Yes | FACe registration number |\n\n```json\n{ \"tool\": \"es__get_face_invoice_status\", \"arguments\": { \"invoice_id\": \"FAC-2025-00012345\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n#### `es__validate_facturae_schema`\n\nValidates a Facturae XML against the official Facturae 3.2.2 XSD using `lxml`. Returns\nstructured errors with XPath locations.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml` | `string` | Yes | Facturae XML to validate |\n| `schema_version` | `string` | No | Schema version (default: `\"3.2.2\"`) |\n\n```json\n{ \"tool\": \"es__validate_facturae_schema\", \"arguments\": { \"xml\": \"...\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n### SII (Suministro Inmediato de Informacion)\n\n#### `es__build_sii_invoice_record`\n\nBuilds an AEAT SII XML record (issued `FacturaExpedida` or received `FacturaRecibida`)\nconforming to the AEAT SII technical guide v3.0 (April 2024). Supports `TipoComunicacion` A0/A1/A4.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `invoice` | `InvoiceDocument` | Yes | Core invoice model |\n| `record_type` | `string` | Yes | `\"issued\"` or `\"received\"` |\n| `communication_type` | `string` | No | `\"A0\"` new (default), `\"A1\"` modification, `\"A4\"` cancellation |\n\n```json\n{ \"tool\": \"es__build_sii_invoice_record\", \"arguments\": { \"invoice\": { \"date\": \"2025-03-15\", \"number\": \"2025-0042\" }, \"record_type\": \"issued\", \"communication_type\": \"A0\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n#### `es__submit_sii_batch`\n\nSubmits a batch of invoices (up to 10,000 records) to the AEAT SII SOAP endpoint. Requires MTLS.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `records` | `array` | Yes | List of XML strings from `es__build_sii_invoice_record` |\n| `record_type` | `string` | Yes | `\"issued\"` or `\"received\"` |\n| `fiscal_year` | `integer` | Yes | Fiscal year (YYYY) |\n\n```json\n{ \"tool\": \"es__submit_sii_batch\", \"arguments\": { \"records\": [\"...\"], \"record_type\": \"issued\", \"fiscal_year\": 2025 } }\n```\n\n> โ ๏ธ Pending regulatory confirmation: `AuthMode.MTLS` is not yet implemented in `mcp-einvoicing-core`.\n\n---\n\n#### `es__query_sii_status`\n\nQueries the status of a submitted SII batch via `ConsultaFactInformadasEmitidas` or\n`ConsultaFactInformadasRecibidas`.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `nif_titular` | `string` | Yes | NIF of the SII titular (obligado tributario) |\n| `nombre_titular` | `string` | Yes | Name or company name of the titular |\n| `fiscal_year` | `integer` | Yes | Fiscal year (YYYY) |\n| `period` | `string` | Yes | Settlement period: `\"01\"`..`\"12\"` for monthly, or `\"0A\"` for annual |\n| `record_type` | `string` | No | `\"issued\"` or `\"received\"` (default: `\"issued\"`) |\n| `invoice_number` | `string` | No | `NumSerieFacturaEmisor` to filter by a specific invoice |\n| `emisor_nif` | `string` | No | Issuer NIF to filter by (only applies to `\"received\"`) |\n\n```json\n{ \"tool\": \"es__query_sii_status\", \"arguments\": { \"nif_titular\": \"B12345674\", \"nombre_titular\": \"Ejemplo SL\", \"fiscal_year\": 2025, \"period\": \"03\", \"record_type\": \"issued\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n#### `es__generate_sii_correction`\n\nGenerates an SII modification (`A1`) or cancellation (`A4`) record referencing the original\ninvoice via `IDFactura`. The credit note builder is a candidate for `mcp-einvoicing-core`\n(score 3/3).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `original_invoice` | `InvoiceDocument` | Yes | Invoice being corrected |\n| `corrected_invoice` | `InvoiceDocument` | No | Corrected data (`null` for A4) |\n| `correction_type` | `string` | Yes | `\"A1\"` or `\"A4\"` |\n| `record_type` | `string` | Yes | `\"issued\"` or `\"received\"` |\n\n```json\n{ \"tool\": \"es__generate_sii_correction\", \"arguments\": { \"original_invoice\": { \"number\": \"2025-0042\" }, \"correction_type\": \"A1\", \"record_type\": \"issued\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n### TicketBAI\n\n#### `es__generate_ticketbai_xml`\n\nGenerates a TicketBAI XML invoice with XAdES signature and `HuellaTBAI` chain. Automatically\nselects the correct provincial XSD: Araba v1.2, Gipuzkoa v1.2, Bizkaia v2.1.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `invoice` | `InvoiceDocument` | Yes | Core invoice model |\n| `province` | `string` | Yes | `\"araba\"`, `\"gipuzkoa\"` or `\"bizkaia\"` |\n| `previous_hash` | `string` | No | `HuellaTBAI` of the preceding record |\n| `software_license` | `string` | Yes | TicketBAI software license key |\n| `cert_path` | `string` | Yes | Signing certificate path |\n| `cert_password` | `string` | Yes | Certificate password |\n\n```json\n{ \"tool\": \"es__generate_ticketbai_xml\", \"arguments\": { \"invoice\": { \"date\": \"2025-03-15\", \"number\": \"2025-0042\" }, \"province\": \"gipuzkoa\", \"software_license\": \"TBAI-GI-12345\", \"cert_path\": \"/certs/empresa.p12\", \"cert_password\": \"s3cr3t\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation: the three provincial XSDs must be packaged separately; cross-province validation is not permitted.\n\n---\n\n#### `es__submit_ticketbai`\n\nSubmits a TicketBAI XML record to the corresponding Basque provincial authority. The endpoint\nis automatically routed: Araba (`batuz.eus`), Gipuzkoa (`tbai.egoitza.gipuzkoa.eus`),\nBizkaia (`www.bizkaia.eus/ogasun`).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml` | `string` | Yes | Signed TicketBAI XML |\n| `province` | `string` | Yes | `\"araba\"`, `\"gipuzkoa\"` or `\"bizkaia\"` |\n| `nif` | `string` | Yes | Sender NIF |\n\n```json\n{ \"tool\": \"es__submit_ticketbai\", \"arguments\": { \"xml\": \"...\", \"province\": \"bizkaia\", \"nif\": \"B12345678\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n#### `es__validate_ticketbai_schema`\n\nValidates a TicketBAI XML document against the correct provincial XSD. The schemas\n**are not interchangeable** between provinces.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml` | `string` | Yes | TicketBAI XML |\n| `province` | `string` | Yes | `\"araba\"`, `\"gipuzkoa\"` or `\"bizkaia\"` |\n\n```json\n{ \"tool\": \"es__validate_ticketbai_schema\", \"arguments\": { \"xml\": \"...\", \"province\": \"gipuzkoa\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n### Crea y Crece / B2B\n\n#### `es__generate_b2b_einvoice_es`\n\nGenerates a B2B invoice conforming to EN 16931 in UBL 2.1 or Facturae 3.2.2 format\nper Ley 18/2022, developed by RD 238/2026 (BOE-A-2026-7295).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `invoice` | `InvoiceDocument` | Yes | Core invoice model |\n| `format` | `string` | No | `\"ubl\"` (default) or `\"facturae\"` |\n\n```json\n{ \"tool\": \"es__generate_b2b_einvoice_es\", \"arguments\": { \"invoice\": { \"date\": \"2025-03-15\", \"number\": \"2025-0042\" }, \"format\": \"ubl\" } }\n```\n\n> โ ๏ธ RD 238/2026 confirms the admitted formats (EN 16931: CII/UBL/EDIFACT/Facturae; this\n> tool implements UBL and Facturae). The Orden Ministerial (Hacienda) developing the\n> public-solution technical package (Disp. final tercera) is still pending.\n\n---\n\n#### `es__check_b2b_mandate_applicability`\n\nDetermines the applicable regime (VERI\\*FACTU, SII, TicketBAI, NaTicket) based on\nturnover, province code, and SII enrollment. Applies the mutual exclusion logic of\nReal Decreto 254/2025.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `annual_turnover_eur` | `number` | Yes | Annual VAT turnover in EUR |\n| `tax_address_province_code` | `string` | Yes | INE province code (e.g., `\"28\"` Madrid) |\n| `enrolled_in_sii` | `boolean` | No | SII enrollment (default: `false`) |\n| `entity_type` | `string` | No | `\"IS\"` (Impuesto sobre Sociedades) or `\"IRPF\"` |\n\n```json\n{ \"tool\": \"es__check_b2b_mandate_applicability\", \"arguments\": { \"annual_turnover_eur\": 2500000, \"tax_address_province_code\": \"28\", \"enrolled_in_sii\": false, \"entity_type\": \"IS\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n### Utility tools\n\n#### `es__detect_regional_regime`\n\nDetects the applicable e-invoicing regime based on the INE province code.\nReturns `VERIFACTU`, `TICKETBAI`, `NATICKET`, or `VERIFACTU+SII`.\n\nBasque provinces: `01` Araba, `20` Gipuzkoa, `48` Bizkaia. Navarre: `31`.\nAll others return `VERIFACTU`. Candidate for promotion to `mcp-einvoicing-core`.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `province_code` | `string` | Yes | Two-digit INE province code |\n| `enrolled_in_sii` | `boolean` | No | SII enrollment (default: `false`) |\n\n```json\n{ \"tool\": \"es__detect_regional_regime\", \"arguments\": { \"province_code\": \"20\", \"enrolled_in_sii\": false } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n#### `es__get_compliance_status`\n\nReturns the current mandate deadlines and operating system for a business profile.\nReflects RD-ley 15/2025, subject to changes by subsequent legislation.\nCandidate for promotion to `mcp-einvoicing-core` (generic deadline registry).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `entity_type` | `string` | Yes | `\"IS\"` or `\"IRPF\"` |\n| `province_code` | `string` | Yes | INE province code |\n| `annual_turnover_eur` | `number` | No | For SII threshold check (6M EUR) |\n| `enrolled_in_sii` | `boolean` | No | SII enrollment |\n\n```json\n{ \"tool\": \"es__get_compliance_status\", \"arguments\": { \"entity_type\": \"IS\", \"province_code\": \"28\", \"annual_turnover_eur\": 1000000, \"enrolled_in_sii\": false } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n---\n\n#### `es__parse_aeat_response`\n\nParses and normalizes an AEAT XML response (VERI\\*FACTU or SII) into structured JSON.\nExtracts `EstadoEnvio` (`Correcto`/`AceptadoConErrores`/`Incorrecto`), `CSV`\n(secure verification code), and error details. Candidate for promotion to\n`mcp-einvoicing-core` (generic vendor XML response parser, score 2/3).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml` | `string` | Yes | Raw AEAT XML response |\n| `response_type` | `string` | No | `\"verifactu\"` (default) or `\"sii\"` |\n\n```json\n{ \"tool\": \"es__parse_aeat_response\", \"arguments\": { \"xml\": \"...\", \"response_type\": \"verifactu\" } }\n```\n\n> โ ๏ธ Pending regulatory confirmation\n\n## Architecture\n\n`mcp-facturacion-electronica-es` is a country adapter within the `mcp-einvoicing` family,\nbuilt on `mcp-einvoicing-core`.\n\n```\nmcp-einvoicing-core (v0.1.0+)\nโ BaseDocumentGenerator, BaseDocumentValidator, BaseLifecycleManager\nโ InvoiceDocument, InvoiceParty, InvoiceLineItem, VATSummary, PaymentTerms\nโ EInvoicingError, ValidationError, XSDValidationError, PlatformError\nโ BaseEInvoicingClient, OAuthConfig, AuthMode (OAUTH2 / BEARER / MTLS)\nโ get_logger, format_amount, xml_element, format_error\nโ\nโโโ mcp-facture-electronique-fr (France โ XP Z12-013, Chorus Pro)\nโโโ mcp-einvoicing-be (Belgium โ Peppol BIS 3.0, PINT-BE, Mercurius)\nโโโ mcp-facturacion-electronica-es (Spain โ this package)\nโ โโโ verifactu/ record generation, hash chain, QR, cancellation\nโ โโโ facturae/ Facturae 3.2.2 XML, XAdES-EPES, FACe submission\nโ โโโ sii/ batch building, AEAT SOAP, corrections\nโ โโโ ticketbai/ XML generation, provincial routing, validation\nโ โโโ b2b/ UBL/Facturae Crea y Crece, mandate detector\nโ โโโ utils/ regime detection, AEAT response parser, deadline registry\nโโโ mcp-fattura-elettronica-it (Italy โ FatturaPA / SDI)\nโโโ mcp-ksef-pl (Poland โ KSeF / FA(2))\n```\n\n## Supported standards\n\nThe Spanish e-invoicing ecosystem has **six coexisting systems** with distinct scopes,\nformats, and timelines. VERI\\*FACTU introduces tamper-proof chained invoice records\nsubmitted in real time to the AEAT (Agencia Estatal de Administracion Tributaria),\napplicable to most businesses from 2027 (RD-ley 15/2025). SII is already mandatory for\nlarge taxpayers under a 4-day communication window. Facturae XML with XAdES-EPES signing\ncovers all B2G invoicing through the FACe portal. The Basque Country applies TicketBAI\nindependently, with three provincial authorities each maintaining their own XSD schemas and\nendpoints. Navarre operates NaTicket. The Ley Crea y Crece mandates B2B e-invoicing for\nall businesses; RD 238/2026 (BOE-A-2026-7295) confirms the admitted formats (EN 16931:\nCII/UBL/EDIFACT/Facturae), while the Orden Ministerial developing the public-solution\ntechnical package is still pending. Regime detection\nbased on tax domicile and turnover is a prerequisite to all other operations: use\n`es__detect_regional_regime` first.\n\n### Regulatory coverage\n\n| System | Scope | Format | Mandatory from | Status |\n|---|---|---|---|---|\n| **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) |\n| **Facturae / FACe** | B2G (public sector) | Facturae 3.2.2 + XAdES-EPES | Mandatory since 2015 (Ley 25/2013) | Implemented (pending regulatory confirmation) |\n| **SII** | Turnover >6M EUR, VAT groups, REDEME | XML SOAP/REST AEAT | Already mandatory (RD 596/2016) | Implemented (pending regulatory confirmation) |\n| **TicketBAI** | Araba, Gipuzkoa, Bizkaia | Provincial XML + XAdES + QR | By province, 2022-2023 | Removed from scope (v0.2.0) |\n| **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) |\n| **NaTicket** | Navarre | Foral XML + signature | Foral mandate (phased rollout) | Partial (via `es__detect_regional_regime`) |\n\n> **SII / VERI\\*FACTU mutual exclusion (Real Decreto 254/2025):** Taxpayers enrolled in\n> SII are exempt from VERI\\*FACTU. Use `es__check_b2b_mandate_applicability`\n> before generating any record.\n\n### Compliance notes\n\n> **Notice:** Mandate dates reflect RD-ley 15/2025 (December 2025) and are\n> subject to changes by subsequent legislation or AEAT administrative instructions.\n> This software does not constitute legal or tax advice.\n\n**Mandate timeline**\n\n| System | Targets | Deadline |\n|---|---|---|\n| SII | Turnover >6M EUR / VAT groups / REDEME | Already mandatory (RD 596/2016) |\n| Facturae/FACe | All B2G suppliers | Already mandatory (Ley 25/2013) |\n| TicketBAI | All businesses in the Basque Country | Phased rollout by sector 2022-2023 |\n| VERI\\*FACTU | IS (Impuesto sobre Sociedades) taxpayers | **January 2027** (RD-ley 15/2025) |\n| VERI\\*FACTU | IRPF + other non-SII | **July 2027** (RD-ley 15/2025) |\n| Crea y Crece B2B | Turnover >8M EUR (art. 121 Ley 37/1992) | **12 months** after the Orden Ministerial's entry into force `[Unverified date]` |\n| Crea y Crece B2B | All other businesses | **24 months** after the Orden Ministerial's entry into force `[Unverified date]` |\n\n**Regional exceptions**\n\n- **Basque Country:** TicketBAI applies **instead of** VERI\\*FACTU.\n Each of the three provinces (Araba, Gipuzkoa, Bizkaia) has a different XSD, endpoint,\n and software certification process. National AEAT endpoints do not apply.\n- **Navarre:** NaTicket applies (Hacienda Foral de Navarra). VERI\\*FACTU does not apply.\n- **Ceuta / Melilla:** IPSI (not VAT); SII/VERI\\*FACTU applicability differs, verify with the AEAT.\n- **SII / VERI\\*FACTU mutual exclusion:** Real Decreto 254/2025 makes these systems\n mutually exclusive. Taxpayers enrolled in SII do not submit VERI\\*FACTU records.\n\nAll AEAT submission endpoints require an FNMT-RCM certificate or one from an accredited CA.\nThe AEAT provides a free test environment at `prewww2.aeat.es`.\n\n## Tests\n\n```bash\n# Install development dependencies\nuv sync --all-extras\n\n# Run the full test suite\nuv run pytest tests/ -v\n\n# With coverage report\nuv run pytest --cov=mcp_facturacion_electronica_es --cov-report=term-missing\n```\n\n## Contributing\n\nOpen an issue before starting significant work. For reusable utility logic across country\nadapters, open a `core-promotion` issue in `mcp-einvoicing-core` before implementing it:\nuse the scoring rubric (3 = MUST promote, 2 = SHOULD, 1 = keep here).\n\n```bash\ngit clone https://github.com/cmendezs/mcp-facturacion-electronica-es.git\ncd mcp-facturacion-electronica-es\nuv sync --all-extras\nuv run pytest\nmake audit\n```\n\nAll regulatory assertions must reference a specific BOE publication, an official XSD version,\nor an AEAT technical guide version. Do not remove\n`โ ๏ธ Pending regulatory confirmation` without linking the verified source in the\nPR description.\n\n## Other e-invoicing MCP servers\n\n| Country | Server |\n|---------|--------|\n| ๐ Global | [mcp-einvoicing-core](https://github.com/cmendezs/mcp-einvoicing-core) |\n| ๐ง๐ช Belgium | [mcp-einvoicing-be](https://github.com/cmendezs/mcp-einvoicing-be) |\n| ๐ง๐ท Brazil | [mcp-nfe-br](https://github.com/cmendezs/mcp-nfe-br) |\n| ๐ซ๐ท France | [mcp-facture-electronique-fr](https://github.com/cmendezs/mcp-facture-electronique-fr) |\n| ๐ฉ๐ช Germany | [mcp-einvoicing-de](https://github.com/cmendezs/mcp-einvoicing-de) |\n| ๐ฎ๐ณ India | [mcp-einvoicing-in](https://github.com/cmendezs/mcp-einvoicing-in) |\n| ๐ฎ๐น Italy | [mcp-fattura-elettronica-it](https://github.com/cmendezs/mcp-fattura-elettronica-it) |\n| ๐ฒ๐ฝ Mexico | [mcp-cfdi-mx](https://github.com/cmendezs/mcp-cfdi-mx) |\n| ๐ต๐ฑ Poland | [mcp-ksef-pl](https://github.com/cmendezs/mcp-ksef-pl) |\n| ๐ธ๐ฌ Singapore | [mcp-invoicenow-sg](https://github.com/cmendezs/mcp-invoicenow-sg) |\n| ๐ช๐ธ Spain | [mcp-facturacion-electronica-es](https://github.com/cmendezs/mcp-facturacion-electronica-es) |\n| ๐ฆ๐ช United Arab Emirates | [mcp-einvoicing-ae](https://github.com/cmendezs/mcp-einvoicing-ae) |\n\n## License\n\nReleased under the [Apache License 2.0](LICENSE). For the full version history, see [CHANGELOG.md](CHANGELOG.md).\n",
"bytes": 35020,
"sha": "f43568a11d62b98c1b1af9ad4d2f22b2e753895462f96e604cd16b955de0e7c1",
"repo_slug": "cmendezs/mcp-facturacion-electronica-es",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cmendezs_mcp_facturacion_elect_c8115c05/readme"
}