Informes fiscals

Un informe fiscal és una declaració calculada a partir de les teves pròpies dades de facturació per a un període i materialitzada en un fitxer. Factuarea cobreix els tres models espanyols que una empresa emissora de factures presenta per si mateixa, produeix cadascun en tres formats i desa totes les generacions en un històric que pots llistar, auditar i tornar a descarregar.

Tots els endpoints viuen sota https://api.factuarea.com/v1. Generar usa tax_reports:write; previsualitzar, llistar i descarregar usen tax_reports:read.

Els tres models

year i format són obligatoris en tots tres. El quarter l'exigeixen el 303 i el 130, i el 347 l'ignora: el 347 és anual i no existeix cap 347 trimestral. Els exercicis suportats comencen el 2024.

curl -X POST https://api.factuarea.com/v1/tax_reports/303 \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2026, "quarter": 1, "format": "txt_aeat" }'

Tres formats, un sol càlcul

Els tres models produeixen les mateixes tres sortides, i totes tres es construeixen a partir del mateix càlcul de domini. Es diferencien en per a què serveixen, no en el que diuen.

Dit això —i aquesta és l'altra meitat de la regla— les xifres del PDF i del llibre són fiables. No es recalculen per a la capa de presentació: surten exactament del mateix càlcul que produeix el fitxer oficial, així que quadrar contra elles és quadrar contra allò que presentaràs. Que un import diferís entre dos formats de la mateixa declaració és impossible per construcció.

El llibre d'Excel

El llibre té exactament dos fulls —Resumen i Detalle— i tots dos s'obren amb la mateixa etiqueta de context: model, període fiscal i empresa declarant amb el seu NIF. Un full es copia a un altre llibre o s'imprimeix a part, i aleshores res del context de l'aplicació no hi viatja.

Les primeres files de Resumen, abans de qualsevol dada, porten l'avís:

AVISO: este libro es material de trabajo y NO es presentable ante la AEAT.
La presentación se realiza con el fichero oficial en formato TXT que genera
la propia aplicación.

L'advertiment viu dins del fitxer expressament. El llibre es descarrega, s'adjunta a un correu i s'obre en un altre ordinador, que és justament on algú podria intentar presentar-lo. Un avís que només existís a la pantalla que va originar la descàrrega no hi seria, en aquell moment.

Què posa cada model a cada full:

Dues propietats en què pots confiar:

• Els imports són nombres, no text formatat. Una columna d'imports se suma al full mateix sense conversió prèvia, i un zero s'escriu com a 0 en comptes de deixar-se en blanc: en un informe econòmic una cel·la buida es llegeix com a «sense dada», no com a «zero».
• A cada fila del 347, els quatre trimestres sumen la base anual. La columna Tipo és el que distingeix una compra d'una venda tan bon punt reordenes el full.

Generar, descarregar, conservar l'històric

Una generació és un recurs persistit. Els tres endpoints de model retornen 201 amb l'informe i el seu id; el fitxer s'obté a part, tantes vegades com calgui.

# 1. Generar — retorna 201 amb l'id de l'informe
curl -X POST https://api.factuarea.com/v1/tax_reports/347 \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2025, "format": "excel" }'

# 2. Descarregar el fitxer que va produir
curl -G https://api.factuarea.com/v1/tax_reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/download \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --output modelo-347-2025.xlsx

GET /v1/tax_reports/{tax_report}/download transmet el fitxer amb el tipus de contingut del format amb què es va generar —text posicional, PDF o full de càlcul— i hi afegeix una capçalera X-Tax-Report-Hash amb què verificar que els bytes que vas arxivar són els que es van generar.

La resta del domini llegeix aquest mateix històric:

Per veure les xifres abans de comprometre't amb un fitxer, usa POST /v1/tax_reports/preview amb type, year i quarter: calcula el mateix desglossament, no persisteix res i no escriu cap fitxer. És la crida que va darrere d'una pantalla de «revisar abans de presentar».

Errors que has de preveure

Referència completa a Tots els error codes.

Des d'un agent

Les mateixes nou operacions estan exposades com a MCP tools: generate_tax_report_303, generate_tax_report_347 i generate_tax_report_130 sota tax_reports:write, i previsualització, cerca per període, històric, estadístiques, activitat i descàrrega sota tax_reports:read. Consulta el catàleg de tools.

Passos següents