Factuarea APIDevelopers
Improved

Tax reports: working workbook and agent tools

Tax reports use an Excel working workbook and expose nine MCP tools. Existing report endpoints now document their supported output formats precisely.

The excel format of the Modelo 303, 347 and 130 was a published contract that always failed: announced in the enum, in the request schemas, in the v1 route and in the CLI's --format excel, and returning 422 unsupported_format in every case. It now produces a real workbook. See Tax reports.

  • format: "excel" works for the three modelsPOST /v1/tax_reports/303, /347 and /130 return a .xlsx workbook with two sheets, Resumen and Detalle, both headed by model, fiscal period and declaring company. Amounts are written as numbers, so a column can be summed in the sheet; zeros are written as 0 rather than left blank.
  • 347 — summary of declared clients and suppliers, total amount and how many counterparties cleared the 3,005.06 € threshold; one detail row per counterparty with its NIF, province, annual base and four quarters, which add up to the base. 303 — the aggregates that determine the balance, with accrued VAT and surcharge broken down by tax rate. 130 — derived boxes in the summary, starting boxes in the detail.
  • It is not filed with the AEAT, and it says so inside the file — the first rows of Resumen carry the notice that the workbook is working material and that filing happens with the official TXT. Its figures are still trustworthy: they come from the same domain calculation as the official file, so two formats of the same filing can never disagree.
  • A year with no counterparty above the threshold still produces a workbook, with an empty detail sheet and a summary that says so. It is the ordinary case for a small company, not an error.
  • Nine new MCP tools for a domain that had nine published routes and no tools: generate_tax_report_303, generate_tax_report_347 and generate_tax_report_130 (tax_reports:write), plus preview, find-by-period, history, stats, activities and download (tax_reports:read). No new scope family — both scopes already existed. See the tool catalog.

Contract correction (generated clients). Nine binary operations declared application/json with a text or object body while returning a file: the tax report download, the quote and pro-forma PDFs, the invoice Excel export and PDF preview, the purchase-invoice attachment and payment receipt, and the two monthly time-close exports. They now declare their real media types (application/pdf, text/plain, text/csv, image/jpeg, image/png, spreadsheet) with a binary schema. Nothing changed on the wire — no typed client could have worked against the previous type — but if you use a generated SDK or the CLI, regenerate it: your model for these operations will change. The CLI's hand-maintained list of binary corrections is gone, because the spec no longer lies.

Updated endpoints4

EndpointDescription
POST/v1/tax_reports/130Generate Modelo 130
POST/v1/tax_reports/303Generate Modelo 303
POST/v1/tax_reports/347Generate Modelo 347
GET/v1/tax_reports/{tax_report}/downloadDownload tax report file