Get complete tax types catalog (deprecated)
Scopeconfiguration:readDeprecated. Use GET /v1/tax-types, which returns exactly the same catalog. It is
reference data shared by every account, not the settings of a NIF, so it does not belong
under /v1/configuration.
Returns the catalog of Spanish tax regimes with their valid percentages and VeriFactu regime codes.
tax_regimes: the tax types and the percentages and regime keys each one admits.irpf_types: the available IRPF withholding rates.equivalence_surcharges: the surcharge that corresponds to each VAT percentage.exemption_reasons: the accepted exemption reasons.
Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.
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
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/configuration/tax-types"{
"success": true,
"data": {
"tax_regimes": [
{
"code": "IVA",
"name": "IVA",
"description": "Value Added Tax",
"tax_rates": [
{
"percentage": 21,
"description": "IVA (21%)",
"active": true,
"associated_equivalence_surcharge": 5.2,
"valid_from": null,
"valid_until": null
}
],
"applies_equivalence_surcharge": true,
"regime_keys": [
{
"code": "01",
"description": "General regime operation"
}
]
}
],
"irpf_types": [
{
"percentage": 15,
"description": "IRPF Profesional (15%)",
"active": true
}
],
"equivalence_surcharges": [
{
"percentage": 5.2,
"associated_vat": 21,
"description": "RE 5.2% (IVA 21%)",
"active": true,
"valid_from": null,
"valid_until": null
}
],
"exemption_reasons": [
{
"code": "EXENTA_ART_20",
"label": "invoice.exemption.EXENTA_ART_20",
"description": "invoice.exemption.EXENTA_ART_20",
"category": "OPERACIONES EXENTAS",
"classification_type": "EXENTA",
"available_as_default": false,
"available_on_invoice_line": true
}
]
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"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": "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 the tax configuration of a company PUT
Updates the tax configuration of a company. Fields you omit keep their current value; `default_main_tax`, when sent, replaces the stored one wholesale. - **Regime coherence:** the main tax and its VeriFactu regime key must be coherent. Regime key `18` (equivalence surcharge) only exists for `IVA`, so pairing it with any other regime answers `422 INVALID_REGIME_KEY_FOR_TAX_TYPE`, with `details` naming the rejected key, the tax type and the keys that type admits. - **Surcharge:** applying the surcharge without regime key `18` answers `422` `RECARGO_REQUIRES_REGIME_RE`. - **Exemption reason:** `default_exemption_reason` travels with `default_main_tax` — sending the tax without a reason clears the stored one, and sending only the reason applies it to the tax already stored. - **Coherence of the result:** the configuration as it stands after the change is checked as a whole, and answers `422` with one of these codes: `MAIN_TAX_REQUIRED` (there is no `default_main_tax`, stored or sent), `IRPF_REQUIRED_WHEN_NOT_EXEMPT` (`apply_irpf` without `irpf_exempt` and no `default_irpf_rate`), `RECARGO_EQUIVALENCIA_REQUIRED` (`apply_equivalence_surcharge` without `default_equivalence_surcharge`), `RECARGO_IVA_COMBINATION_INVALID` (a surcharge rate that does not go with the main IVA rate), `EXEMPTION_REASON_NOT_ALLOWED_AS_DEFAULT` (a `default_exemption_reason` that only makes sense line by line), `EXEMPTION_REASON_REQUIRES_ZERO_RATE` (an exemption reason on a main tax that is not 0%), `ZERO_RATE_REQUIRES_EXEMPTION_REASON` (a 0% main tax with no reason) or `EXEMPTION_REASON_TEXT_REQUIRED` (a reason that needs `default_exemption_reason_text` and has none). - **First write:** two concurrent requests that both create the configuration answer the loser with `409 TAX_CONFIG_CONFLICT`; retrying it updates the one that won.
Get user tax configuration (deprecated) GET
**Deprecated.** Use `GET /v1/companies/{company_id}/tax-configuration`, which behaves identically. Retrieves the tax configuration of the company in focus: the default main tax (`IVA`, `IGIC`, `IPSI` or `OTHER`) with its percentage and regime key, the default exemption reason, the IRPF and equivalence surcharge settings, and the default payment method and payment term. **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.