Update the tax configuration of a company
Scopeconfiguration:writeUpdates 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.
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.
uuidTax exemption reason code per Spanish VAT Law (Ley 37/1992 LIVA). VeriFactu mapping: EXENTA_ART_20→E1, EXENTA_ART_21→E2, EXENTA_ART_22→E3, EXENTA_ART_24→E4, EXENTA_ART_25→E5, rest→E6. ISP→S2, NO_SUJETA→N1/N2. When OTRO, a custom text must be provided in exemption_reason_text.
"EXENTA_ART_20" | "EXENTA_ART_21" | "EXENTA_ART_22" | "EXENTA_ART_24" | "EXENTA_ART_25" | "EXENTA_ART_26" | "EXENTA_ART_140" | "NO_SUJETA_ART_7_9" | "NO_SUJETA_LOCALIZACION" | "ISP_ART_84_2_A" | "ISP_ART_84_2_E" | "ISP_ART_84_2_F" | "REGIMEN_ART_129" | "REGIMEN_ART_135" | "REGIMEN_ART_141" | "REGIMEN_ART_154" | "REGIMEN_ART_163_DECIES" | "OTRO"Custom exemption text, mandatory when default_exemption_reason is OTRO.
Only EXENTA_ART_20 and OTRO can be declared as a default — the reasons a
NIF can verify on its own. The rest depend on the recipient, the operation or
the regime, so they are declared per invoice line; sending one returns 422.
A 0% VAT/IPSI without a reason is also rejected with 422: in those taxes 0% is
not a rate, it is the sentinel of an operation carrying no tax.
length <= 500Whether the freelancer is under the equivalence surcharge regime.
Omit it to leave the current value untouched. On creation, omitting it means false.
Equivalence surcharge percentage in decimal format. Pairs allowed (rate ↔ recargo): 4↔0.5, 5↔0.625 (RD-ley 11/2022), 10↔1.4, 21↔5.2. The backend automatically normalizes equivalent formats (5.20 → 5.2).
0 | 0.5 | 0.625 | 1.4 | 5.2Whether IRPF withholding should be applied.
Omit it to leave the current value untouched. On creation, omitting it means false:
a withholding nobody declared is not applied.
Personal income tax/withholding percentage in integer format. Allowed values: 0 (exempt), 1 (agricultural/livestock/forestry), 2 (reduced for modules), 7, 15, 19, 24 (non-residents).
0 | 1 | 2 | 7 | 15 | 19 | 24Whether the freelancer is exempt from IRPF withholding.
Omit it to leave the current value untouched. On creation, omitting it means false.
Default payment method for new invoices. If NONE is selected, no payment information will be shown on the invoice.
Default payment term in days (0-365)
0 <= value <= 365Default validity term in days for new proformas (0-365).
Send null to clear it (proformas stop getting a prefilled expiry date).
0 <= value <= 365Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/tax-configuration" \ -H "Content-Type: application/json" \ -d '{}'{
"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": "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": "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": "VALIDATION_ERROR",
"message": "Validation error",
"details": {
"field_name": "Field is required"
}
},
"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"
}
}Get the tax configuration of a company GET
Retrieves 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.
Get complete tax types catalog GET
**Deprecated.** Use `GET /v1/tax-types`, which returns exactly the same catalog. The catalog is the same for every credential, so it does not belong under `/v1/configuration`, which is where the settings of a NIF live. The response announces the retirement date in its `Sunset` header. Retrieves the complete catalog of available tax types with structured information for tax configuration in Spain: - **Tax regimes**: VAT (Peninsula), IGIC (Canary Islands), IPSI (Ceuta/Melilla), OTHERS - **Percentages per regime**: Valid percentages for each tax type - **Regime codes**: VeriFactu codes for each tax type - **IRPF**: Available withholding percentages - **Equivalence surcharge**: Automatic mappings based on VAT percentage - **Utilities**: Validation functions and geographic auto-detection This endpoint provides all necessary information for the frontend without duplicating tax validation logic.