Treballar amb factures

Emesa no vol dir enviada

Emetre una factura i lliurar-la són dos fets diferents. Emetre és l’acte fiscal: la factura rep el número definitiu de sèrie, el registre VeriFactu i els moviments d’stock, i el seu estat passa a issued. Enviar vol dir que el client l’ha rebuda: un email acceptat pel servidor de correu o un lliurament que registres tu. Viu en camps propis (is_sent, sent_at, sent_via), independents de l’estat i del cobrament.

• Emet un esborrany sense enviar-lo per correu amb POST /v1/companies/{company}/invoices/{invoice}/issue, o emet-lo i envia’l en un sol pas amb POST /v1/companies/{company}/invoices/{invoice}/send.
• Registra un lliurament fet per un canal propi amb POST /v1/companies/{company}/invoices/{invoice}/mark-sent i esborra’l amb POST /v1/companies/{company}/invoices/{invoice}/unsend.
• Filtra les factures pendents de lliurar amb GET /v1/companies/{company}/invoices?status=issued&is_sent=false.
• Tria què fa cada execució d’una factura recurrent amb generation_mode: draft, issue o issue_and_send.

Aquest vocabulari requereix la versió de l’API 2026-10-01. Les versions anteriors, inclosa la predeterminada, publiquen una factura emesa com a sent i posen l’instant d’emissió a sent_at. Consulta Versionat i la publicació de Novetats.

IVA d'una línia sense tipus

Una línia de venda pren el seu IVA de la primera font que el tingui: el tax_rate que declares (un 0 és un tipus real del 0 %), l'impost al qual fa referència, l'impost del seu producte i, si no n'hi ha cap, l'IVA per defecte de l'empresa per a aquest tipus de document (factura, pressupost, proforma, albarà o factura recurrent). Si l'empresa tampoc no té un IVA per defecte, la petició es rebutja amb 422 missing_required_param, error.param: lines.2.tax_rate i error.line_index: 2, la posició de la línia començant per zero.

Els errors de domini que neixen d'una línia d'un document porten el mateix line_index (error.line_index a l'API, error.data.line_index a MCP), de manera que saps quina línia corregir sense llegir el missatge.

Preus amb IVA inclòs

Quan els imports que tens són els preus finals que va pagar el teu client, envia prices_include_tax: true a POST /v1/companies/{company}/invoices. Cada unit_price és aleshores el preu final, i Factuarea calcula la base neta al cèntim perquè el total de la factura sigui igual a la suma dels imports que has enviat. Quan cap línia pot absorbir els cèntims, la més gran es parteix en dues i el total continua sent exacte; si no es pot assolir de cap manera (una retenció o un recàrrec el desplacen), la petició es rebutja amb 422 amount_reconciliation_failed i no s'emet res. En aquest mode no s'admeten línies de catàleg (product_id). Els detalls són a Facturació des de terminals desatesos.

Les despeses d'enviament d'una proforma també són un import amb IVA inclòs: no se sumen a la base, i quan la proforma es converteix en factura passen a ser una línia la base de la qual és shipping_cost / (1 + r), amb IVA r, de manera que el total de la factura és igual al total amb enviament que mostra la proforma.

Registrar el pagament amb la factura

payment (method, i opcionalment paid_at i reference, per exemple la transacció del datàfon) registra el pagament de tot l'import just després d'emetre. Implica emetre, i la factura queda paid. Amb options.register_verifactu l'alta VERI*FACTU es genera a la mateixa crida, abans de la resposta.

Una factura emesa per error que ja té pagaments no es pot anul·lar si no ho demanes: POST /v1/companies/{company}/invoices/{invoice}/annul amb revert_collections: true reverteix tots els pagaments vigents (amb el motiu reservat issued_in_error) i anul·la la factura en una sola operació atòmica. Si falla un pas, no es reverteix res. És una anul·lació, no un reemborsament: quan el client ha de recuperar els seus diners, emet una factura rectificativa. GET /v1/companies/{company}/invoices/{invoice}/can-annul informa de requires_collection_reversal i d'active_collections_amount per endavant.

Data de l'operació

Quan l'operació va tenir lloc un dia diferent de la data d'emissió, envia operation_on (operation_date a l'aplicació). Segueix els articles 6.1.f i 7.1.c de l'RD 1619/2012:

• Pots fixar-la o canviar-la mentre la factura és un esborrany, i és immutable un cop emesa.
• No pot ser posterior a issued_on (422 operation_date_after_issue_date), tret que la primera línia que declara un regime_key faci servir 14 o 15.
• Una factura rectificativa hereta la data de la factura que corregeix.
• S'imprimeix al costat de la data d'emissió al PDF i a la pàgina pública, i es declara al registre VeriFactu com a FechaOperacion. No canvia la huella de cap registre existent.
• El recurs de factura la retorna com a operation_on.