---
title: "Preview a tax report"
method: POST
path: "/companies/{company}/tax-reports/preview"
tags: ["Tax Reports"]
---

# Preview a tax report

`POST /companies/{company}/tax-reports/preview`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/tax-reports/preview`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Computes the breakdown of a tax report without persisting a generation or writing files. Ideal for interactive UIs that confirm totals before commit.

## Path parameters

- `company` string, uuid, required

## Headers

- `Factuarea-Version` string, date

## Request body

- PreviewTaxReportV1Request: Compute the breakdown of a tax report without persisting any generation or file. Useful to show what is about to be declared before confirming. `303` and `347` are accepted as aliases of `modelo_303` and `modelo_347`, consistent with `POST /v1/companies/{company}/tax-reports/303` and `POST /v1/companies/{company}/tax-reports/347`.
  - `type` 'modelo_303' | 'modelo_347' | 'modelo_130', required
  - `year` integer, required
  - `quarter` integer, nullable

## Response `200`

- object
  - `data` TaxReportPreview, required: Preview (dry-run computation, without persisting any file) of a Modelo 303/347 for a period. Lets the integrator validate the amounts before generating the final report. Amounts are expressed in euro cents (integers).
    - `object` 'tax_report_preview', required
    - `type` 'modelo_303' | 'modelo_347', required: Type of previewed report.
    - `period` object, required: Previewed fiscal period.
      - `year` integer, required: Fiscal year.
      - `quarter` integer, nullable, required: Quarter (1-4), or `null` for annual reports (347).
      - `label` string, required: Human-readable period label (e.g. `2026 Q1`).
    - `breakdown_303` object, required: Breakdown by VAT rate (Modelo 303 only). Map indexed by tax rate → `{base, cuota}` in cents. Empty for Modelo 347.
    - `totals` object, required: Aggregated totals of the declaration (amounts in cents).
    - `clients_347` object[], required: Operations with clients that exceed the Modelo 347 threshold (Modelo 347 only). Empty for Modelo 303.
      - `taxId` string, nullable: Client tax ID (NIF/CIF).
      - `partyName` string, nullable: Name or legal/business name of the client.
      - `base` integer: Total annual amount of operations, in cents.
      - `quarters` object: Amount per quarter (quarter key → amount in cents).
    - `suppliers_347` object[], required: Operations with suppliers that exceed the Modelo 347 threshold (Modelo 347 only). Empty for Modelo 303.
      - `taxId` string, nullable: Supplier tax ID (NIF/CIF).
      - `partyName` string, nullable: Name or legal/business name of the supplier.
      - `base` integer: Total annual amount of operations, in cents.
      - `quarters` object: Amount per quarter (quarter key → amount in cents).
    - `invoice_count` integer, required: Number of issued invoices considered in the period.
    - `purchase_invoice_count` integer, required: Number of expenses considered in the period.
    - `warnings` string[], required: Non-blocking warnings detected during the computation (e.g. invoices with incomplete data).
    - `warning_codes` string[], required: Stable machine-readable codes paired one-to-one (same index) with `warnings`. Branch on these instead of matching the Spanish text; unknown codes should fall back to the corresponding `warnings` entry.

## Other responses

- `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).
- `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).
- `422`: Validation failed for the tax report request — e.g. an invalid period (Modelo 303 requires a quarter, Modelo 347 does not admit one, or the year is out of range), no invoices in the period, or an unsupported output format. The `error.param` field identifies which input is invalid.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)