Claves de régimen

La facturación española sobrecarga la palabra régimen. Tres conceptos distintos la comparten, viven en niveles diferentes del documento y solo uno de ellos es algo que envíes por la API pública:

Confundir los dos primeros es, con diferencia, la causa más habitual de una factura mal calificada. Esta página los separa.

Cuándo aplica

Siempre: toda factura emitida declara una calificación y, para casi todos los regímenes fiscales, una clave de régimen. Lo que varía es si dejas ambas a la derivación o las declaras explícitamente por línea.

Declara una clave de régimen explícita cuando la operación pertenezca a un régimen especial — bienes usados, agencias de viaje, criterio de caja, agricultura, recargo de equivalencia, ventas a distancia por ventanilla única. La derivación por cabecera solo produce el régimen general o la exportación, así que la granularidad del catálogo completo solo se alcanza por línea.

El catálogo cerrado

lines[].regime_key acepta exactamente estos diecisiete códigos de dos dígitos, de la lista ClaveRegimen L8.1 de la AEAT (BR-INV-031). Cualquier otro valor responde 422 con la lista completa en allowed_values.

Los números 12, 13 y 16 faltan a propósito — no forman parte de la lista, y enviarlos se rechaza igual que cualquier otro valor fuera del catálogo.

Qué envía la API

regime_key es un campo opcional, por línea y aditivo de POST /v1/invoices y PUT /v1/invoices/{id}. Una línea que lo omite cae a la clave derivada de la cabecera de la factura:

{
  "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 }
  ]
}

La primera línea declara el régimen de bienes usados; la segunda, sin clave, se deriva de la cabecera. Omitir el campo en todas las líneas reproduce exactamente el comportamiento que existía antes de introducir las claves por línea, huella incluida — que es la razón por la que el campo es aditivo y no obligatorio (BR-INV-031).

Tres de los cuatro ejemplos publicados de creación de factura —b2c, intracomunitario_bienes y con_irpf, en el desplegable de ejemplos del cuerpo de petición— declaran regime_key: "01" de forma explícita en lugar de apoyarse en el valor derivado. El cuarto, b2b_nacional, lo omite y deja que el régimen lo ponga la cabecera, lo cual es igual de válido. Copia la costumbre explícita: una clave por línea se documenta a sí misma y sobrevive a un cambio en la derivación por cabecera.

El régimen de cabecera es de solo lectura en la v1

El objeto factura devuelve operation_regime, y ni la operación de creación ni la de actualización lo aceptan. Toda factura creada por la API pública nace bajo el régimen general. La causa de exención a nivel de documento —exemption_reason en el objeto factura— es de solo lectura por el mismo motivo.

La consecuencia es concreta y conviene decirla sin rodeos: la calificación derivada de la cabecera será S1 en cualquier factura creada por la v1, así que la exención y la no sujeción deben declararse por línea, con lines[].exemption_reason. Es exactamente lo que hace el ejemplo intracomunitario_bienes —tax_rate: 0 más exemption_reason: "E5"— en lugar de apoyarse en un régimen de cabecera que no puede fijar.

Ver Clasificación fiscal y exenciones por línea para el catálogo de línea, y Alcance y limitaciones para qué permite y qué no esta frontera.

El catálogo legible por máquina

GET /v1/tax-catalog (scope taxes:read) publica los catálogos fiscales que describe esta página — regímenes indirectos con sus tipos válidos y sus códigos AEAT, regímenes de operación con sus menciones legales, causas de exención con su artículo de la LIVA, tipos de retención del sistema y los pares legales de IVA y recargo — con etiquetas en español, inglés y catalán en cada respuesta.

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

Dos propiedades hacen seguro cachearlo de forma agresiva (BR-TAX-028): es idéntico para todas las empresas —la consulta no lleva identificador de empresa y ninguna de sus fuentes está acotada a un tenant, así que dos API keys reciben cuerpos idénticos byte a byte y por tanto el mismo ETag— y se deriva de los objetos de valor cerrados del código y no de una lista copiada, de modo que un caso nuevo aparece automáticamente en vez de desincronizarse en silencio.

Qué sale en el PDF

La clave de régimen en sí no se imprime. Lo que ve quien lee el documento es la mención legal derivada del régimen de operación — la referencia al art. 25 LIVA en una entrega intracomunitaria, al art. 21 en una operación con terceros países, al art. 84.Uno.2 en la inversión del sujeto pasivo — y nada en absoluto para el régimen general, que no necesita mención (BR-TAX-024).

Como esas menciones derivan del régimen de cabecera, y el régimen de cabecera no se puede fijar en la v1, una factura creada por la API pública no imprime ninguna mención automática de régimen. Usa notes si el documento necesita declarar la exención en prosa.

Qué llega a la AEAT

Viajan dos campos distintos por cada grupo de desglose, y responden a preguntas distintas.

La calificación responde a «¿qué clase de operación es esta?», y se deriva del régimen de cabecera (BR-VFC-029):

Los códigos E1, E3, E4 y E6 existen en el catálogo de la AEAT pero esta derivación no los produce nunca: solo se alcanzan como causa de exención de línea. Una línea que declare una gana al valor derivado de la cabecera (BR-INV-032).

La clave de régimen responde a «¿bajo qué régimen especial?», y no se emite de forma incondicional (BR-VFC-035):

• Bajo IPSI no se emite nunca. Las reglas de validación de la AEAT son explícitas en que este impuesto no lleva ClaveRegimen.
• Bajo IVA e IGIC la clave se deriva, con un valor general conservador, y nunca se fija a fuego a 08. El código 08 corresponde a un emisor peninsular cuya operación se localiza en Canarias, Ceuta o Melilla — no a un emisor establecido allí, que declara su propio impuesto con su propia lista.
• Una causa de exención a nivel de documento que lleve su propia clave de régimen especial —bienes usados, agricultura, agencias de viaje, criterio de caja, recargo de equivalencia— tiene prioridad sobre ese valor por defecto.

Trazabilidad

Derivado de las reglas de dominio del backend de Factuarea:

• BR-INV-031 — el catálogo cerrado L8.1 de lines[].regime_key, su valor derivado de la cabecera y la invariante de huella idéntica.
• BR-INV-032 — las causas de exención de línea ganando a la calificación derivada de la cabecera.
• BR-VFC-029 — el mapa de calificaciones desde el régimen de operación de cabecera, y el hecho de que por esa vía solo se alcanzan E5 y E2.
• BR-VFC-035 — cómo se deriva ClaveRegimen: nunca fijada a fuego a 08, nunca emitida para IPSI, prioridad de la clave especial de la causa de exención.
• BR-TAX-024 — la causa de exención a nivel de documento y la mención legal automática.
• BR-TAX-028 — el catálogo fiscal público: sus cinco fuentes, su independencia del tenant y la publicación en positivo de los tipos de retención.