Get the tax configuration of a company
Scopeconfiguration:readRetrieves the tax configuration of this company (NIF), including:
- Default tax regime (VAT, IGIC, IPSI, OTHERS)
- Default main tax percentage
- IRPF and equivalence surcharge configuration
The catalog of tax types this configuration draws from is not company data and lives outside this resource.
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.
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
},
"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 required"
},
"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": "La factura debe tener al menos una línea",
"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 Spanish law allows on an invoice: 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. 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. Use it to validate a rate before sending it, or to build your own picker instead of hard-coding the percentages. **VAT lists 4, 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 with an `exemption_reason`, which this same response publishes under `exemption_reasons`. Offering a bare 0 % in a picker seeded configurations with no reason behind them and every line built from them was rejected. IGIC does list 0: there it is the real "Tipo Cero" and needs no reason. The 5 % VAT rate (RD-ley 11/2022) is kept even though it no longer applies to new operations, because correctives and late filings for those periods still need it.
Update the tax configuration of a company PUT
Updates the tax configuration of this company (NIF). **Business rules:** the main tax and its VeriFactu regime key must be coherent. Regime key `18` (equivalence surcharge) only exists for VAT, so pairing it with IGIC, IPSI or OTHERS answers `422` `INVALID_REGIME_KEY_FOR_TAX_TYPE`, with `details` naming the rejected key, the tax type and the keys that type admits. Applying the surcharge without regime key `18` answers `422` `RECARGO_REQUIRES_REGIME_RE`.