Ejemplos fiscales de factura
Los 21 escenarios fiscales españoles de facturación, cuáles cuatro de ellos se publican como ejemplos de request listos para enviar en la Referencia de la API y un ejemplo de rectificativa por cada código R de la AEAT (R1–R5).
La facturación española cubre muchos escenarios fiscales — B2B nacional,
bienes y servicios intracomunitarios, ventas a distancia OSS, IGIC en
Canarias, IPSI en Ceuta/Melilla, retención IRPF, recargo de equivalencia,
operaciones exentas y no sujetas. La parte difícil es acertar la
combinación correcta de tax_rate, exemption_reason, regime_key,
retention_rate y surcharge_rate en cada línea.
Para hacerlo concreto, la Referencia de la API incluye cuatro ejemplos
de request nombrados y listos para enviar en
POST /v1/invoices
— un conjunto curado y representativo, no uno por escenario. Cada uno es
un payload válido que puedes copiar, adaptar y enviar: elige el más
cercano a tu caso en el desplegable de ejemplos del request body y apóyate
en la tabla siguiente y en la guía enlazada en cada fila para el resto.
Los 21 escenarios
Cada fila de abajo es un escenario que puedes expresar línea a línea con los campos anteriores. Los cuatro marcados con ★ son además ejemplos de request nombrados que puedes elegir directamente en el desplegable; los otros diecisiete están documentados aquí y en la guía enlazada, pero no tienen ejemplo nombrado en el spec — constrúyelos a partir del marcado más cercano.
| Clave del escenario | Escenario | Guía |
|---|---|---|
★ b2b_nacional | B2B nacional, IVA 21% por línea (régimen general AEAT 01). | Claves de régimen |
b2b_nacional_iva_reducido | IVA reducido (10%) o superreducido (4%), régimen 01. | Clasificación por línea |
★ b2c | Consumidor final (sin NIF del destinatario; factura simplificada cuando aplique). | Simplificadas o completas |
★ intracomunitario_bienes | Entrega intracomunitaria de bienes, exenta E5 (art. 25 LIVA). | Clientes internacionales |
intracomunitario_servicios | Servicios B2B UE, inversión del sujeto pasivo — calificación S2 (sujeta y no exenta, cuota repercutida 0) derivada del régimen de cabecera isp, no una causa de exención. | Clientes internacionales |
oss | Ventas a distancia OSS (IVA del país de destino), regime_key: 17. | Clientes internacionales · Claves de régimen |
igic_canarias | IGIC en Canarias, regime_key: 08. | Impuestos territoriales |
ipsi_ceuta_melilla | IPSI en Ceuta / Melilla, regime_key: 08. | Impuestos territoriales |
★ con_irpf | Retención IRPF por línea (retention_rate). | Clasificación por línea |
con_recargo_equivalencia | Recargo de equivalencia con un par legal IVA↔recargo, regime_key: 18. | Clasificación por línea · Claves de régimen |
exenta_articulo_20 | Exenta por art. 20 LIVA, exemption_reason: E1. | Clasificación por línea |
exenta_exportacion | Exportación fuera de la UE, exenta E2 (art. 21), regime_key: 02. | Clientes internacionales · Claves de régimen |
no_sujeta | Operación no sujeta, exemption_reason: N1 / N2. | Clasificación por línea |
inversion_sujeto_pasivo_nacional | Inversión del sujeto pasivo nacional (p. ej. ejecución de obra), tax_rate: 0. | Clasificación por línea |
regimen_especial_bienes_usados | Régimen del margen de bienes usados (REBU), regime_key: 03. | Claves de régimen |
regimen_agencias_viajes | Régimen de agencias de viajes (REAV), regime_key: 05. | Claves de régimen |
criterio_caja | Régimen del criterio de caja, regime_key: 07. | Claves de régimen |
multilinea_iva_mixto | Varias líneas a tipos de IVA distintos (21% / 10% / 4%). | Clasificación por línea |
con_descuento_y_metadata | discount_percent por línea más metadata de integración. | Recetario fiscal |
con_idempotency_key | Reintentos seguros con el header Idempotency-Key. | Recetario fiscal |
cliente_extranjero_alternative_id | Destinatario extranjero con identificador alternativo (matriz tipo↔país AEAT). | Clientes internacionales |
Cada uno de los cuatro ejemplos marcados también se publica como una entrada
reutilizable components.examples.invoice_* en el spec OpenAPI, para que los
SDK y el tooling puedan resolverlos por $ref.
Los value objects fiscales (régimen, motivo de exención, IRPF, recargo)
vienen del motor fiscal de Factuarea. Los ejemplos muestran
combinaciones válidas; para el contrato campo a campo consulta el schema
del request de
POST /v1/invoices
e Importes y fechas.
Facturas rectificativas por código R
Una factura rectificativa lleva el código de rectificación de la AEAT que
indica por qué se corrige la original.
POST /v1/invoices/{id}/corrective
incluye un ejemplo nombrado por cada código, cada uno un payload válido
que produce ese correction_code exacto:
| Ejemplo | Código | Aplica a | Guía |
|---|---|---|---|
r1_error_fundado | R1 | Error fundado de derecho / anulación. Facturas completas F1/F3. | Facturas rectificativas |
r2_concurso | R2 | Concurso de acreedores del destinatario. F1/F3. | Facturas rectificativas |
r3_incobrable | R3 | Créditos incobrables. F1/F3. | Facturas rectificativas |
r4_otras | R4 | Resto de causas; total o parcial (correction_type: partial con lines). F1/F3. | Facturas rectificativas |
r5_simplificada | R5 | Rectificación de una factura simplificada. Solo F2. | Facturas rectificativas · Simplificadas o completas |
Pasa correction_code explícitamente para seleccionar el código R; R5
solo aplica a facturas simplificadas (F2).
Una rectificativa es a su vez un documento fiscal: una vez emitida se reporta a la AEAT vía VeriFactu igual que cualquier otra factura. Usa el ejemplo que coincida con la causa legal — el código no es cosmético.