Factures recurrents

Una factura recurrent és una plantilla més una cadència: Factuarea genera una factura real a cada execució programada. Aquesta guia cobreix els controls que van més enllà del create/update bàsic — ometre un cicle, arrencar una recurrència a partir d'una factura existent, l'enviament automàtic per correu, la previsualització del document calculat i els camps fiscals per línia que exigeix VeriFactu.

Tots els endpoints de sota viuen sota https://api.factuarea.com/v1 i usen el mateix embolcall d'error, paginació per cursor i scopes que la resta de l'API.

Ometre la pròxima generació

POST /v1/recurring_invoices/{recurring_invoice}/skip

Avança next_run_at exactament un període sense generar cap factura per al cicle actual. L'ocurrència omesa no compta per a max_occurrences — el comptador de factures generades no es mou. Fes-lo servir per saltar-te un període de facturació (festius, un client en pausa) mantenint intacte el calendari.

Requereix l'scope recurring_invoices:write. Retorna 200 amb el recurs de la factura recurrent (fixa't en el next_run_at avançat). Una recurrència cancel·lada o completada respon 422; una factura recurrent que pertany a una altra empresa respon 404.

curl -X POST https://api.factuarea.com/v1/recurring_invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/skip \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Crear una recurrència des d'una factura existent

POST /v1/invoices/{invoice}/create-recurring

Copia les línies, el client i la sèrie d'una factura origen en una factura recurrent nova (amb el seu propi UUID v7) i aplica la cadència indicada al cos. La factura origen queda intacta. Requereix l'scope recurring_invoices:write.

Retorna 201 amb la nova factura recurrent i una capçalera Location que hi apunta. Una factura origen que pertany a una altra empresa respon 404.

curl -X POST https://api.factuarea.com/v1/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42/create-recurring \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": "monthly",
    "start_on": "2026-07-01",
    "max_occurrences": 12,
    "auto_delivery": {
      "send_automatically": true,
      "recipients": ["billing@acme.example"]
    }
  }'

Enviament automàtic

L'objecte auto_delivery — disponible en crear i actualitzar una recurrent i a create-recurring — envia per correu cada factura generada de manera automàtica.

Quan send_automatically és true, cada factura generada s'envia per correu a recipients (amb cc opcional) usant subject/body. Posar send_automatically a false desactiva l'enviament. Una llista recipients buida amb send_automatically: true es rebutja amb 422 — no hi ha a qui enviar.

{
  "auto_delivery": {
    "send_automatically": true,
    "recipients": ["billing@acme.example"],
    "cc": ["copy@acme.example"],
    "subject": "La teva factura mensual",
    "body": "Hola, aquí tens la teva factura d'aquest període."
  }
}

Previsualitzar el document calculat

GET /v1/recurring_invoices/{recurring_invoice}/preview

Sense expand, preview retorna només la previsió de dates — les pròximes dates d'execució (usa count per controlar quantes).

Passa expand=document per calcular a més el pròxim document en sec: la resposta afegeix un bloc next_invoice amb les lines resoltes i els totals (subtotal, tax, total), construïts des de template_data sense persistir res. Fes-lo servir per mostrar al client què contindrà exactament la pròxima factura abans d'emetre-la.

curl -G https://api.factuarea.com/v1/recurring_invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "expand=document"

{
  "data": { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b", "object": "recurring_invoice" },
  "next_invoice": {
    "lines": [
      { "description": "Quota mensual", "quantity": 1, "unit_price": 500, "subtotal": 500 }
    ],
    "totals": { "subtotal": 500, "tax": 105, "total": 605 }
  }
}

Camps fiscals per línia

Cada línia de template_data accepta els camps fiscals que necessiten VeriFactu i el model tributari espanyol. Es traslladen a cada factura generada.

El recàrrec d'equivalència va lligat per llei a l'IVA de la línia. Els únics parells legals tax_rate → surcharge són:

Enviar un exemption_reason, regime_key, retention_rate_id o surcharge_rate_id fora del seu catàleg respon 422 amb una llista allowed_values a l'error. Un parell IVA↔recàrrec il·legal (p.ex. 21 amb 1.4) també es rebutja amb 422.

{
  "template_data": {
    "lines": [
      {
        "description": "Consultoria",
        "quantity": 1,
        "unit_price": 1000,
        "tax_rate": 21,
        "surcharge": 5.2,
        "retention": 15,
        "regime_key": "01",
        "exemption_reason": null
      }
    ]
  }
}