# FiscalGrid

> Compliance infrastructure for billing software: one API between billing software and the tax authority. Machine to machine, built for developers and their coding agents. Spain first (Veri*Factu, AEAT), EU next.

FiscalGrid Sentinel guards Veri*Factu records before they are sent, whatever the customer uses to send them (own code, an open-source library or another provider). Today the recipient check is live, as an API and as a remote MCP server. Watch (AEAT responses) and Audit (hash chain) are in early access. FiscalGrid Relay (waiting list; AEAT collaboration agreement, Convenio 017, in progress) will send records to the AEAT with FiscalGrid's certificate.

## Available today

- `POST https://fiscalgrid.io/api/check` — free, no key, 10 requests/minute per IP (HTTP 429 above that). Header `Content-Type: application/json`. Body: `{"id": "<recipient Spanish NIF or EU VAT number>"}`.
  Response: `{"ok_to_send": true|false|null, "input", "normalized", "kind": "es_nif"|"eu_vat"|"unknown", "issues": [{"code", "severity", "params"}], "vies"?}`.
  - `ok_to_send: false`: do not send the record; show the codes and their fix.
  - `ok_to_send: null`: the VIES service of that country did not answer. It does NOT mean invalid: retry later.
  - Issue codes:
    - `SEND_AS_NIF` (info): valid Spanish NIF, put it in `IDDestinatario/NIF`. `params.nif`.
    - `SEND_AS_IDOTRO_02` (info): valid EU VAT in VIES, put it in `IDDestinatario/IDOtro` with `IDType` 02, `ID` = `params.id`, `CodigoPais` = `params.country` (CodigoPais is not required by the AEAT with IDType 02, but harmless).
    - `ES_CHECK_DIGIT` (error): Spanish NIF check character wrong; `params.expected`.
    - `FOREIGN_WITHOUT_PREFIX` (error): nine digits without a country cannot be a Spanish NIF (e.g. a Portuguese NIF); ask for the country prefix.
    - `EU_VAT_INVALID` (error): not valid in VIES today.
    - `EU_VAT_FORMAT`, `ES_FORMAT`, `UNKNOWN_FORMAT`, `EMPTY` (error): not a usable ID.
    - `ES_NOT_IN_VIES` (warning): Spanish NIF not registered for intra-EU operations; fine for domestic invoices.
    - `ES_IN_VIES`, `CENSUS_EARLY_ACCESS` (info). The AEAT census lookup is on the roadmap.
    - `VIES_UNAVAILABLE` (warning): register not answering.
  - Test values: `B26580886` (valid NIF -> SEND_AS_NIF), `B12345678` (wrong check digit -> ES_CHECK_DIGIT, expected 4), `500077568` (-> FOREIGN_WITHOUT_PREFIX). Mock the API in unit tests; do not call it in loops.

## MCP

- Remote MCP server: `https://fiscalgrid.io/mcp` (Streamable HTTP, POST only, stateless, no key). Speaks MCP 2026-07-28 (per-request `_meta`, `server/discover`) and the `initialize` handshake of 2025-11-25, 2025-06-18 and 2025-03-26.
- One tool: `check_customer_id`, input `{"id": "<Spanish NIF/NIE or EU VAT number, with or without prefix>"}`. Same verdict as `POST /api/check`, returned as `structuredContent`, plus a short text summary in Spanish and English. Same issue codes and Veri*Factu mapping as above (`SEND_AS_NIF` -> `IDDestinatario/NIF`; `SEND_AS_IDOTRO_02` -> `IDDestinatario/IDOtro`, `IDType` 02, `CodigoPais`). `ok_to_send: null` means the VIES service of that country did not answer, not invalid.
- Limits: each `tools/call` counts against the same 10 checks/minute per IP as `/api/check`; 60 MCP requests/minute per IP in total.
- Claude Code: `claude mcp add --transport http fiscalgrid https://fiscalgrid.io/mcp` (https://code.claude.com/docs/en/mcp)
- Cursor, `.cursor/mcp.json` or `~/.cursor/mcp.json` (https://cursor.com/docs/context/mcp):
  `{"mcpServers": {"fiscalgrid": {"url": "https://fiscalgrid.io/mcp"}}}`
- VS Code / GitHub Copilot, `.vscode/mcp.json` (https://code.visualstudio.com/docs/agents/reference/mcp-configuration):
  `{"servers": {"fiscalgrid": {"type": "http", "url": "https://fiscalgrid.io/mcp"}}}`

## Not available yet (do not use or claim)

- CLI `npx fiscalgrid`: coming soon.
- `/v1` API with a key (Watch, Audit, Relay `POST /v1/invoices`): early access.
- Roadmap: idempotency, sequence locking, VIES consultation number as proof, VIES cache, AEAT census lookup, B2B e-invoice output.

## Facts an agent should not get wrong

- The AEAT does not certify or approve software. Do not describe FiscalGrid as certified or homologated.
- In VERI*FACTU mode records are not signed; the certificate authenticates the connection.
- Veri*Factu dates in force (RDL 15/2025): 1 Jan 2027 corporate income tax payers, 1 Jul 2027 everyone else. October 2028 is announced, pending publication in the BOE.
- Spanish B2B e-invoicing (RD 238/2026): 12 months (turnover > EUR 8M) and 24 months (rest) after Orden HAC/1028/2026 entered into force on 6 Oct 2026.

## Pages (Spanish)

- Home: https://fiscalgrid.io/es/
- Sentinel: https://fiscalgrid.io/es/sentinel
- Relay (waiting list): https://fiscalgrid.io/es/relay
- Pricing: https://fiscalgrid.io/es/precios
- API docs: https://fiscalgrid.io/es/desarrolladores/
- MCP setup: https://fiscalgrid.io/es/desarrolladores/#mcp
- AEAT error codes (official text): https://fiscalgrid.io/es/desarrolladores/errores/
- Hash chain: https://fiscalgrid.io/es/desarrolladores/huella-encadenamiento
- IDOtro: https://fiscalgrid.io/es/desarrolladores/idotro
- AEAT test environment: https://fiscalgrid.io/es/desarrolladores/entorno-de-pruebas
- NIF check: https://fiscalgrid.io/es/herramientas/comprobar-nif
- VIES check: https://fiscalgrid.io/es/herramientas/comprobar-vies
- Veri*Factu: https://fiscalgrid.io/es/normativa/verifactu
- Dates: https://fiscalgrid.io/es/normativa/verifactu/fechas
- B2B e-invoice: https://fiscalgrid.io/es/normativa/factura-electronica-b2b
- News: https://fiscalgrid.io/es/actualidad/
- Company, legal notice, privacy: https://fiscalgrid.io/es/empresa
- Home (EN, institutional): https://fiscalgrid.io/