Get the fiscal summary of a company
Scopeinvoices:readReturns the VAT and IRPF summary of the invoices issued under this company over the requested period, together with the annual IRPF projection and its progressive bracket breakdown.
start_date and end_date go together: send both, or neither. Omitting both defaults to the current month; sending only one answers 400, because a period you did not ask for is worse than an error. The range may not exceed 365 days, and every fault names itself in details.reason.
Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key
short of the scope an operation needs is answered 403. The scope an operation requires
is shown next to its title, and the full catalogue lives in the Scopes reference.
Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.
In: header
Path Parameters
Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
uuidQuery Parameters
Period start date (inclusive), as YYYY-MM-DD. Goes together with end_date:
supply both or neither. Omitting both defaults to the current month; supplying
only one is rejected with 400 (PERIOD_INCOMPLETE).
datePeriod end date (inclusive), as YYYY-MM-DD. Goes together with start_date:
supply both or neither. Omitting both defaults to the current month; supplying
only one is rejected with 400 (PERIOD_INCOMPLETE).
dateResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/fiscal-summary"{
"success": true,
"data": {
"queried_period": {
"start_date": "2025-01-01",
"end_date": "2025-03-31",
"days_included": 90
},
"total_taxable_base": 15000,
"total_vat": 3150,
"tax_breakdown": [
{
"tax_type": "IVA",
"percentage": 21,
"taxable_base": 8000,
"tax_amount": 1680
},
{
"tax_type": "IGIC",
"percentage": 7,
"taxable_base": 2000,
"tax_amount": 140
}
],
"vat_breakdown_by_rate": {
"21.000": 3150
},
"surcharge_breakdown": [
{
"type": 5.2,
"base": 1000,
"amount": 52
}
],
"total_equivalence_surcharge": 52,
"total_irpf_withheld": 750,
"period_base": 15000,
"projected_annual_base": 60000,
"estimated_annual_irpf": 14582.5,
"pending_annual_irpf": 11546.17,
"bracket_details": [
{
"base_from": 0,
"base_to": 12450,
"rate_percentage": 19,
"applicable_base": 12450,
"amount": 2365.5
}
],
"invoices": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"invoice_number": "F2025/001",
"issue_date": "2025-01-15",
"customer_name": "Empresa SL",
"taxable_base": 1000,
"total_vat": 210,
"total_irpf": 150,
"invoice_total": 1060
}
],
"total_invoices": 12
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You do not have permission to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again in 60 seconds."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Update invoice series (deprecated) PUT
**Deprecated.** The canonical form has a single update verb, `PATCH /v1/companies/{company_id}/series/{series_id}`. The same body produces the same result there — this route already merges field by field, leaving absent fields untouched — with one difference: an explicit `description: null`, which this route ignores, clears the description under `PATCH`. Updates an existing invoice series with the body you send; absent fields keep their value. - **Numbering fields:** `code`, `format`, `counter_reset` and `initial_number` are rejected once the series has issued invoices (`numbering_locked` is `true`). `name`, `description`, `active`, `default_series` and `document_type` can always be changed. - **`active`:** a default series cannot be deactivated — set another one as default first. - **`default_series`:** sending `false` on the series that currently is the default is rejected with `DEFAULT_CANNOT_BE_UNMARKED`. Promote another series with `PUT /v1/companies/{company_id}/series/{series_id}/default`, which unmarks the previous one for you. An inactive series cannot be marked as default. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.
Provision an account POST
Provisions a new account on BeeL and, when it is born with a holder, returns a single-use `claim_token` to deliver so they can set a password and take ownership. - **`email`:** send it to create the account with a holder. Omit it and the account is created with no person at all, no `person_id` and no `claim_token`; a holder can be added later with `POST /v1/accounts/{account_id}/claim-tokens`. - **`tax_profile`:** send it and the account comes back ready to invoice, with its NIF, default invoice series and VeriFactu configuration set up. Omit it and the account's company is created without a NIF until its holder registers one. Either way its `company_id` is in the response. - **`access_level`:** the access you retain over the account. Defaults to `NONE`; `OPERATE` requires a `tax_profile`. - **`external_ref`:** the idempotency key. Resending the same one returns the existing account rather than creating a second. - **Entitlement:** requires `manage_accounts`. ## Reactivation If you previously ended your management of this account (`DELETE /v1/accounts/{account_id}/management`) and its holder has not claimed it yet, provisioning the same email reactivates that account instead of creating a new one. The same account, holder, NIFs and invoices come back under your management, with the `external_ref` and `access_level` of this request, and it counts towards your billable usage again. Once the holder has claimed the account it is theirs, and only they can grant you access again.