Regime keys

Spanish invoicing overloads the word regime. Three distinct concepts share it, they live at different levels of the document, and only one of them is something you send on the public API:

Confusing the first two is the single most common cause of a wrongly qualified invoice. This page separates them.

When this applies

Always: every issued invoice declares a qualification and, for most tax regimes, a regime key. What varies is whether you leave both to derivation or state them explicitly per line.

Declare a regime key explicitly when the operation belongs to a special regime — used goods, travel agencies, cash-basis accounting, agriculture, equivalence surcharge, distance sales under the one-stop shop. Header derivation only ever produces the general regime or export, so the granularity of the full catalogue is reachable only per line.

The closed catalogue

lines[].regime_key accepts exactly these seventeen two-digit codes, from the AEAT ClaveRegimen list L8.1 (BR-INV-031). Anything else answers 422 with the full list in allowed_values.

The numbers 12, 13 and 16 are deliberately absent — they are not part of the list, and sending them is rejected like any other value outside the catalogue.

What the API sends

regime_key is an optional, per-line, additive field on POST /v1/invoices and PUT /v1/invoices/{id}. A line that omits it falls back to the key derived from the invoice header:

{
  "lines": [
    { "description": "Reventa de maquinaria de ocasión", "quantity": 1, "unit_price": 100, "regime_key": "03" },
    { "description": "Servicio de instalación", "quantity": 1, "unit_price": 50, "tax_rate": 21 }
  ]
}

The first line declares the used-goods regime; the second one, with no key, is derived from the header. Omitting the field on every line reproduces exactly the behaviour that existed before per-line keys were introduced, fingerprint included — which is the reason the field is additive rather than mandatory (BR-INV-031).

Three of the four published create-invoice examples — b2c, intracomunitario_bienes and con_irpf in the request-body examples dropdown — declare regime_key: "01" explicitly rather than relying on the fallback. The fourth, b2b_nacional, omits it and lets the header supply the regime, which is equally valid. Copy the explicit habit: a per-line key is self-documenting and survives a change in header derivation.

The header regime is read-only in v1

The invoice object returns operation_regime, and neither the create nor the update operation accepts it. Every invoice created through the public API is born under the general regime. The document-level exemption cause — exemption_reason on the invoice object — is read-only for the same reason.

The consequence is concrete and worth stating plainly: the qualification derived from the header will be S1 for any v1-created invoice, so exemption and non-subjection must be declared per line, with lines[].exemption_reason. That is exactly what the intracomunitario_bienes example does — tax_rate: 0 plus exemption_reason: "E5" — rather than relying on a header regime it cannot set.

See Line tax classification and exemptions for the line catalogue, and Scope and limitations for what this boundary does and does not allow.

The machine-readable catalogue

GET /v1/tax-catalog (scope taxes:read) publishes the fiscal catalogues this page describes — indirect tax regimes with their valid rates and AEAT codes, operation regimes with their legal mentions, exemption causes with their LIVA article, system withholding rates and the legal VAT-to-surcharge pairs — with labels in Spanish, English and Catalan in every response.

curl https://api.factuarea.com/v1/tax-catalog \
  -H "Authorization: Bearer fact_live_3pXnR2VbY7TcA9eFmN5z8KqW"

Two properties make it safe to cache aggressively (BR-TAX-028): it is identical for every company — the query carries no company identifier and none of its sources is scoped to a tenant, so two API keys receive byte-identical bodies and therefore the same ETag — and it is derived from the closed value objects in the code rather than from a copied list, so a new case appears automatically instead of silently desynchronising.

What appears on the PDF

The regime key itself is not printed. What the reader sees is the legal mention derived from the operation regime — the reference to art. 25 LIVA for an intra-community supply, art. 21 for a third-country operation, art. 84.Uno.2 for reverse charge — and nothing at all for the general regime, which needs no mention (BR-TAX-024).

Because those mentions derive from the header regime, and the header regime is not settable in v1, an invoice created through the public API prints no automatic regime mention. Use notes if the document needs to state the exemption in prose.

What reaches the AEAT

Two different fields travel per breakdown group, and they answer different questions.

The qualification answers "what kind of operation is this?", and is derived from the header regime (BR-VFC-029):

Codes E1, E3, E4 and E6 exist in the AEAT catalogue but are never produced by this derivation: they are only reachable as a line exemption reason. A line that declares one wins over the header fallback (BR-INV-032).

The regime key answers "under which special regime?", and is not emitted unconditionally (BR-VFC-035):

• Under IPSI, the key is never emitted at all. The AEAT validation rules are explicit that this tax carries no ClaveRegimen.
• Under VAT and IGIC, the key is derived, with a conservative general default, and never hardcoded to 08. Code 08 belongs to a mainland issuer whose operation is located in the Canary Islands, Ceuta or Melilla — not to an issuer established there, who declares their own tax with their own list.
• A document-level exemption cause that carries its own special-regime key — used goods, agriculture, travel agencies, cash-basis, equivalence surcharge — takes priority over that default.

Traceability

Derived from the domain rules of the Factuarea backend:

• BR-INV-031 — the closed L8.1 catalogue for lines[].regime_key, its fallback to header derivation, and the identical-fingerprint invariant.
• BR-INV-032 — line-level exemption causes overriding the header-derived qualification.
• BR-VFC-029 — the qualification map from the header operation regime, and the fact that only E5 and E2 are reachable that way.
• BR-VFC-035 — how ClaveRegimen is derived: never hardcoded 08, never emitted for IPSI, priority of the exemption cause's special key.
• BR-TAX-024 — the document-level exemption cause and the automatic legal mention.
• BR-TAX-028 — the public fiscal catalogue: its five sources, tenant independence, and the positive publication of withholding rates.