Get the fiscal summary of a company for a period
Scopeinvoices:readReturns the VAT and IRPF summary of the invoices issued under this company (NIF) for the requested period, together with the annual IRPF projection and its progressive bracket breakdown. The period defaults to the current month and may not exceed 365 days. Requires the invoices:read scope.
API Key authentication.
Format: Authorization: Bearer beel_sk_<key>
Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with
specific scopes that limit which endpoints it can access. The required scope for each
endpoint is documented in the operation's security section under OAuth2.
Obtaining Keys: API Keys are managed from the BeeL dashboard
Security: API Keys are secret credentials. Do not share them or store them in source code
In: header
Path Parameters
NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed.
uuidQuery Parameters
Period start date (inclusive). Format: YYYY-MM-DD
datePeriod end date (inclusive). Format: YYYY-MM-DD
dateResponse Body
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.00": 3150
},
"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": "BAD_REQUEST",
"message": "Invalid request"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required"
},
"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"
}
}Replace invoice series PUT
**Deprecated.** This route will be retired on the date announced in its `Sunset` response header. 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`. Replaces an existing invoice series with the body you send. Numbering fields (`code`, `format`, `counter_reset`, `initial_number`) are rejected once the series has issued invoices; `name`, `description`, `active`, `default_series` and `document_type` can always be changed. Business rules: - Cannot deactivate a default series (must set another as default first) - Cannot mark an inactive series as default
Provision an account POST
Provisions a new account on BeeL. and returns a one-time `claim_token` to deliver to the account holder so they can set their password and take ownership. The holder can be an self-employed individual or a legal entity. Privileged: requires the `accounts:write` scope (only on your provisioner key). Idempotent by `external_ref`. Use `access_level` to choose the management level you keep over the account (default: billing only — you pay their subscription but do not see their data). 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.