Tipos de factura

El campo type de una factura sigue la nomenclatura Veri*Factu de la AEAT. No todos se crean igual: unos nacen con POST /invoices, otros solo se producen a través de una acción sobre una factura ya emitida.

El catálogo

type	Nombre	Cómo se produce
F1	Factura ordinaria (completa). Receptor identificado.	POST /invoices
F2	Factura simplificada (sin identificar al receptor; «ticket»).	POST /invoices
F3	Sustitutiva: sustituye a una o varias F2 ya declaradas.	POST /invoices/{id}/actions/replace
R1	Rectificativa por error fundado en derecho / art. 80 Uno, Dos y Seis LIVA.	POST /invoices/{id}/actions/rectify
R2	Rectificativa por art. 80.3 (concurso de acreedores).	…/actions/rectify
R3	Rectificativa por art. 80.4 (créditos incobrables).	…/actions/rectify
R4	Rectificativa, resto de causas.	…/actions/rectify
R5	Rectificativa sobre factura simplificada.	…/actions/rectify

F1 y F2 son los únicos que creas directamente

El resto son derivados de una factura emitida. Las rectificativas (R1–R5) y las sustitutivas (F3) tienen su propia acción porque heredan datos y relaciones de la factura de origen. Ver Corregir o anular.

F1 — Factura ordinaria

El caso normal: hay un receptor identificado (partner_id). Necesita partner; omitirlo devuelve 400 (invoices.partner_required).

curl -X POST https://api.test.bilteo.com/api/v1/invoices \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "type": "F1", "partner_id": "…",
        "lines": [{ "description": "Consultoría", "quantity": "1", "unit_price": "1000.00" }] }'

F2 — Factura simplificada

El «ticket»: sin identificar al receptor. partner_id es opcional. Pensada para ventas por debajo del umbral legal de simplificada. Si después necesitas emitir una completa por esas ventas, usa una sustitutiva (F3).

curl -X POST https://api.test.bilteo.com/api/v1/invoices \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "type": "F2",
        "lines": [{ "description": "Venta mostrador", "quantity": "1", "unit_price": "30.00" }] }'

F3 — Sustitutiva

No se crea con POST /invoices. Se genera desde una F2 emitida con la acción replace, que crea la F3 (borrador), la enlaza como sustituta de la F2 y recalcula sus líneas agrupando bases por combinación de impuestos. Ver Sustitutivas (F2 → F3).

R1–R5 — Rectificativas

No se crean con POST /invoices. Nacen de rectify sobre la factura de origen; su R-type se deriva de la causa (rectification_cause) y del tipo de origen. La mecánica y el mapeo causa → R-type están en Rectificativas.

Series y numeración

Cada factura toma su número de una serie, de forma correlativa e inmutable. Las series tienen un type que debe ser compatible con el tipo de factura:

Serie (type)	Tipos de factura que numera
normal	F1, F3
simplified	F2
rectified	R1–R5
quote	(presupuestos; fuera de la API pública)

• El code de una serie es único por tenant (409 serie.code_taken si choca).
• Puedes elegir si la numeración se reinicia por ejercicio fiscal (resets_per_fiscal_year) y el modo de redondeo (per_line / per_total).
• Inmutabilidad: en cuanto una serie numera su primer documento, su numeración queda bloqueada. Solo puedes cambiar name e is_active; tocar cualquier otro campo devuelve 409 serie.numbering_started. Un borrador no cuenta: mientras no hayas emitido, la serie es editable entera.
• El type se fija al crear y no se cambia nunca (409 serie.type_immutable): la compatibilidad entre tipo de serie y tipo de factura se valida al crear la factura, así que moverlo dejaría facturas en una serie que no les toca.
• No puedes borrar una serie con documentos, aunque sean borradores (409 serie.in_use), ni la última serie de un tipo (409 serie.last_of_type).

Número de partida (start_number)

Por defecto la primera factura de una serie es la 1. Si migras desde otro programa de facturación y quieres continuar tu numeración anterior, informa start_number al crear la serie:

{ "code": "F26", "name": "Facturas 2026", "type": "normal",
  "prefix": "F26-", "num_size": 4, "start_number": 1250 }

• Solo siembra el primer periodo de numeración. Con resets_per_fiscal_year: true, el ejercicio siguiente vuelve a empezar en 1.
• Sigue siendo editable por PATCH mientras la serie no haya numerado nada (un borrador no cuenta), igual que el resto de la numeración. Después devuelve 409 serie.numbering_started; reenviar el mismo valor no cuenta como cambio y no da error.

Si omites serie_id al crear, el backend elige la serie por defecto según la cascada de defaults.