Fiscal invoice examples
The 21 Spanish tax scenarios for invoicing, which four of them ship as ready-to-send request examples in the API Reference, and a corrective example for each AEAT R-code (R1–R5).
Spanish invoicing covers many tax scenarios — domestic B2B, intra-EU
goods and services, OSS distance sales, IGIC in the Canary Islands, IPSI
in Ceuta/Melilla, IRPF withholding, equivalence surcharge, exempt and
non-subject operations. Getting the right combination of tax_rate,
exemption_reason, regime_key, retention_rate and surcharge_rate
on each line is the hard part.
To make this concrete, the API Reference ships four named,
ready-to-send request examples on
POST /v1/invoices
— a curated, representative set rather than one per scenario. Each one is
a valid payload you can copy, adapt and send: pick the closest one in the
request-body examples dropdown, then use the table below and the guide
linked on each row for the rest.
The 21 scenarios
Every row below is a scenario you can express line by line with the fields above. The four marked ★ are the ones that also ship as named request examples you can pick straight from the dropdown; the remaining seventeen are documented here and in the linked guide, but have no named example in the spec — build them from the closest starred one.
| Scenario key | Scenario | Guide |
|---|---|---|
★ b2b_nacional | Domestic B2B, 21% VAT per line (general AEAT regime 01). | Regime keys |
b2b_nacional_iva_reducido | Reduced (10%) or super-reduced (4%) VAT, regime 01. | Line tax classification |
★ b2c | Final consumer (no recipient tax ID; simplified invoice where applicable). | Simplified or full |
★ intracomunitario_bienes | Intra-EU supply of goods, exempt E5 (art. 25 LIVA). | International customers |
intracomunitario_servicios | Intra-EU B2B services, reverse charge — qualification S2 (subject, not exempt, charged quota 0) derived from the isp header regime, not an exemption cause. | International customers |
oss | OSS distance sales (destination-country VAT), regime_key: 17. | International customers · Regime keys |
igic_canarias | IGIC in the Canary Islands, regime_key: 08. | Territorial taxes |
ipsi_ceuta_melilla | IPSI in Ceuta / Melilla, regime_key: 08. | Territorial taxes |
★ con_irpf | Per-line IRPF withholding (retention_rate). | Line tax classification |
con_recargo_equivalencia | Equivalence surcharge using a legal VAT↔surcharge pair, regime_key: 18. | Line tax classification · Regime keys |
exenta_articulo_20 | Exempt under art. 20 LIVA, exemption_reason: E1. | Line tax classification |
exenta_exportacion | Export outside the EU, exempt E2 (art. 21), regime_key: 02. | International customers · Regime keys |
no_sujeta | Non-subject operation, exemption_reason: N1 / N2. | Line tax classification |
inversion_sujeto_pasivo_nacional | Domestic reverse charge (e.g. construction work), tax_rate: 0. | Line tax classification |
regimen_especial_bienes_usados | Used-goods margin scheme (REBU), regime_key: 03. | Regime keys |
regimen_agencias_viajes | Travel-agency scheme (REAV), regime_key: 05. | Regime keys |
criterio_caja | Cash-basis scheme, regime_key: 07. | Regime keys |
multilinea_iva_mixto | Several lines at different VAT rates (21% / 10% / 4%). | Line tax classification |
con_descuento_y_metadata | Per-line discount_percent plus integration metadata. | Fiscal cookbook |
con_idempotency_key | Safe retries with the Idempotency-Key header. | Fiscal cookbook |
cliente_extranjero_alternative_id | Foreign recipient with an alternative ID (AEAT type↔country matrix). | International customers |
Each of the four starred examples is also published as a reusable
components.examples.invoice_* entry in the OpenAPI spec, so SDKs and
tooling can resolve them by $ref.
The fiscal value objects (regime, exemption reason, IRPF, surcharge)
come from Factuarea's tax engine. The examples show valid combinations;
for the field-by-field contract see the
POST /v1/invoices
request schema and Amounts and dates.
Corrective invoices by R-code
A corrective (rectificativa) invoice carries the AEAT correction code
that states why the original is being corrected.
POST /v1/invoices/{id}/corrective
ships one named example per code, each a valid payload that produces that
exact correction_code:
| Example | Code | Applies to | Guide |
|---|---|---|---|
r1_error_fundado | R1 | Well-founded error in law / cancellation. Full invoices F1/F3. | Corrective invoices |
r2_concurso | R2 | Insolvency proceedings of the recipient. F1/F3. | Corrective invoices |
r3_incobrable | R3 | Bad debts. F1/F3. | Corrective invoices |
r4_otras | R4 | Other causes; full or partial (correction_type: partial with lines). F1/F3. | Corrective invoices |
r5_simplificada | R5 | Correction of a simplified invoice. F2 only. | Corrective invoices · Simplified or full |
Pass correction_code explicitly to select the R-code; R5 applies only
to simplified (F2) invoices.
A corrective is itself a fiscal document: once issued it is reported to AEAT via VeriFactu just like any other invoice. Use the example that matches the legal reason — the code is not cosmetic.