Exemples fiscals de factura
Els 21 escenaris fiscals espanyols de facturació, quins quatre d'ells es publiquen com a exemples de request llestos per enviar a la Referència de l'API i un exemple de rectificativa per cada codi R de l'AEAT (R1–R5).
La facturació espanyola cobreix molts escenaris fiscals — B2B nacional,
béns i serveis intracomunitaris, vendes a distància OSS, IGIC a Canàries,
IPSI a Ceuta/Melilla, retenció IRPF, recàrrec d'equivalència, operacions
exemptes i no subjectes. La part difícil és encertar la combinació
correcta de tax_rate, exemption_reason, regime_key,
retention_rate i surcharge_rate a cada línia.
Per fer-ho concret, la Referència de l'API inclou quatre exemples de
request amb nom i llestos per enviar a
POST /v1/invoices
— un conjunt curat i representatiu, no un per escenari. Cadascun és un
payload vàlid que pots copiar, adaptar i enviar: tria el més proper al teu
cas al desplegable d'exemples del request body i recolza't en la taula
següent i en la guia enllaçada a cada fila per a la resta.
Els 21 escenaris
Cada fila de sota és un escenari que pots expressar línia a línia amb els camps anteriors. Els quatre marcats amb ★ són a més exemples de request amb nom que pots triar directament al desplegable; els altres disset estan documentats aquí i a la guia enllaçada, però no tenen exemple amb nom al spec — construeix-los a partir del marcat més proper.
| Clau de l'escenari | Escenari | Guia |
|---|---|---|
★ b2b_nacional | B2B nacional, IVA 21% per línia (règim general AEAT 01). | Claus de règim |
b2b_nacional_iva_reducido | IVA reduït (10%) o superreduït (4%), règim 01. | Classificació per línia |
★ b2c | Consumidor final (sense NIF del destinatari; factura simplificada quan escaigui). | Simplificades o completes |
★ intracomunitario_bienes | Lliurament intracomunitari de béns, exempta E5 (art. 25 LIVA). | Clients internacionals |
intracomunitario_servicios | Serveis B2B UE, inversió del subjecte passiu — qualificació S2 (subjecta i no exempta, quota repercutida 0) derivada del règim de capçalera isp, no una causa d'exempció. | Clients internacionals |
oss | Vendes a distància OSS (IVA del país de destí), regime_key: 17. | Clients internacionals · Claus de règim |
igic_canarias | IGIC a Canàries, regime_key: 08. | Impostos territorials |
ipsi_ceuta_melilla | IPSI a Ceuta / Melilla, regime_key: 08. | Impostos territorials |
★ con_irpf | Retenció IRPF per línia (retention_rate). | Classificació per línia |
con_recargo_equivalencia | Recàrrec d'equivalència amb un parell legal IVA↔recàrrec, regime_key: 18. | Classificació per línia · Claus de règim |
exenta_articulo_20 | Exempta per art. 20 LIVA, exemption_reason: E1. | Classificació per línia |
exenta_exportacion | Exportació fora de la UE, exempta E2 (art. 21), regime_key: 02. | Clients internacionals · Claus de règim |
no_sujeta | Operació no subjecta, exemption_reason: N1 / N2. | Classificació per línia |
inversion_sujeto_pasivo_nacional | Inversió del subjecte passiu nacional (p. ex. execució d'obra), tax_rate: 0. | Classificació per línia |
regimen_especial_bienes_usados | Règim del marge de béns usats (REBU), regime_key: 03. | Claus de règim |
regimen_agencias_viajes | Règim d'agències de viatges (REAV), regime_key: 05. | Claus de règim |
criterio_caja | Règim del criteri de caixa, regime_key: 07. | Claus de règim |
multilinea_iva_mixto | Diverses línies a tipus d'IVA diferents (21% / 10% / 4%). | Classificació per línia |
con_descuento_y_metadata | discount_percent per línia més metadata d'integració. | Receptari fiscal |
con_idempotency_key | Reintents segurs amb el header Idempotency-Key. | Receptari fiscal |
cliente_extranjero_alternative_id | Destinatari estranger amb identificador alternatiu (matriu tipus↔país AEAT). | Clients internacionals |
Cadascun dels quatre exemples marcats també es publica com una entrada
reutilitzable components.examples.invoice_* al spec OpenAPI, perquè els SDK i
el tooling els puguin resoldre per $ref.
Els value objects fiscals (règim, motiu d'exempció, IRPF, recàrrec)
vénen del motor fiscal de Factuarea. Els exemples mostren combinacions
vàlides; per al contracte camp a camp consulta el schema del request de
POST /v1/invoices
i Imports i dates.
Factures rectificatives per codi R
Una factura rectificativa porta el codi de rectificació de l'AEAT que
indica per què es corregeix l'original.
POST /v1/invoices/{id}/corrective
inclou un exemple amb nom per cada codi, cadascun un payload vàlid que
produeix aquest correction_code exacte:
| Exemple | Codi | Aplica a | Guia |
|---|---|---|---|
r1_error_fundado | R1 | Error fonamentat de dret / anul·lació. Factures completes F1/F3. | Factures rectificatives |
r2_concurso | R2 | Concurs de creditors del destinatari. F1/F3. | Factures rectificatives |
r3_incobrable | R3 | Crèdits incobrables. F1/F3. | Factures rectificatives |
r4_otras | R4 | Resta de causes; total o parcial (correction_type: partial amb lines). F1/F3. | Factures rectificatives |
r5_simplificada | R5 | Rectificació d'una factura simplificada. Només F2. | Factures rectificatives · Simplificades o completes |
Passa correction_code explícitament per seleccionar el codi R; R5
només aplica a factures simplificades (F2).
Una rectificativa és al seu torn un document fiscal: un cop emesa es reporta a l'AEAT via VeriFactu igual que qualsevol altra factura. Usa l'exemple que coincideixi amb la causa legal — el codi no és cosmètic.