# Fiscal summary
Read the VAT and IRPF totals of a company for any period of up to 365 days, plus an annual IRPF projection — a starting point for preparing tax returns.
[`GET /v1/companies/{company_id}/fiscal-summary`](/fiscal-summary/getCompanyFiscalSummary)
adds up the invoices of a company over a period and returns what you need at hand when
preparing a quarterly return: the taxable base, the indirect tax charged, the IRPF withheld
by your customers, and an estimate of the income tax for the whole year.
The fiscal summary is a **calculation over your invoices**, not a tax return. BeeL. does
not file anything with the AEAT from it and does not produce any official form. Use it
to prepare or cross-check your returns, and confirm the figures with your tax advisor.
## Choosing the period
`start_date` and `end_date` are inclusive dates in `YYYY-MM-DD` format.
- **Send both, or neither.** With neither, the period is the current month up to today: on
24 September it is 1–24 September. With only one, the request is rejected: you never get
back a period you did not ask for.
- **At most 365 days**, counting both ends. A calendar year fits, except a leap year
(366 days): split it into two requests.
- **Faults answer `400` [`VALIDATION_ERROR`](/errors/VALIDATION_ERROR)** and name themselves in `error.details.reason`,
next to the dates you sent:
| `reason` | Cause |
|---|---|
| `PERIOD_INCOMPLETE` | Only one of `start_date` / `end_date` was sent |
| `PERIOD_INVERTED` | `start_date` is after `end_date` |
| `PERIOD_TOO_LONG` | The range exceeds `details.max_days` (`"365"`, a string) |
A date that is not a valid `YYYY-MM-DD` answers `400` [`VALIDATION_ERROR`](/errors/VALIDATION_ERROR) too, naming the
parameter in `error.details.field`, without a `reason`.
## Which invoices count
- **Fiscal documents only**: `STANDARD`, `CORRECTIVE` and `SIMPLIFIED`. Proformas never
count (see [Proformas](/guides/proformas)).
- **Issued invoices only.** Drafts and scheduled invoices are left out: there is no fiscal
document yet.
- **Corrections net out.** A corrective invoice always counts, with its negative amounts,
and so does the invoice it corrects. The pair adds up to what is actually declarable. The
corrective inherits the operation date of the invoice it corrects, so it lands in the same
period even when it is issued months later.
- **A void without a corrective invoice does not count.** An invoice voided directly (issued
by mistake) is left out entirely.
- **Dated by operation date.** An invoice falls in the period by its `operation_date`, or by
its issue date when it has none. VAT accrues when the operation takes place, so a December
service invoiced in January belongs to the fourth quarter.
- **Same environment as your key.** A test key summarises sandbox invoices; a live key,
production ones.
## A quarterly example
Take a company with a default IRPF of 15 % and these documents, all issued in September
2026 for work done in the first quarter (the date that counts is `operation_date`):
| Document | `operation_date` | Base | IVA 21 % | IRPF 15 % | Counts? |
|---|---|---|---|---|---|
| Invoice | 10 Feb 2026 | 1,000.00 | 210.00 | 150.00 | Yes |
| Invoice | 5 Mar 2026 | 2,000.00 | 420.00 | 300.00 | Yes |
| Invoice | 15 Jan 2026 | 800.00 | 168.00 | 120.00 | Yes |
| Partial corrective of the 800.00 invoice | inherited, 15 Jan 2026 | −200.00 | −42.00 | −30.00 | Yes |
| Invoice voided directly | 20 Mar 2026 | 500.00 | 105.00 | 75.00 | No |
| Draft | 1 Feb 2026 | 999.00 | — | — | No |
```bash
curl "https://app.beel.es/api/v1/companies/{company_id}/fiscal-summary?start_date=2026-01-01&end_date=2026-03-31" \
-H "Authorization: Bearer $BEEL_API_KEY"
```
The response, trimmed:
```json
{
"success": true,
"data": {
"queried_period": {
"start_date": "2026-01-01",
"end_date": "2026-03-31",
"days_included": 90
},
"total_taxable_base": 3600.0,
"total_vat": 756.0,
"tax_breakdown": [
{ "tax_type": "IVA", "percentage": 21.0, "taxable_base": 3600.0, "tax_amount": 756.0, "regime_key": "01" }
],
"surcharge_breakdown": [],
"total_equivalence_surcharge": 0.0,
"total_irpf_withheld": 540.0,
"period_base": 3600.0,
"projected_annual_base": 14600.0,
"estimated_annual_irpf": 2881.5,
"pending_annual_irpf": 691.5,
"bracket_details": [
{ "base_from": 0.0, "base_to": 12450.0, "rate_percentage": 19.0, "applicable_base": 12450.0, "amount": 2365.5 },
{ "base_from": 12450.0, "base_to": 20200.0, "rate_percentage": 24.0, "applicable_base": 2150.0, "amount": 516.0 }
],
"invoices": [
{ "invoice_number": "F-2026-0084", "issue_date": "2026-09-24", "taxable_base": 2000.0, "total_vat": 420.0, "total_irpf": 300.0, "invoice_total": 2120.0 },
{ "invoice_number": "R-2026-0022", "issue_date": "2026-09-24", "taxable_base": -200.0, "total_vat": -42.0, "total_irpf": -30.0, "invoice_total": -212.0 }
],
"total_invoices": 4
}
}
```
*(`invoices` shortened to two of its four entries.)*
The voided invoice and the draft are not in `invoices`, and the corrective is, with its
negative amounts: 1,000 + 2,000 + 800 − 200 = 3,600 of base.
### The period figures
| Field | What it is |
|---|---|
| `total_taxable_base` | Sum of the taxable bases in the period. `period_base` carries the same value. |
| `total_vat` | Indirect tax charged in the period: IVA, IGIC, IPSI and any other rate, not only IVA. |
| `tax_breakdown` | `total_vat` split by tax type, rate and regime key. |
| `total_equivalence_surcharge` | Equivalence surcharge charged. It is **not** part of `total_vat`. |
| `total_irpf_withheld` | IRPF withheld by your customers on the invoices of the period. |
| `invoices` / `total_invoices` | The invoices that went into the calculation, so you can reconcile the totals. |
Index `tax_breakdown` by `(tax_type, percentage, regime_key)`, never by
`(tax_type, percentage)` alone. An invoice that mixes general-regime and OSS lines at the
same rate yields two rows at `percentage: 21` that only `regime_key` tells apart. The older
`vat_breakdown_by_rate` map collapses exactly those rows and is deprecated.
### The annual projection
The IRPF figures extrapolate the period to a full year. They are an estimate, and the
shorter the period, the rougher it is.
- **`projected_annual_base`** is the period base scaled to 365 days:
`period_base × 365 / days_included`. In the example, 3,600 over 90 days projects to 14,600.
- **`estimated_annual_irpf`** applies the progressive IRPF brackets of the **current
calendar year** to that projected base. `bracket_details` shows how much of the base falls
in each bracket and what each one contributes.
- **`pending_annual_irpf`** is the estimate minus the withholdings, also scaled to a year,
and never below zero. In the example the 14,600 of projected base fall in two brackets —
12,450 at 19 % and 2,150 at 24 % — for an estimate of 2,881.50; the withholdings of 540
project to 2,190 a year, so 2,881.50 − 2,190 = 691.50.
The projection only knows your invoices. It does not know about expenses, other income,
personal allowances or payments on account you have already made, so it does not replace
the calculation of an actual return.
## Gotchas
- **Omitting the dates is not "year to date".** It is the current month.
- **One request covers one period.** For a year-on-year or quarter-by-quarter view, make one
request per period.
- **The brackets follow today's date, not the period.** Querying a past year still applies
the brackets of the current year to the projection. The period totals are unaffected.
- **Totals move when invoices change.** Issuing, correcting or voiding an invoice dated
inside a period changes that period's summary the next time you ask for it.
## Related
- [Amounts and rounding](/guides/amounts-and-rounding) — how the bases and taxes are computed
- [Proformas](/guides/proformas) — why proformas stay out of the totals
- [Bulk operations and exports](/guides/bulk-operations-and-exports) — export the invoices behind the figures
---
Full OpenAPI spec: https://docs.beel.es/api/openapi