Trabajar con facturas

Emitida no es enviada

Emitir una factura y entregarla son dos hechos distintos. Emitir es el acto fiscal: la factura recibe su número definitivo de serie, su registro VeriFactu y sus movimientos de stock, y su estado pasa a issued. Enviar significa que el cliente la ha recibido: un email aceptado por el servidor de correo o una entrega que registras tú. Vive en sus propios campos (is_sent, sent_at, sent_via), independientes del estado y del cobro.

• Emite un borrador sin enviarlo por correo con POST /v1/companies/{company}/invoices/{invoice}/issue, o emítelo y envíalo en un solo paso con POST /v1/companies/{company}/invoices/{invoice}/send.
• Registra una entrega hecha por un canal propio con POST /v1/companies/{company}/invoices/{invoice}/mark-sent y bórrala con POST /v1/companies/{company}/invoices/{invoice}/unsend.
• Filtra las facturas pendientes de entregar con GET /v1/companies/{company}/invoices?status=issued&is_sent=false.
• Elige qué hace cada ejecución de una factura recurrente con generation_mode: draft, issue o issue_and_send.

Este vocabulario requiere la versión de la API 2026-10-01. Las versiones anteriores, incluida la predeterminada, publican una factura emitida como sent y ponen el instante de emisión en sent_at. Consulta Versionado y la publicación de Novedades.

IVA de una línea sin tipo

Una línea de venta toma su IVA de la primera fuente que lo tenga: el tax_rate que declaras (un 0 es un tipo real del 0 %), el impuesto al que hace referencia, el impuesto de su producto y, si no hay ninguno, el IVA por defecto de la empresa para ese tipo de documento (factura, presupuesto, proforma, albarán o factura recurrente). Si la empresa tampoco tiene un IVA por defecto, la petición se rechaza con 422 missing_required_param, error.param: lines.2.tax_rate y error.line_index: 2, la posición de la línea empezando en cero.

Los errores de dominio que nacen de una línea de un documento llevan el mismo line_index (error.line_index en la API, error.data.line_index en MCP), de modo que sabes qué línea corregir sin leer el mensaje.

Precios con IVA incluido

Cuando los importes que tienes son los precios finales que pagó tu cliente, envía prices_include_tax: true en POST /v1/companies/{company}/invoices. Cada unit_price es entonces el precio final, y Factuarea calcula la base neta al céntimo para que el total de la factura sea igual a la suma de los importes que enviaste. Cuando ninguna línea puede absorber los céntimos, la mayor se parte en dos y el total sigue siendo exacto; si no se puede alcanzar de ninguna manera (una retención o un recargo lo desplazan), la petición se rechaza con 422 amount_reconciliation_failed y no se emite nada. En este modo no se admiten líneas de catálogo (product_id). Los detalles están en Facturación desde terminales desatendidos.

Los gastos de envío de una proforma también son un importe con IVA incluido: no se suman a la base, y cuando la proforma se convierte en factura pasan a ser una línea cuya base es shipping_cost / (1 + r), con IVA r, de modo que el total de la factura es igual al total con envío que muestra la proforma.

Registrar el pago con la factura

payment (method, y opcionalmente paid_at y reference, por ejemplo la transacción del datáfono) registra el pago de todo el importe justo después de emitir. Implica emitir, y la factura queda paid. Con options.register_verifactu el alta VERI*FACTU se genera en la misma llamada, antes de la respuesta.

Una factura emitida por error que ya tiene pagos no se puede anular si no lo pides: POST /v1/companies/{company}/invoices/{invoice}/annul con revert_collections: true revierte todos los pagos vigentes (con el motivo reservado issued_in_error) y anula la factura en una sola operación atómica. Si falla un paso, no se revierte nada. Es una anulación, no un reembolso: cuando el cliente tiene que recuperar su dinero, emite una factura rectificativa. GET /v1/companies/{company}/invoices/{invoice}/can-annul informa de requires_collection_reversal y de active_collections_amount de antemano.

Fecha de la operación

Cuando la operación tuvo lugar un día distinto de la fecha de emisión, envía operation_on (operation_date en la aplicación). Sigue los artículos 6.1.f y 7.1.c del RD 1619/2012:

• Puedes fijarla o cambiarla mientras la factura es un borrador, y es inmutable una vez emitida.
• No puede ser posterior a issued_on (422 operation_date_after_issue_date), salvo que la primera línea que declara un regime_key use 14 o 15.
• Una factura rectificativa hereda la fecha de la factura que corrige.
• Se imprime junto a la fecha de emisión en el PDF y en la página pública, y se declara en el registro VeriFactu como FechaOperacion. No cambia la huella de ningún registro existente.
• El recurso de factura la devuelve como operation_on.