Get the tax configuration of a company
Scopeconfiguration:readReturns the tax configuration of a company: its default main tax (IVA, IGIC,
IPSI or OTHER) with the default percentage and regime key, the default exemption
reason, its IRPF and equivalence surcharge settings, and the default payment method and
payment term.
The catalogue of tax types this configuration draws from is not company data and lives outside this resource.
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.
uuidResponse 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/tax-configuration"{
"success": true,
"data": {
"default_main_tax": {
"type": "IVA",
"percentage": 21,
"regime_key": "01"
},
"default_exemption_reason": "EXENTA_ART_20",
"default_exemption_reason_text": "string",
"apply_equivalence_surcharge": false,
"default_equivalence_surcharge": 5.2,
"apply_irpf": false,
"default_irpf_rate": 15,
"irpf_exempt": false,
"default_payment_method": "BANK_TRANSFER",
"payment_term_days": 365,
"proforma_validity_days": 365,
"withholding_options": {
"allowed_irpf_rates": [
0,
19,
24
],
"suggested_irpf_rate": 0
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
"details": {
"field": "invoice_id",
"invalid_value": "deliveries",
"expected_format": "UUID"
}
},
"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": "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": "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"
}
}List the tax types allowed in Spain GET
Returns the tax regimes and percentages that BeeL accepts on an invoice. Use it to validate a rate before sending it, or to build your own picker instead of hard-coding the percentages. - **Contents:** VAT (mainland), IGIC (Canary Islands), IPSI (Ceuta and Melilla), the withholding (IRPF) percentages, the equivalence surcharge that corresponds to each VAT rate, and the exemption reasons with the classification each one implies. - **Scope:** the catalogue is the same for every credential and does not depend on any account or on any NIF, so the operation takes no identifier and works before the first NIF exists. ## VAT rates and the zero case - **VAT lists 2, 4, 5, 7.5, 10 and 21, and deliberately not 0:** under VAT (and IPSI) a 0 % is not a rate but the exemption/non-subject sentinel, and on its own it says nothing. A 0 % line is only valid together with an `exemption_reason`, which this same response publishes under `exemption_reasons`. - **IGIC does list 0:** there it is the real "Tipo Cero" and needs no reason. - **Temporary VAT rates carry their period:** 5 % (2022-07-01 to 2024-09-30), and 2 % and 7.5 % (2024-10-01 to 2024-12-31) are listed with `valid_from` / `valid_until`. They no longer apply to new operations but stay listed, because correctives and late filings for those periods still need them; an invoice whose operation date falls outside the period is rejected with `422 VAT_RATE_NOT_ACCEPTED_ON_DATE`. Every other rate has both `null`. - **Equivalence surcharges are listed per VAT ↔ surcharge pair**, each with its period.
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.