---
title: "Update the tax configuration of a company"
method: PUT
path: "/v1/companies/{company_id}/tax-configuration"
tags: ["CompanyTaxConfiguration"]
---

# Update the tax configuration of a company

`PUT /v1/companies/{company_id}/tax-configuration`

## Request

- Base URL: `https://app.beel.es/api`
- URL: `https://app.beel.es/api/v1/companies/{company_id}/tax-configuration`
- Auth: HTTP bearer

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.

## Request body

- UpdateTaxConfigurationRequest
  - `default_main_tax` TaxInfo: Complete tax information with cross-validations: - IVA: real rates 4, 10, 21, and the temporary 2, 5 and 7.5 (see below for 0) - IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real "Tipo Cero" - IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0) - OTHER: any percentage between 0 and 100 **0 % under IVA and IPSI is not a rate, it is the exemption sentinel.** It is accepted on a line, but only together with an `exemption_reason` (exempt or non-subject operation); on its own it says nothing and the line is rejected. That is why `GET /v1/tax-types` publishes the IVA rates without 0: the legitimate way to a 0 % IVA line is through an exemption reason, which the same response also publishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and needs no reason. **IVA 5 %** (the temporary rate applied from 2022 to electricity, gas and certain foodstuffs) is no longer in force for new operations. AEAT only accepts it on operations dated from 2022-07-01 to 2024-09-30: send the `operation_date` of that period, because without one the issue date decides and a line at 5 % is rejected with `422 VAT_RATE_NOT_ACCEPTED_ON_DATE`. Its equivalence surcharge pair is 0.5 up to 2022-12-31 and 0.62 from 2023-01-01. **IVA 2 % and 7.5 %** (temporary rates of the last quarter of 2024) are accepted only on operations dated from 2024-10-01 to 2024-12-31, with surcharges 0.26 and 1. Exception: when regime_key = "17" (OSS/IOSS) the invoice applies the destination country VAT instead of the Spanish one, so any percentage in the EU range [0, 27] is accepted regardless of the tax type set — including 0 without an exemption reason.
    - `type` 'IVA' | 'IGIC' | 'IPSI' | 'OTHER', required: Tax type by territory: - IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period) - IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%) - IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%) - OTHER: Configurable 0%-100% Under IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject sentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate. See `TaxInfo` for the full rules.
    - `percentage` number, required: Tax percentage
    - `regime_key` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '14' | '15' | '17' | '18' | '19' | '20': Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies: - 01: General regime operation - 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`) - 03: Used goods, art, antiques (not accepted, see below) - 04: Investment gold - 05: Travel agencies - 06: Group of entities (not accepted, see below) - 07: Cash basis - 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA on an IGIC line. It is **not** the general regime of IGIC, which is `01`. - 09: Mediating agencies - 10: Third-party collections - 11: Local rental - 14: VAT pending in certifications (not accepted, see below) - 15: VAT pending successive tract - 17: OSS and IOSS - 18: Equivalence surcharge - 19: REAGYP - 20: Simplified regime **What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on IVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with `422` and the code in brackets: - `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 % (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`, `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`). - `11` (IVA): a subject line only at 21 %, and no reverse charge (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them data the invoice does not carry (a cost-based taxable base; an operation date after the issue date and a public-administration recipient). - `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The corrective of an invoice that already carried `03` keeps it. - `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge, no non-subject reason and, of the exemptions, only art. 20 or `OTRO` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). `GET /v1/tax-types` only offers the keys that are accepted. **One exception to "a key you send is the key you get":** when the line ends up carrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate` or it was inherited from the company's tax configuration — a `01` is rewritten to `18`, because a surcharge under the general regime is fiscally incoherent. Send `equivalence_surcharge_rate: 0` explicitly to keep `01`. See `equivalence_surcharge_rate` in the invoice line for the full rules.
  - `default_exemption_reason` '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_B' | 'ISP_ART_84_2_C' | 'ISP_ART_84_2_D' | 'ISP_ART_84_2_E' | 'ISP_ART_84_2_F' | 'ISP_ART_84_2_G' | 'REGIMEN_ART_129' | 'REGIMEN_ART_135' | 'REGIMEN_ART_141' | 'REGIMEN_ART_154' | 'REGIMEN_ART_163_DECIES' | 'OTRO': 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, nullable: 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` 0 | 0.26 | 0.5 | 0.62 | 1 | 1.4 | 1.75 | 5.2: 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` 0 | 1 | 2 | 2.8 | 6 | 7 | 7.6 | 9.5 | 15 | 19 | 24: 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` 'NONE' | 'BANK_TRANSFER' | 'CARD' | 'CASH' | 'CHECK' | 'DIRECT_DEBIT' | 'BIZUM' | 'OTHER': Payment method shown on invoices and recurring invoices. - `NONE`: no payment information is shown. - `BANK_TRANSFER`: bank transfer to the IBAN of the payment details; the only method that requires an IBAN. - `CARD`: card payment. - `CASH`: cash payment. - `CHECK`: payment by cheque. - `DIRECT_DEBIT`: direct debit from the customer's bank account. - `BIZUM`: payment through Bizum. - `OTHER`: any other method.
  - `payment_term_days` integer, nullable: Default payment term in days (0-365). Omit it to leave the current value untouched; send `null` to clear it.
  - `proforma_validity_days` integer, nullable: 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).

## Response `200`

Configuration updated successfully

- object: The envelope every successful JSON response of the BeeL. API is wrapped in. There are no bare resources in v1 and none are planned: the payload always hangs off `data`. - A **single resource** is an object in `data`. - A **collection** hangs off a named key inside `data`, together with its `pagination`, also inside `data` — `data: {invoices: [...], pagination: {...}}`. - A collection carries `pagination` unless its operation declares itself a **closed catalogue**: a fixed, bounded list with nothing to page through. The declaration is explicit in the operation; a missing `pagination` is never something to infer. - `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a documented variant of pagination, not another envelope. Putting the array straight into `data` with `pagination` as its sibling is the shape a v2 would adopt; v1 is not being flipped to it.
  - `success` boolean, required
  - `data` object, 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.
    - `default_main_tax` object, required: Convenience **prefill**, not a default the API applies. Includes tax regime type (IVA/IGIC/IPSI/OTHER), percentage and regime key. It seeds the tax fields of a line where a human (or BeeL itself) is composing one: the dashboard invoice editor, onboarding, and the drafts BeeL generates from payment events. The value is written into the line at that moment and is visible and editable from then on. **Never applied to invoice lines created via the API**: omitting `main_tax` on a `NORMAL` line is a validation error (`422 LINE_MAIN_TAX_REQUIRED`), never a silent fallback to this value. Which tax a line bears is a fiscal decision of the issuer, so the API refuses to guess it — the same line body must produce the same invoice regardless of how the account happens to be configured today. (`SUPLIDO` lines carry no main tax at all, so nothing is prefilled there either.) Common examples: - Standard VAT: { type: "IVA", percentage: 21, regime_key: "01" } - Special Reduced IGIC: { type: "IGIC", percentage: 7, regime_key: "01" } - Standard IPSI: { type: "IPSI", percentage: 10, regime_key: "01" }
      - `type` 'IVA' | 'IGIC' | 'IPSI' | 'OTHER', required: Tax type by territory: - IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period) - IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%) - IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%) - OTHER: Configurable 0%-100% Under IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject sentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate. See `TaxInfo` for the full rules.
      - `percentage` number, required: Tax percentage
      - `regime_key` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '14' | '15' | '17' | '18' | '19' | '20': Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies: - 01: General regime operation - 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`) - 03: Used goods, art, antiques (not accepted, see below) - 04: Investment gold - 05: Travel agencies - 06: Group of entities (not accepted, see below) - 07: Cash basis - 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA on an IGIC line. It is **not** the general regime of IGIC, which is `01`. - 09: Mediating agencies - 10: Third-party collections - 11: Local rental - 14: VAT pending in certifications (not accepted, see below) - 15: VAT pending successive tract - 17: OSS and IOSS - 18: Equivalence surcharge - 19: REAGYP - 20: Simplified regime **What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on IVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with `422` and the code in brackets: - `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 % (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`, `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`). - `11` (IVA): a subject line only at 21 %, and no reverse charge (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them data the invoice does not carry (a cost-based taxable base; an operation date after the issue date and a public-administration recipient). - `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The corrective of an invoice that already carried `03` keeps it. - `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge, no non-subject reason and, of the exemptions, only art. 20 or `OTRO` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). `GET /v1/tax-types` only offers the keys that are accepted. **One exception to "a key you send is the key you get":** when the line ends up carrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate` or it was inherited from the company's tax configuration — a `01` is rewritten to `18`, because a surcharge under the general regime is fiscally incoherent. Send `equivalence_surcharge_rate: 0` explicitly to keep `01`. See `equivalence_surcharge_rate` in the invoice line for the full rules.
    - `default_exemption_reason` '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_B' | 'ISP_ART_84_2_C' | 'ISP_ART_84_2_D' | 'ISP_ART_84_2_E' | 'ISP_ART_84_2_F' | 'ISP_ART_84_2_G' | 'REGIMEN_ART_129' | 'REGIMEN_ART_135' | 'REGIMEN_ART_141' | 'REGIMEN_ART_154' | 'REGIMEN_ART_163_DECIES' | 'OTRO': 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, nullable: Custom exemption text. Only used when `default_exemption_reason` is `OTRO`, where it is mandatory — same rule as in the invoice line.
    - `apply_equivalence_surcharge` boolean, required: Whether the freelancer is under the equivalence surcharge regime. **Business rule**: If `true`, the `default_equivalence_surcharge` field is REQUIRED.
    - `default_equivalence_surcharge` number: Default equivalence surcharge, as the configuration holds it. It is what is stored, not what a request accepts (see `EquivalenceSurchargePercentage`): a configuration saved with the `0.625` surcharge of VAT at 5 %, before it was corrected to 0.62, is returned as `0.625` until it is updated. **Business rule**: REQUIRED if `apply_equivalence_surcharge` is `true`.
    - `apply_irpf` boolean, required: Whether IRPF withholding should be applied to invoices. Defaults to `false`: no withholding is applied until the user declares one (a rate nobody declared is never invented). **Business rule**: If `true` and `irpf_exempt` is `false`, the `default_irpf_rate` field is REQUIRED.
    - `default_irpf_rate` number: Default IRPF for new invoices, as the configuration holds it. It is what is stored, not what a request accepts (see `IrpfPercentage`): a configuration saved with a rate the table no longer has is returned as it is until it is updated. **Business rule**: REQUIRED if `apply_irpf` is `true` and `irpf_exempt` is `false`.
    - `irpf_exempt` boolean: Whether the freelancer is exempt from IRPF withholding (e.g., business start). **Note**: When `true`, any provided `default_irpf_rate` is saved but not applied to invoices. This allows pre-configuring the rate for when the exemption ends.
    - `default_payment_method` 'NONE' | 'BANK_TRANSFER' | 'CARD' | 'CASH' | 'CHECK' | 'DIRECT_DEBIT' | 'BIZUM' | 'OTHER': Payment method shown on invoices and recurring invoices. - `NONE`: no payment information is shown. - `BANK_TRANSFER`: bank transfer to the IBAN of the payment details; the only method that requires an IBAN. - `CARD`: card payment. - `CASH`: cash payment. - `CHECK`: payment by cheque. - `DIRECT_DEBIT`: direct debit from the customer's bank account. - `BIZUM`: payment through Bizum. - `OTHER`: any other method.
    - `payment_term_days` integer, nullable: Default payment term in days (0-365). Null means no default term.
    - `proforma_validity_days` integer, nullable: Default validity term in days for new proformas (0-365). Null means no default: proformas are created without an expiry date. UI-only default: the dashboard uses it to prefill `valid_until` when creating a proforma (issue date + N days, editable). It is never applied server-side, so the public API contract of `valid_until` does not change.
    - `withholding_options` WithholdingOptions: Withholding rates a company can bear, deduced from the first letter of its NIF. Only individuals pay IRPF (Law 35/2006, art. 8), so no entity bears the rates of individuals (1, 2, 7, 15, and 6, 2.8 and 7.6 in Ceuta and Melilla); any rate an entity cannot bear, on its invoices, products, default configuration or recurring templates, is rejected with `IRPF_RATE_NOT_FOR_CORPORATE_ISSUER`. - **Legal person that pays Corporate Income Tax** (NIF starting with `A`, `B`, `C`, `D`, `F`, `G`, `Q`, `R` or `U`) and **permanent establishment of a non-resident entity** (`W`, which bears the Corporate Income Tax withholding regime, Royal Legislative Decree 5/2004, art. 23.1): only `0`, `19` and `24`. Its income bears withholding only when it is one of those listed in the Corporate Income Tax regulation (Royal Decree 634/2015, art. 60: rents of urban property, image rights, director fees, capital income…), at 19 % or, for image rights, 24 % (art. 66); 19 % is halved to 9.5 for rents of urban property in Ceuta and Melilla. An exempt entity bears none on its exempt income. The suggestion is `0`: a provision of services is not in that list. - **Non-resident entity** (`N`): `0`, `19` and `24`, the Non-Residents Income Tax withholding (Royal Legislative Decree 5/2004, arts. 25.1 a) and 31): 24 %, 19 % if it resides in the European Union or the European Economic Area, 0 if the income is exempt or a tax treaty says so. It depends on facts the NIF does not show: no suggestion. - **State, Autonomous Community or local entity** (`S`, `P`): fully exempt, its income bears no withholding (Law 27/2014, art. 9.1; Royal Decree 634/2015, art. 61): only `0`. - **Individual, or entity whose income is attributed to its members** (`E`): every rate of the IRPF regulation, including the Ceuta and Melilla reduced rates (6, 2.8, 7.6), but not the Corporate Income Tax 9.5. Which one applies depends on the activity and its years, which the NIF does not show, so there is no suggestion. - **Any other NIF** (`H`, `J`, `V`): not restricted, no suggestion.
      - `allowed_irpf_rates` IrpfPercentage[], required: The rates this company can use, in ascending order.
      - `suggested_irpf_rate` number, nullable, required: One of `allowed_irpf_rates`. The rate to preselect for this company, or `null` when it depends on facts the NIF does not show and the user has to choose.
  - `meta` ResponseMeta
    - `timestamp` string, date-time
    - `request_id` string

## Other responses

- `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.
- `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.
- `403`: Your account does not own or manage this company, or does not hold the required access over it. A NIF that does not exist answers the same way. That case answers `error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`.
- `409`: `TAX_CONFIG_CONFLICT` — another request created this company's tax configuration at the same time. Retry: it now finds the configuration and updates it.
- `422`: `VALIDATION_ERROR` — the body parses but a value is not acceptable. `details` is a flat map from the offending property's name (in the contract's `snake_case`, nested paths joined with a dot, e.g. `recipient.address.postal_code`) to a message describing what is wrong with it, one entry per property. When the rejected value is one outside an enum's vocabulary, `details` instead follows `FieldDeserializationError` (`field`, `invalid_value`, `allowed_values`). Two more codes share this status for a value that passes the contract but does not fit where it is stored: `VALUE_TOO_LONG` (a text longer than its column holds) and `VALUE_OUT_OF_RANGE` (a number outside what its column holds). Nothing was written. Other `error.code` values with this status: - `INVALID_PERCENTAGE` — the `percentage` is not a rate of that tax type (e.g. IVA 13); the message lists the valid rates. OSS key `17` accepts any EU rate. - `INVALID_REGIME_KEY_FOR_TAX_TYPE` — the `regime_key` does not exist for that tax type (e.g. `18` under IGIC); `details.allowed_values` lists the accepted keys. - `IRPF_RATE_NOT_FOR_CORPORATE_ISSUER` — the issuer is a company (corporate income tax), which can only withhold 0, 19 or 24 %; use one of those. - `IRPF_RATE_ONLY_FOR_CORPORATE_ISSUER` — the rate (e.g. 9.5 % Ceuta/Melilla) only applies to corporate issuers; an individual issuer must use a personal-income-tax rate. - `REGIME_KEY_NOT_SUPPORTED` — BeeL. cannot declare that `regime_key` to AEAT (e.g. `06`, `14`); use another key.
- `429`: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because too many went out to that recipient in a short time. Either way, retry after the `Retry-After` seconds. `QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan for the current period (issued invoices, for instance). Retrying does not help until the quota resets or the plan changes. `error.details` carries `feature_code`, `current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until the reset when it is known.
- `500`: Internal server error
- `default`: Any status code the operation does not list above. Every operation declares it, so a generated client always has a branch to fall into and never loses the cause of a failure it did not anticipate. This is where the transport-level answers land — `405`, `406`, `415` and `429` — together with any status a future version of the API starts returning. All of them carry the same error envelope as the codes listed explicitly, so `error.code` is what tells them apart: switching on the status code alone is not enough. See «Transport-level errors» in the API description for when each one is produced. A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active subscription. `error.details` says why and what to do: `current_status` (absent if it never had one), `required_permission` and `action`. A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a dependency of BeeL itself (the database, the email provider) was momentarily unavailable and nothing was done. Retry after those seconds. A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the operation depends on failed or did not answer in time. It is a transient condition — retry with the same `Idempotency-Key` where the operation accepts one. One exception to the envelope: a failure of the network edge that never reaches the application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not BeeL's — it may not even be JSON. Treat those as "no answer", and retry.

---

[API](https://skmtc.dev/beel/apis/beel-public-api.md) · [All operations](https://skmtc.dev/beel/apis/beel-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beel/apis/beel-public-api/revisions/ffbc0ae31f79?raw)