# Update tax configuration (deprecated) API Reference **Deprecated.** Use `PUT /v1/companies/{company_id}/tax-configuration`, which behaves identically. Updates the tax configuration of the company in focus. Fields you omit keep their current value. - **Regime coherence:** the main tax and its VeriFactu regime key must match. Regime key `18` (equivalence surcharge) only exists for `IVA`, so pairing it with `IGIC`, `IPSI` or `OTHER` 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. **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. ## PUT /v1/configuration/taxes **Update tax configuration** **Deprecated.** Use `PUT /v1/companies/{company_id}/tax-configuration`, which behaves identically. Updates the tax configuration of the company in focus. Fields you omit keep their current value. - **Regime coherence:** the main tax and its VeriFactu regime key must match. Regime key `18` (equivalence surcharge) only exists for `IVA`, so pairing it with `IGIC`, `IPSI` or `OTHER` 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. **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. **Deprecated.** ### Authentication Accepts any of: - `ApiKeyAuth` (HTTP bearer, token format `beel_sk_*`) ### Request Body Required. **Content `application/json`:** - **default_main_tax**: Default main tax configuration. If provided, completely replaces the current configuration. It travels together with `default_exemption_reason`: sending the tax without a reason clears the stored one (going back from 0% to 21% cannot leave an orphan "art. 20 exempt" behind), and sending only the reason applies it to the tax already stored. Sending neither leaves the current declaration untouched. - **default_exemption_reason** `ExemptionReason`: Tax exemption reason code per the Spanish VAT Law (Ley 37/1992, LIVA), with the VeriFactu code each one is reported as. - `EXENTA_ART_20`: exempt, art. 20 (domestic operations such as medical, educational, cultural and financial services, or housing rentals). E1. - `EXENTA_ART_21`: exempt, art. 21 (exports of goods). E2. - `EXENTA_ART_22`: exempt, art. 22 (operations treated as exports). E3. - `EXENTA_ART_24`: exempt, art. 24 (free zones, warehouses and customs regimes). E4. - `EXENTA_ART_25`: exempt, art. 25 (intra-community supplies of goods). E5. - `EXENTA_ART_26`: exempt, art. 26 (intra-community acquisitions of goods). It exempts the buyer's acquisition, not a supply the seller invoices, so an invoice line that carries it is rejected with `EXEMPTION_NOT_FOR_ISSUED_INVOICE`; a supply to another Member State is `EXENTA_ART_25`. - `NO_SUJETA_ART_7_9`: not subject under art. 7 (such as the transfer of a business as a going concern, art. 7.1º). N1. - `NO_SUJETA_LOCALIZACION`: not subject by the place-of-supply rules (intra-community or non-EU services, arts. 69 and 70). N2. - `ISP_ART_84_2_A` … `ISP_ART_84_2_F`: reverse charge (the invoice states «inversión del sujeto pasivo»), art. 84.Uno.2.º letters a) (supplier not established in Spain), b) (unwrought or semi-finished gold), c) (scrap, waste and recovery materials, plastic, paper, cardboard, glass and textile waste, and semi-finished non-ferrous metal products), d) (greenhouse gas emission allowances), e) (certain real estate supplies: in insolvency proceedings, with the exemption waived, or enforcing a security) and f) (construction or renovation works). S2. - `ISP_ART_84_2_G`: reverse charge of letter g) (silver, platinum, palladium, mobile phones, consoles, laptops and tablets). The law requires these supplies to be invoiced in a special series, so an invoice line that carries it is rejected with `REVERSE_CHARGE_CASE_NOT_SUPPORTED`. - `EXENTA_ART_140`: investment gold exemption, art. 140 bis (usually with `regime_key` `04`). E6. - `REGIMEN_ART_129` (agriculture, livestock and fishing, arts. 124 to 134 bis), `REGIMEN_ART_135` (second-hand goods, art and antiques), `REGIMEN_ART_141` (travel agencies), `REGIMEN_ART_154` (equivalence surcharge) and `REGIMEN_ART_163_DECIES` (cash basis, arts. 163 decies to 163 sexiesdecies): operations of special regimes, which VeriFactu identifies by the regime key rather than by an exemption code. An invoice line that carries one is rejected with `EXEMPTION_REGIME_NOT_SUPPORTED_IN_VERIFACTU`; declare the regime with `regime_key` instead. - `OTRO`: any other provision. Requires the text in `exemption_reason_text`. E6. - **default_exemption_reason_text** `string`: 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. - **apply_equivalence_surcharge** `boolean`: Whether the freelancer is under the equivalence surcharge regime. Omit it to leave the current value untouched. On creation, omitting it means `false`. - **default_equivalence_surcharge** `EquivalenceSurchargePercentage`: Equivalence surcharge percentage in decimal format, one of the values AEAT accepts. Pairs allowed (VAT rate ↔ surcharge): 21↔5.2, 21↔1.75 (tobacco products), 10↔1.4, 4↔0.5, and the temporary ones, only on operations of their period: 5↔0.5 up to 2022-12-31, 5↔0.62 from 2023-01-01 to 2024-09-30, and 7.5↔1 and 2↔0.26 from 2024-10-01 to 2024-12-31. A pair outside its period is rejected with `422 SURCHARGE_RATE_NOT_ACCEPTED_ON_DATE`. `GET /v1/tax-types` publishes every pair with its `valid_from` / `valid_until`. The backend automatically normalizes equivalent formats (5.20 → 5.2). - **apply_irpf** `boolean`: Whether 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. - **default_irpf_rate** `IrpfPercentage`: Withholding (IRPF) percentage, as the IRPF regulation (Royal Decree 439/2007) sets it: 0 (no withholding), 1 (pig fattening and poultry, and some activities under objective estimation), 2 (other agricultural, livestock and forestry activities), 7 (professional activity in its first three years, and the other 7 % cases), 15 (professional activities, and intellectual property income), 19 (rent of urban property and other income of art. 75.2.b; also the general rate of the Corporate Income Tax withholding) and 24 (image rights). A company that pays Corporate Income Tax can only use 0, 19, 24 and 9.5: see `WithholdingOptions`. Ceuta and Melilla: income with the Ceuta and Melilla deduction bears the base rate reduced as the law sets it. Under IRPF, 15 % and 7 % (professional activities) and 19 % (rent of urban property located there) are reduced by 60 %: 6, 2.8 and 7.6. Under Corporate Income Tax, 19 % on those rents is halved: 9.5, which only a company can use (`IRPF_RATE_ONLY_FOR_CORPORATE_ISSUER` otherwise). Whether the reduction applies is the issuer's choice: the NIF does not show it. The value counts, not how it is written: `15.0` is `15` and `2.80` is `2.8`. - **irpf_exempt** `boolean`: Whether the freelancer is exempt from IRPF withholding. Omit it to leave the current value untouched. On creation, omitting it means `false`. - **default_payment_method** `string`: Default payment method for new invoices. If NONE is selected, no payment information will be shown on the invoice. - **payment_term_days** `integer`: Default payment term in days (0-365). Omit it to leave the current value untouched; send `null` to clear it. - **proforma_validity_days** `integer`: Default validity term in days for new proformas (0-365). Omit it to leave the current value untouched; send `null` to clear it (proformas stop getting a prefilled expiry date). ### Responses #### 200: Configuration updated successfully **Content `application/json`:** - **success** (required) `boolean`: No description (example: true) - **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1. - **meta** `ResponseMeta` - **data** `TaxConfiguration` #### 400: Bad request. From a dashboard session, a `BeeL-Environment` header whose value is not a known environment answers `ENVIRONMENT_HEADER_INVALID`, with the header named in `error.details` (`{"BeeL-Environment": "invalid"}`); it is never read as production. `BUSINESS_RULE_VIOLATION` is the generic answer to an operation the resource does not admit in its current state when that state has no code of its own. It carries no `details`; read the resource again before retrying. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "success": false, "error": { "code": "BAD_REQUEST", "message": "Invalid request" }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### 401: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Authentication is required to access this resource" }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### 403: Authenticated but not allowed. Fourteen causes shared by every operation, told apart by `error.code`; an operation that adds a cause of its own names it in its `403`. You can branch on them exhaustively. - `INSUFFICIENT_SCOPE` — the credential lacks a scope the operation requires; `error.details.missing_scopes` names them as a single comma-separated string (for example `"invoices:write,customers:read"`), not as an array; `required_scopes` has the same shape and lists every scope the operation needs. Retrying will not help: mint a key that holds them. - `COMPANY_READ_ONLY` — the scope is there, but your access level over that NIF only lets you read it. - `ACCOUNT_MANAGEMENT_FORBIDDEN` — the scope is there, but your role over the account, or the management relationship you hold over it, does not cover this operation. - `ACCOUNT_NOT_ACCESSIBLE` — the account is not yours to reach, which is also the answer when it does not exist, so existence is never disclosed. - `ACTIVE_COMPANY_NOT_ACCESSIBLE` — the same, for a NIF: the company in the path, or the one named by `BeeL-Active-Company`, is not one this credential may reach — and again, this is also the answer when it does not exist. - `COMPANY_ACCESS_REVOKED` — your access to the NIF was withdrawn while the request was already in flight, so the write was rejected and nothing was recorded. Retrying will not help until the access is granted again. - `LIVE_CREDENTIAL_REQUIRED` — the operation changes the real account and the call came from a test API key (`beel_sk_test_…`). Use your live key or the dashboard. - `FEATURE_NOT_AVAILABLE` — your subscription does not include the entitlement the operation needs; `error.details.feature_code` names it. This gate runs **before** the scope gate, so for such an operation you never see `INSUFFICIENT_SCOPE` first. - `NO_ACTIVE_ACCOUNT` — the credential does not resolve to an account, so no scope can be evaluated against one. Fail-closed, not a permission that can be granted to you. - `OPERATION_REQUIRES_SESSION` — the operation is available only from the web session; no API key and no OAuth2 token can perform it, whatever scopes it holds. - `OPERATION_REQUIRES_API_KEY` — the reverse: the operation needs a scope that only an API key can hold (such as `accounts:write`), so a dashboard session never satisfies it. - `API_KEY_LIVE_NOT_AVAILABLE` — the call came with a live API key (`beel_sk_live_…`) and the account has no Live mode yet. It is never degraded to Test: use your test key, or activate Live first. - `ACCOUNT_REQUIRES_FOCUS_SWITCH` — dashboard session only: you are a member of the account in the path, but it is not the account in focus. Switch focus to it and retry. - `REQUEST_BLOCKED` — the edge security filter stopped the request before the API saw its body, usually because a text field carries something that looks like markup or a script (HTML tags, `