Fiscal summary

GET /v1/companies/{company_id}/fiscal-summary 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.

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 and name themselves in error.details.reason, next to the dates you sent:

A date that is not a valid YYYY-MM-DD answers 400 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).
• 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):

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:

{
  "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

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