NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Tax Configuration

Update tax configuration

Scopeconfiguration:write

Deprecated. Use PUT /v1/companies/{company_id}/tax-configuration, which behaves identically.

Updates the tax configuration of the company (NIF) 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.
PUT
/v1/configuration/taxes

Authorization

AuthorizationBearer <token>

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

Request Body

default_main_tax?
default_exemption_reason?string

Tax 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.

Value in"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"
default_exemption_reason_text?string|null

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.

Lengthlength <= 500
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?number

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).

Value in0 | 0.5 | 0.625 | 1.4 | 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?integer

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).

Value in0 | 1 | 2 | 7 | 15 | 19 | 24
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|null

Default payment method for new invoices. If NONE is selected, no payment information will be shown on the invoice.

payment_term_days?integer|null

Default payment term in days (0-365). Omit it to leave the current value untouched; send null to clear it.

Range0 <= value <= 365
proforma_validity_days?integer|null

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).

Range0 <= value <= 365

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://app.beel.es/api/v1/configuration/taxes" \  -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 is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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": "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 user tax configuration GET

**Deprecated.** Use `GET /v1/companies/{company_id}/tax-configuration`, which behaves identically. Retrieves the tax configuration of the company (NIF) in focus: the default main tax (`IVA`, `IGIC`, `IPSI` or `OTHER`) with its percentage and regime key, the default exemption reason, the IRPF and equivalence surcharge settings, and the default payment method and payment term.

Get the VeriFactu configuration of a company GET

Retrieves the VeriFactu configuration of this company (NIF). The configuration belongs to the NIF, so the NIF in the path is what decides which one is returned.