{ "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" } } ``` > ⚠️ Pending regulatory confirmation: XSD v1.0 (HAC/1177/2024) not yet validated against the AEAT test environment. --- #### `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": "..." } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__submit_verifactu_to_aeat` Submits a signed VERI\*FACTU record to the AEAT real-time endpoint via MTLS (FNMT-RCM Class 1 certificate). Respects `AEAT_ENV=sandbox|production`. | 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": "...", "nif": "B12345678" } } ``` > ⚠️ Pending regulatory confirmation: `AuthMode.MTLS` is not yet implemented in `mcp-einvoicing-core`; tracked in the core gaps backlog. --- #### `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). | 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_amount": 1210.00 } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__cancel_verifactu_record` Generates a VERI\*FACTU cancellation record (`IndicadorAnulacion=S`, `TipoHuella=01`) chained to the current fingerprint sequence. | Parameter | Type | Required | Description | |---|---|---|---| | `original_invoice_number` | `string` | Yes | `NumSerieFactura` to cancel | | `original_invoice_date` | `string` | Yes | `FechaExpedicionFactura` (YYYY-MM-DD) | | `issuer_nif` | `string` | Yes | Issuer NIF | | `previous_hash` | `string` | Yes | `Huella` of the last record in the chain | ```json { "tool": "es__cancel_verifactu_record", "arguments": { "original_invoice_number": "2025-0042", "original_invoice_date": "2025-03-15", "issuer_nif": "B12345678", "previous_hash": "3C4A9B..." } } ``` > ⚠️ Pending regulatory confirmation --- ### Facturae / FACe #### `es__generate_facturae_xml` Generates a Facturae 3.2.2 compliant XML invoice for B2G submission. Uses `InvoiceDocument` from `mcp-einvoicing-core`. | Parameter | Type | Required | Description | |---|---|---|---| | `invoice` | `InvoiceDocument` | Yes | Core invoice model | | `schema_version` | `string` | No | Facturae schema version (default: `"3.2.2"`) | ```json { "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 }] } } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__sign_facturae_xades` Applies an XAdES-EPES digital signature (ETSI EN 319 132-1) to a Facturae XML document. Candidate for promotion to `mcp-einvoicing-core` (XAdES signing, score 3/3). | Parameter | Type | Required | Description | |---|---|---|---| | `xml` | `string` | Yes | Unsigned Facturae XML | | `cert_path` | `string` | Yes | Path to PKCS#12 certificate (`.p12` / `.pfx`) | | `cert_password` | `string` | Yes | Certificate password | | `signature_policy_id` | `string` | No | Signature policy OID (default: Facturae standard) | ```json { "tool": "es__sign_facturae_xades", "arguments": { "xml": "...", "cert_path": "/certs/empresa.p12", "cert_password": "s3cr3t" } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__submit_to_face` Submits a signed Facturae XML to FACe (Punto General de Entrada de Facturas Electronicas) via the FACe B2B REST API v2. Requires OAuth2 (`FACE_CLIENT_ID` / `FACE_CLIENT_SECRET`). | Parameter | Type | Required | Description | |---|---|---|---| | `xml` | `string` | Yes | Facturae XML with XAdES signature | | `administrative_unit` | `string` | Yes | FACe `UnidadTramitadora` code | | `accounting_office` | `string` | Yes | FACe `OficinasContables` code | | `management_body` | `string` | Yes | FACe `OrganoGestor` code | ```json { "tool": "es__submit_to_face", "arguments": { "xml": "...", "administrative_unit": "U00000038", "accounting_office": "U00000038", "management_body": "U00000038" } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__get_face_invoice_status` Queries the processing status of an invoice on FACe. Returns standard status codes: 1200 (Registered), 2400 (Acknowledged), 3100 (Rejected), 4100 (Paid). | Parameter | Type | Required | Description | |---|---|---|---| | `invoice_id` | `string` | Yes | FACe registration number | ```json { "tool": "es__get_face_invoice_status", "arguments": { "invoice_id": "FAC-2025-00012345" } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__validate_facturae_schema` Validates a Facturae XML against the official Facturae 3.2.2 XSD using `lxml`. Returns structured errors with XPath locations. | Parameter | Type | Required | Description | |---|---|---|---| | `xml` | `string` | Yes | Facturae XML to validate | | `schema_version` | `string` | No | Schema version (default: `"3.2.2"`) | ```json { "tool": "es__validate_facturae_schema", "arguments": { "xml": "..." } } ``` > ⚠️ Pending regulatory confirmation --- ### SII (Suministro Inmediato de Informacion) #### `es__build_sii_invoice_record` Builds an AEAT SII XML record (issued `FacturaExpedida` or received `FacturaRecibida`) conforming to the AEAT SII technical guide v3.0 (April 2024). Supports `TipoComunicacion` A0/A1/A4. | Parameter | Type | Required | Description | |---|---|---|---| | `invoice` | `InvoiceDocument` | Yes | Core invoice model | | `record_type` | `string` | Yes | `"issued"` or `"received"` | | `communication_type` | `string` | No | `"A0"` new (default), `"A1"` modification, `"A4"` cancellation | ```json { "tool": "es__build_sii_invoice_record", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "record_type": "issued", "communication_type": "A0" } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__submit_sii_batch` Submits a batch of invoices (up to 10,000 records) to the AEAT SII SOAP endpoint. Requires MTLS. | Parameter | Type | Required | Description | |---|---|---|---| | `records` | `array` | Yes | List of XML strings from `es__build_sii_invoice_record` | | `record_type` | `string` | Yes | `"issued"` or `"received"` | | `fiscal_year` | `integer` | Yes | Fiscal year (YYYY) | ```json { "tool": "es__submit_sii_batch", "arguments": { "records": ["..."], "record_type": "issued", "fiscal_year": 2025 } } ``` > ⚠️ Pending regulatory confirmation: `AuthMode.MTLS` is not yet implemented in `mcp-einvoicing-core`. --- #### `es__query_sii_status` Queries the status of a submitted SII batch via `ConsultaFactInformadasEmitidas` or `ConsultaFactInformadasRecibidas`. | Parameter | Type | Required | Description | |---|---|---|---| | `batch_id` | `string` | Yes | Batch reference returned by `es__submit_sii_batch` | | `record_type` | `string` | Yes | `"issued"` or `"received"` | ```json { "tool": "es__query_sii_status", "arguments": { "batch_id": "SII-BATCH-20250315-001", "record_type": "issued" } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__generate_sii_correction` Generates an SII modification (`A1`) or cancellation (`A4`) record referencing the original invoice via `IDFactura`. The credit note builder is a candidate for `mcp-einvoicing-core` (score 3/3). | Parameter | Type | Required | Description | |---|---|---|---| | `original_invoice` | `InvoiceDocument` | Yes | Invoice being corrected | | `corrected_invoice` | `InvoiceDocument` | No | Corrected data (`null` for A4) | | `correction_type` | `string` | Yes | `"A1"` or `"A4"` | | `record_type` | `string` | Yes | `"issued"` or `"received"` | ```json { "tool": "es__generate_sii_correction", "arguments": { "original_invoice": { "number": "2025-0042" }, "correction_type": "A1", "record_type": "issued" } } ``` > ⚠️ Pending regulatory confirmation --- ### TicketBAI #### `es__generate_ticketbai_xml` Generates a TicketBAI XML invoice with XAdES signature and `HuellaTBAI` chain. Automatically selects the correct provincial XSD: Araba v1.2, Gipuzkoa v1.2, Bizkaia v2.1. | Parameter | Type | Required | Description | |---|---|---|---| | `invoice` | `InvoiceDocument` | Yes | Core invoice model | | `province` | `string` | Yes | `"araba"`, `"gipuzkoa"` or `"bizkaia"` | | `previous_hash` | `string` | No | `HuellaTBAI` of the preceding record | | `software_license` | `string` | Yes | TicketBAI software license key | | `cert_path` | `string` | Yes | Signing certificate path | | `cert_password` | `string` | Yes | Certificate password | ```json { "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" } } ``` > ⚠️ Pending regulatory confirmation: the three provincial XSDs must be packaged separately; cross-province validation is not permitted. --- #### `es__submit_ticketbai` Submits a TicketBAI XML record to the corresponding Basque provincial authority. The endpoint is automatically routed: Araba (`batuz.eus`), Gipuzkoa (`tbai.egoitza.gipuzkoa.eus`), Bizkaia (`www.bizkaia.eus/ogasun`). | Parameter | Type | Required | Description | |---|---|---|---| | `xml` | `string` | Yes | Signed TicketBAI XML | | `province` | `string` | Yes | `"araba"`, `"gipuzkoa"` or `"bizkaia"` | | `nif` | `string` | Yes | Sender NIF | ```json { "tool": "es__submit_ticketbai", "arguments": { "xml": "...", "province": "bizkaia", "nif": "B12345678" } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__validate_ticketbai_schema` Validates a TicketBAI XML document against the correct provincial XSD. The schemas **are not interchangeable** between provinces. | Parameter | Type | Required | Description | |---|---|---|---| | `xml` | `string` | Yes | TicketBAI XML | | `province` | `string` | Yes | `"araba"`, `"gipuzkoa"` or `"bizkaia"` | ```json { "tool": "es__validate_ticketbai_schema", "arguments": { "xml": "...", "province": "gipuzkoa" } } ``` > ⚠️ Pending regulatory confirmation --- ### Crea y Crece / B2B #### `es__generate_b2b_einvoice_es` Generates a B2B invoice conforming to EN 16931 in UBL 2.1 or Facturae 3.2.2 format per Ley 18/2022. | Parameter | Type | Required | Description | |---|---|---|---| | `invoice` | `InvoiceDocument` | Yes | Core invoice model | | `format` | `string` | No | `"ubl"` (default) or `"facturae"` | ```json { "tool": "es__generate_b2b_einvoice_es", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "format": "ubl" } } ``` > ⚠️ Pending regulatory confirmation: the B2B mandate implementing regulations have not been published yet. --- #### `es__check_b2b_mandate_applicability` Determines the applicable regime (VERI\*FACTU, SII, TicketBAI, NaTicket) based on turnover, province code, and SII enrollment. Applies the mutual exclusion logic of Real Decreto 254/2025. | Parameter | Type | Required | Description | |---|---|---|---| | `annual_turnover_eur` | `number` | Yes | Annual VAT turnover in EUR | | `tax_address_province_code` | `string` | Yes | INE province code (e.g., `"28"` Madrid) | | `enrolled_in_sii` | `boolean` | No | SII enrollment (default: `false`) | | `entity_type` | `string` | No | `"IS"` (Impuesto sobre Sociedades) or `"IRPF"` | ```json { "tool": "es__check_b2b_mandate_applicability", "arguments": { "annual_turnover_eur": 2500000, "tax_address_province_code": "28", "enrolled_in_sii": false, "entity_type": "IS" } } ``` > ⚠️ Pending regulatory confirmation --- ### Utility tools #### `es__detect_regional_regime` Detects the applicable e-invoicing regime based on the INE province code. Returns `VERIFACTU`, `TICKETBAI`, `NATICKET`, or `VERIFACTU+SII`. Basque provinces: `01` Araba, `20` Gipuzkoa, `48` Bizkaia. Navarre: `31`. All others return `VERIFACTU`. Candidate for promotion to `mcp-einvoicing-core`. | Parameter | Type | Required | Description | |---|---|---|---| | `province_code` | `string` | Yes | Two-digit INE province code | | `enrolled_in_sii` | `boolean` | No | SII enrollment (default: `false`) | ```json { "tool": "es__detect_regional_regime", "arguments": { "province_code": "20", "enrolled_in_sii": false } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__get_compliance_status` Returns the current mandate deadlines and operating system for a business profile. Reflects RD-ley 15/2025, subject to changes by subsequent legislation. Candidate for promotion to `mcp-einvoicing-core` (generic deadline registry). | Parameter | Type | Required | Description | |---|---|---|---| | `entity_type` | `string` | Yes | `"IS"` or `"IRPF"` | | `province_code` | `string` | Yes | INE province code | | `annual_turnover_eur` | `number` | No | For SII threshold check (6M EUR) | | `enrolled_in_sii` | `boolean` | No | SII enrollment | ```json { "tool": "es__get_compliance_status", "arguments": { "entity_type": "IS", "province_code": "28", "annual_turnover_eur": 1000000, "enrolled_in_sii": false } } ``` > ⚠️ Pending regulatory confirmation --- #### `es__parse_aeat_response` Parses and normalizes an AEAT XML response (VERI\*FACTU or SII) into structured JSON. Extracts `EstadoEnvio` (`Correcto`/`AceptadoConErrores`/`Incorrecto`), `CSV` (secure verification code), and error details. Candidate for promotion to `mcp-einvoicing-core` (generic vendor XML response parser, score 2/3). | Parameter | Type | Required | Description | |---|---|---|---| | `xml` | `string` | Yes | Raw AEAT XML response | | `response_type` | `string` | No | `"verifactu"` (default) or `"sii"` | ```json { "tool": "es__parse_aeat_response", "arguments": { "xml": "...", "response_type": "verifactu" } } ``` > ⚠️ Pending regulatory confirmation --- ## Installation ### From PyPI (recommended) ```bash pip install mcp-facturacion-electronica-es ``` Without prior installation, using `uvx`: ```bash uvx mcp-facturacion-electronica-es ``` ### From source ```bash git clone https://github.com/cmendezs/mcp-facturacion-electronica-es.git cd mcp-facturacion-electronica-es uv sync --all-extras ``` --- ## Configuration ### Claude Desktop ```json { "mcpServers": { "facturacion-es": { "command": "uvx", "args": ["mcp-facturacion-electronica-es"], "env": { "AEAT_ENV": "sandbox", "AEAT_CERTIFICATE_PATH": "/path/to/cert.p12", "AEAT_CERTIFICATE_PASSWORD": "certificate-password" } } } }