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.
The totals are always computed over every invoice in the period. The list of those invoices is not returned unless you ask for it with include=invoices: it grows with the period and is not paginated, so request it only when you need the per-invoice figures.
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).
dateAdds data that is left out by default. invoices adds the invoices list: one entry per invoice counted in the totals. Omit it and the response carries the totals only; an unsupported value answers 400.
"invoices"Response 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"
}
}Create or update a custom field of a company PUT
Creates the custom field with this `key`, or updates it if the company already has one. Repeating the request leaves the same state, so it is safe to run on every deployment to seed a catalogue. - **Status:** `201` when the field is created, `200` when it already existed. - **Key:** it is the path, never the body, and it never changes. To stop using a field, archive it (`is_archived: true`); fields are never deleted. - **Archive state:** omitting `is_archived` keeps the current one, so repeating the request never reactivates a field someone archived. - **Suggestions:** omitting `suggest_values` keeps the current setting; a new field starts with `true`. Use `false` for a value that changes on every invoice, such as an order number: invoices store the text as sent and no options are created. Turning it off deletes no option, and turning it back on offers them again. - **Options:** the response carries the common options of the field, or none when `suggest_values` is `false`.
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.