API de FiscalGrid para desarrolladores · Verifactu

POST /api/check DISPONIBLE

Gratis, sin clave. Límite: 10 consultas por minuto por IP (responde 429 si lo superas).

curl -X POST https://fiscalgrid.io/api/check \
  -H "Content-Type: application/json" \
  -d '{"id":"PT500077568"}'

Respuesta

{
  "ok_to_send": true | false | null,
  "input": "PT500077568",
  "normalized": "PT500077568",
  "kind": "es_nif" | "eu_vat" | "unknown",
  "issues": [{ "code": "SEND_AS_IDOTRO_02", "severity": "info",
               "params": { "country": "PT", "id": "PT500077568" } }],
  "vies": { ... }   // solo si se consultó VIES
}

ok_to_send: null significa que el VIES de ese país no respondió. No es inválido: reintenta más tarde.
Los códigos no llevan texto: tu software los traduce al idioma de tu usuario.

Códigos

Código	Gravedad	Significado
`SEND_AS_NIF`	info	NIF español válido: va en IDDestinatario/NIF. params.nif
`SEND_AS_IDOTRO_02`	info	NIF-IVA válido en VIES: va en IDDestinatario/IDOtro con IDType 02. params.country, params.id
`ES_CHECK_DIGIT`	error	Letra o dígito de control erróneo. params.expected
`FOREIGN_WITHOUT_PREFIX`	error	Nueve cifras sin país: no puede ser un NIF español
`EU_VAT_INVALID`	error	No válido hoy en VIES. params.country
`EU_VAT_FORMAT · ES_FORMAT · UNKNOWN_FORMAT · EMPTY`	error	No es un identificador utilizable
`ES_NOT_IN_VIES`	warning	NIF español sin alta intracomunitaria: vale para factura nacional
`VIES_UNAVAILABLE`	warning	El VIES del país no responde: ok_to_send es null, reintenta
`ES_IN_VIES · CENSUS_EARLY_ACCESS`	info	Informativos

Con tu agente de código

Pega este prompt en Claude Code, Cursor, GitHub Copilot o Codex:

Añade FiscalGrid Sentinel Check a este proyecto de facturación.

1. Lee primero https://fiscalgrid.io/llms.txt.
2. Busca dónde se genera y se envía cada registro Veri*Factu a la AEAT. Justo antes, llama a POST https://fiscalgrid.io/api/check con {"id": "<NIF o NIF-IVA del destinatario>"}.
3. Si ok_to_send es false: no envíes el registro. Muestra al usuario los códigos de "issues" y su corrección.
4. Si ok_to_send es null (el VIES de ese país no responde): reintenta más tarde. No lo trates como inválido.
5. Lleva el resultado al registro: SEND_AS_NIF -> IDDestinatario/NIF. SEND_AS_IDOTRO_02 -> IDDestinatario/IDOtro con IDType 02, ID = params.id y CodigoPais = params.country.
6. Añade tests con la respuesta simulada para B26580886 (NIF válido), B12345678 (dígito de control erróneo) y 500077568 (número extranjero sin prefijo de país).
7. No cambies cómo se envían hoy los registros. Haz un cambio pequeño y explícalo.

El contexto completo para agentes está en /llms.txt.

Servidor MCP DISPONIBLE

Servidor MCP remoto en https://fiscalgrid.io/mcp (Streamable HTTP, sin clave). Tiene una herramienta, check_customer_id, que devuelve lo mismo que POST /api/check: el veredicto en datos estructurados y un resumen corto en español y en inglés. Cada llamada a la herramienta cuenta en el mismo límite de 10 consultas por minuto por IP.

Claude Code

claude mcp add --transport http fiscalgrid https://fiscalgrid.io/mcp

Cursor

En .cursor/mcp.json (proyecto) o ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "fiscalgrid": { "url": "https://fiscalgrid.io/mcp" }
  }
}

VS Code y GitHub Copilot

En .vscode/mcp.json:

{
  "servers": {
    "fiscalgrid": { "type": "http", "url": "https://fiscalgrid.io/mcp" }
  }
}

Formatos según la documentación de Claude Code, Cursor y VS Code.

CLI PRÓXIMAMENTE

Un CLI (npx fiscalgrid check <id>). Todavía no existe: cuando esté, aparecerá aquí y en llms.txt.

API /v1 con clave ACCESO ANTICIPADO

Vigilar las respuestas de la AEAT y auditar la cadena de huellas, con clave de API. En hoja de ruta: idempotencia en los reenvíos, bloqueo de secuencia y número de consulta de VIES como prueba.

Guías

Códigos de error de la AEAT, con el texto oficial.
Huella y encadenamiento, con los ejemplos oficiales.
IDOtro: clientes extranjeros en el registro.
Entorno de pruebas de la AEAT.

Una llamada antes de cada envío.