Tax Configuration

Update tax configuration

Updates the user's tax configuration

PUT
/v1/configuration/taxes

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

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

Request Body

default_main_tax?
apply_equivalence_surcharge?boolean

Whether the freelancer is under the equivalence surcharge regime

Defaultfalse
default_equivalence_surcharge?number

Equivalence surcharge percentage in decimal format. The backend automatically normalizes equivalent formats (5.20 → 5.2).

Value in0 | 0.5 | 1.4 | 5.2
apply_irpf?boolean

Whether IRPF withholding should be applied

Defaulttrue
default_irpf_rate?integer

Personal income tax/withholding percentage in integer format. Allowed values: 0 (exempt), 2 (reduced for modules), 7, 15, 19, 21, 24 (non-residents).

Value in0 | 2 | 7 | 15 | 19 | 21 | 24
irpf_exempt?boolean

Whether the freelancer is exempt from IRPF withholding

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

Range0 <= value <= 365

Response Body

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"
    },
    "apply_equivalence_surcharge": false,
    "default_equivalence_surcharge": 5.2,
    "apply_irpf": true,
    "default_irpf_rate": 15,
    "irpf_exempt": false,
    "default_payment_method": "BANK_TRANSFER",
    "payment_term_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": "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"
  }
}

Get complete tax types catalog GET

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.

Get VeriFactu configuration GET

Retrieves the current VeriFactu configuration