Auto-facturació amb Stripe

Quan connectes Stripe mitjançant Stripe Connect, Factuarea pot emetre una factura automàticament per cada cobrament correcte: el cobrament es converteix en una factura amb status: sent, es dona d'alta a VeriFactu i se li registra un Payment. El flux és idempotent d'extrem a extrem, així que un webhook reentregat mai produeix una factura duplicada.

L'alimenten dos fluxos:

• Flux A — un cobrament que paga una factura de Factuarea ja existent (una Checkout Session que Factuarea va crear des d'un enllaç de pagament). La factura ja existeix; el cobrament la marca com a pagada.
• Flux B — un cobrament espontani sense factura prèvia (un Payment Link que el comerç va crear al seu propi Dashboard de Stripe, o qualsevol altre cobrament de Connect). Factuarea crea la factura a partir del cobrament.

La configuració es llegeix i s'escriu a través dels endpoints v1 a nivell d'empresa:

• Obtenir la configuració d'auto-facturació (stripe_autoinvoicing:read).
• Actualitzar la configuració d'auto-facturació (stripe_autoinvoicing:write).
• Llistar cobraments auto-facturats (stripe_autoinvoicing:read).
• Llistar rectificatives auto-facturades (stripe_autoinvoicing:read).

Si gestiones diverses botigues amb comptes de Stripe diferents, cada compte té la seva pròpia sèrie i la seva pròpia configuració — consulta Diverses botigues.

L'auto-facturació està limitada pel mòdul d'integració amb Stripe del teu pla i ve desactivada per defecte — activa-la explícitament amb enabled: true.

Diverses botigues

Un negoci pot operar diverses "botigues" o línies (una botiga física + un curs en línia) amb comptes de Stripe diferents (Stripe Connect) i voler numeració de factures independent per a cadascuna (TIENDA-2026-…, CURSOS-2026-…). Factuarea modela cada compte de Stripe que connectes com un compte connectat: cada Account Link que completes afegeix un compte — mai sobreescriu l'anterior — i els cobraments de cada compte s'enruten a la sèrie i la configuració d'aquest compte.

Cada compte connectat porta:

• una sèrie (series_id) usada per a les factures auto-creades a partir dels seus cobraments — null significa que s'usa la sèrie de factures per defecte de l'empresa. Ha de ser una sèrie de factures completes (invoice_kind: complete), el propòsit que numera les F1;
• la seva pròpia configuració d'auto-facturació (autoinvoicing_enabled, simplified_threshold_cents, require_nif, refunds_enabled, subscription_autoinvoicing_enabled) — tota regla fiscal d'aquesta pàgina aplica per compte.

Quan arriba un webhook, Factuarea resol el compte de Stripe (acct_xxx) al seu compte connectat i emet la factura en la sèrie d'aquest compte, amb la política fiscal d'aquest compte — de manera que dues botigues produeixen factures en dues sèries de numeració separades i correctes.

Els comptes nous neixen segurs

Un compte acabat de connectar no hereta la configuració d'un altre compte: neix amb els mateixos valors per defecte segurs que una alta nova — auto-facturació desactivada, llindar 400 €, "exigir NIF" desactivat, devolucions actives, subscripcions desactivades — i sense sèrie (cau en la sèrie per defecte de l'empresa fins que li n'assignes una). Configura'l explícitament abans que emeti res.

Endpoints v1 per compte

Gestiona els comptes sota el recurs connected-accounts (mateixos scopes stripe_autoinvoicing:read|write; la identitat és l'id del compte, un UUID v7):

• Llistar comptes connectats (stripe_autoinvoicing:read).
• Obtenir un compte connectat (stripe_autoinvoicing:read).
• Actualitzar un compte connectat — nom, series_id (envia null per netejar-la) i la configuració per compte (stripe_autoinvoicing:write).
• Desconnectar un compte connectat (stripe_autoinvoicing:write).

# Assignar la sèrie CURSOS i activar l'auto-facturació en una botiga
curl -X PATCH https://api.factuarea.com/v1/companies/{company}/connected-accounts/0192f3a4-… \
  -H "Authorization: Bearer fact_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0192f3a4-…" \
  -d '{
    "series_id": "0192aaaa-…",
    "autoinvoicing_enabled": true
  }'

Desconnectar un compte conserva les seves factures ja emeses i el seu historial; els webhooks posteriors es registren sense processar. Referenciar l'id d'un compte que pertany a una altra empresa retorna 404 (connected_account_not_found) — l'aïllament multi-tenant mai filtra l'existència.

L'endpoint a nivell d'empresa mentre tens una botiga

Els endpoints de configuració a nivell d'empresa de dalt segueixen vàlids mentre tens exactament un compte connectat: el GET retorna la configuració efectiva d'aquest únic compte i el PATCH fa de proxy cap a ell (escriu en la configuració del compte, mai una còpia duplicada a nivell d'empresa).

Tan bon punt connectes un segon compte, la configuració a nivell d'empresa ja no pot respondre a "quin compte?". Tant el GET com el PATCH retornen llavors 422 (per_account_config_required, missatge en castellà) apuntant-te als endpoints per compte — Factuarea mai escriu en dos llocs, així que no hi ha divergència entre una configuració a nivell d'empresa i els comptes.

Connectar un compte de Stripe que ja tens

Factuarea ofereix dues maneres de connectar Stripe, i tries entre elles en connectar un compte:

Sense una elecció explícita el mètode és account_links, el flux de sempre. Cada compte connectat informa a connection_method del mètode amb què es va vincular, de manera que els dos tipus poden conviure en una mateixa empresa.

Instal·lar la Stripe App

1. A Factuarea, connecta un compte de Stripe i tria l'opció de compte existent.
2. Stripe et demana instal·lar l'app de Factuarea al compte que triïs i aprovar-ne els permisos.
3. De tornada a Factuarea, el compte apareix com a compte connectat amb connection_method: stripe_app i authorization_status: authorized. Com tot compte nou, la seva auto-facturació està desactivada fins que la configuris.

L'app només demana el que la integració llegeix: esdeveniments, cobraments, payment intents, sessions de Checkout, clients, factures, payouts, transaccions de saldo i disputes. El seu únic permís d'escriptura és crear sessions de Checkout, que Factuarea fa servir per als enllaços de pagament de les teves factures.

Estat d'autorització i reautoritzar

Cada compte connectat exposa authorization_status:

Factuarea renova l'accés de cada compte automàticament, i una tasca diària renova els comptes sense activitat, de manera que l'autorització no caduca només perquè passi un temps sense cobraments. Els esdeveniments que no necessiten l'API de Stripe, com una devolució, es continuen processant mentre una reautorització és pendent.

Per reautoritzar, repeteix la connexió amb l'opció de compte existent a la mateixa empresa. El compte conserva el seu id, nom, sèrie, configuració i regles, torna a authorized, i pots reprocessar els esdeveniments que estaven esperant.

Desinstal·lar o desconnectar

• Desinstal·lar l'app a Stripe desconnecta el compte a Factuarea: se n'esborren els tokens, el seu authorization_status passa a revoked i s'avisa els teus administradors (stripe_app_uninstalled a la safata). Les factures i l'historial es conserven, i els esdeveniments posteriors d'aquest compte es registren sense processar-se.
• Desconnectar des de Factuarea (Desconnectar un compte connectat) fa el mateix per part teva. L'app continua instal·lada a Stripe fins que la desinstal·lis des del teu Dashboard de Stripe.

Un compte, una empresa

Un compte de Stripe només pot estar actiu en una empresa alhora:

• Connectar un compte que és actiu en una altra empresa es rebutja amb 409 (stripe_account_linked_elsewhere). El missatge no revela quina empresa el té i no es desa res.
• Tornar a connectar un compte que ja és actiu a la teva empresa en renova les credencials, el mètode i l'estat d'autorització sense duplicar-lo: conserva el seu id, nom, sèrie, configuració i regles.
• Quan un compte es desconnecta, una altra empresa el pot connectar.
• Els webhooks s'encaminen a l'empresa que té el compte actiu.

Factura ordinària o simplificada

Una factura espanyola necessita el NIF del destinatari per emetre's com a factura ordinària (F1). Un cobrament B2C sense NIF és justament el cas que la normativa resol amb una factura simplificada (F2). Factuarea decideix quina emetre a partir de les dades que porta el cobrament més la teva política fiscal:

Un NIF capturat es valida contra el format espanyol (NIF/NIE/CIF). Un NIF amb format no vàlid compta com a sense NIF, així que mai s'emet una F1 amb dades escombraries.

El sostre legal absolut d'una factura simplificada és de 3.000 €, garantit pel propi domini de facturació: un cobrament sense NIF per sobre de 3.000 € sempre va a revisió manual, sigui quin sigui el llindar configurat.

Capturar el NIF al Checkout

Perquè un client que sí té NIF pugui aportar-lo, les Checkout Sessions que crea Factuarea (Flux A) activen la recollida de l'identificador fiscal de Stripe. El client pot introduir el seu es_cif/eu_vat en pagar, i aquest NIF encamina cap a la F1.

El NIF també es llegeix de qualsevol checkout.session.completed entrant:

• de customer_details.tax_ids (el camp estàndard de Stripe), i
• dels camps personalitzats dels Payment Links que el comerç construeix al seu propi Dashboard de Stripe — Factuarea busca un camp la clau del qual sembli un identificador fiscal (nif, dni, cif, vat, tax).

Un cobrament que arriba només com a payment_intent.succeeded (sense Checkout) no porta cap NIF capturat, però encara pot ser una F1 si el client es resol per email i ja té un NIF a la seva fitxa.

El llindar

simplified_threshold_cents és l'import en cèntims igual o per sota del qual un cobrament sense NIF s'auto-emet com a factura simplificada. El seu valor per defecte és 40000 (400 €) i accepta qualsevol valor en el rang [0, 300000] (0–3.000 €).

Un valor per defecte conservador de 400 € és deliberat: el sostre de 3.000 € només és legal en sectors taxats concrets, i Factuarea no coneix el teu sector — apuja el llindar únicament si la teva activitat ho permet.

curl -X PATCH https://api.factuarea.com/v1/companies/{company}/stripe-autoinvoicing/config \
  -H "Authorization: Bearer fact_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0192f3a4-…" \
  -d '{
    "enabled": true,
    "simplified_threshold_cents": 100000,
    "require_nif": false
  }'

Tots dos camps fiscals són opcionals: si omets simplified_threshold_cents o require_nif, es conserven els seus valors actuals. Un llindar fora del rang retorna 422 (validation_error).

Exigir un NIF

require_nif (per defecte false) té dos efectes coherents:

• A les Checkout Sessions que crea Factuarea, l'identificador fiscal es marca com a obligatori (if_supported), de manera que se li sol·licita al client.
• A la decisió de dalt, veta la F2: un cobrament sense NIF va a revisió manual en comptes de convertir-se en factura simplificada.

Activa'l quan la teva empresa no vulgui mai factures simplificades automàtiques: cada cobrament passa llavors a tenir NIF (F1) o a esperar-te en revisió manual.

L'esdeveniment sortint

Cada factura auto-creada — F1 o F2 — emet l'esdeveniment invoice.auto_created i un esdeveniment payment.received. En una factura simplificada el payload porta client_id: null (sense destinatari), de manera que un receptor de webhooks pot distingir la F1 de la F2.

Desglossament real d'IVA amb Stripe Tax

Si fas servir Stripe Tax, cada cobrament ja porta el desglossament fiscal real per línia — el tipus, la base imposable i, quan escau, la causa per la qual una línia està exempta o subjecta a inversió del subjecte passiu. Factuarea reflecteix aquest desglossament a la factura en lloc d'aplanar-ho tot a un únic tipus per defecte.

El webhook del Checkout no inclou les línies, així que Factuarea fa una segona crida de només lectura a l'API en nom teu per recuperar-les amb els seus impostos, i mapeja cada línia:

Així, un cobrament amb IVA mixt (p. ex. 21 % de consultoria + 10 % d'un llibre) es converteix en una factura amb dues línies reals, cadascuna al seu tipus, i el desglossament multi-IVA arriba fins al registre de VeriFactu.

Quan no hi ha Stripe Tax (no l'has activat al teu compte de Stripe) no canvia res: cada línia recorre a l'IVA per defecte de la teva empresa, igual que abans. Una empresa sense IVA per defecte configurat recorre al 0 % — mai a un 21 % fantasma.

Línies reals

Quan un cobrament porta diverses línies (diversos productes o conceptes), apareixen com a línies reals i independents a la factura — cadascuna amb la seva descripció, quantitat i preu — en lloc de col·lapsar-se en una de sola. Són línies lliures (no enllaçades al teu catàleg de productes).

Això és ortogonal al tipus de factura: la decisió F1/F2 de més amunt tria el tipus, el mapeig de línies tria les línies — tant una factura ordinària com una de simplificada obtenen les mateixes línies reals.

Un cobrament que arriba només com a payment_intent.succeeded (sense Checkout Session, de manera que no hi ha línies recuperables), o un cobrament la recuperació de línies del qual falla després dels reintents, continua produint una factura: recorre a una sola línia amb l'IVA per defecte. La factura mai no es perd per un detall no essencial.

Abans d'emetre, Factuarea valida el total: el total derivat de les línies reflectides (suma de subtotal + IVA per línia, en EUR) ha de coincidir amb l'import realment cobrat, dins d'una petita tolerància d'arrodoniment (±1 cèntim per línia, mínim ±0,05 €). Si no coincideix, el cobrament es deriva a revisió manual (total_mismatch) en lloc d'emetre una factura el total de la qual divergeixi del cobrament real — el webhook respon correctament igualment.

Concepte dels cobraments sense Checkout

Un cobrament que arriba sense sessió de Checkout no té línies que reflectir, així que la factura porta una sola línia. La seva descripció és la primera d'aquestes que existeixi:

1. el concept de la regla de tractament que ha coincidit;
2. la descripció del PaymentIntent;
3. el concepte per defecte del compte, default_line_concept;
4. el text genèric, Cobro Stripe pi_….

El text es talla a 255 caràcters. Fixa el concepte per defecte d'un compte amb Actualitzar un compte connectat (stripe_autoinvoicing:write), d'1 a 255 caràcters; null l'esborra:

curl -X PATCH https://api.factuarea.com/v1/companies/{company}/connected-accounts/0192f3a4-… \
  -H "Authorization: Bearer fact_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0192f3a4-…" \
  -d '{ "default_line_concept": "Reserva en línia" }'

default_line_concept, connection_method i authorization_status formen part de cada compte connectat a Llistar comptes connectats i Obtenir un compte connectat.

Nota i venciment de les factures automàtiques

Cada factura que Factuarea emet automàticament des d'un compte connectat pot portar una nota que configures una vegada per compte, invoice_note: fins a 500 caràcters, sense espais sobrants, que s'escriu a les notes de cada factura. Per defecte és null i llavors les factures surten sense nota.

Fixa-la amb Actualitzar un compte connectat (stripe_autoinvoicing:write). Si ometes invoice_note es queda com està, una cadena buida o null la treu i un text l'assigna; un text de més de 500 caràcters retorna 422 parameter_invalid_value amb param invoice_note:

curl -X PATCH https://api.factuarea.com/v1/companies/{company}/connected-accounts/0192f3a4-… \
  -H "Authorization: Bearer fact_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0192f3a4-…" \
  -d '{ "invoice_note": "Pagat en línia amb targeta. Gràcies per la teva compra." }'

Si el cobrament va ser en una altra moneda, la línia amb la conversió a EUR i el tipus del BCE s'afegeix a la nota. invoice_note forma part de cada compte connectat a Llistar i Obtenir un compte connectat, i la tool MCP update_stripe_connected_account l'accepta.

Les factures automàtiques prenen el venciment per defecte de qualsevol factura: 30 dies des de la data d'emissió.

Envia cada factura a qui paga

Cada compte connectat pot, a més, enviar per correu cada factura que Factuarea emet automàticament a l'adreça que arriba amb el cobrament de Stripe, és a dir, a la persona que va pagar: email_invoice_to_payer, false per defecte. Factuarea pren l'adreça del Checkout (customer_details.email), de la factura de Stripe d'una subscripció (customer_email) o del mateix cobrament (receipt_email), i envia la factura amb la plantilla de la teva empresa, el seu PDF adjunt i sense botó de pagament, perquè ja està cobrada.

L'adreça és només on es lliura la factura: no es desa a la factura. Una factura simplificada continua sent simplificada, sense destinatari; quan el cobrament identifica el client, la factura completa s'emet al seu nom com sempre i s'envia també a l'adreça del cobrament.

Activa-la amb Actualitzar un compte connectat (stripe_autoinvoicing:write). Si l'ometes es queda com està, i un valor que no sigui booleà retorna 422 parameter_invalid_value amb param email_invoice_to_payer:

curl -X PATCH https://api.factuarea.com/v1/companies/{company}/connected-accounts/0192f3a4-… \
  -H "Authorization: Bearer fact_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0192f3a4-…" \
  -d '{ "email_invoice_to_payer": true }'

L'enviament mai desfà la factura ni el cobrament, i mai fa fallar el webhook. Si un cobrament no porta correu, o l'enviament es rebutja, la factura s'emet i es cobra igualment, i el resultat queda als esdeveniments de la integració: autoinvoice.email_requested, autoinvoice.email_skipped (el cobrament no porta un correu vàlid) o autoinvoice.email_failed (l'enviament es va rebutjar, per exemple perquè la identitat de remitent de la teva empresa encara no està verificada). L'opció forma part de cada compte connectat a Llistar i Obtenir un compte connectat, i la tool MCP update_stripe_connected_account l'accepta.

Cobraments en una altra moneda

Un cobrament en una moneda diferent de l'EUR ja no es descarta. Factuarea el converteix a EUR fent servir el tipus de canvi de referència del Banc Central Europeu (BCE) de la data de pagament i emet la factura en euros — base, IVA i total, i el registre de VeriFactu/AEAT, tot en EUR (Art. 12.1 RD 1619/2012: la quota d'IVA s'ha de consignar en euros).

• Un cobrament en EUR passa intacte.
• Un cobrament ≠EUR amb tipus disponible es converteix; la traça de la conversió — import i moneda originals, tipus BCE i data del tipus — s'escriu a les notes de la factura i al registre d'integració per a l'auditoria fiscal.
• Un cobrament en una moneda sense tipus BCE disponible no s'auto-factura: es deriva a revisió manual i el webhook respon correctament igualment. Factuarea mai no inventa un tipus. L'entrada apareix a la safata com a unsupported_currency, aparcada: quan es publiqui el tipus oficial d'aquella data, reprocessar l'esdeveniment emet la factura.

Els tipus del BCE es memoritzen a diari (sense taula de base de dades addicional), de manera que diversos cobraments ≠EUR del mateix dia comparteixen una sola consulta del tipus.

Cobraments que no es facturen: regles de tractament

No tot cobrament és una operació subjecta. Una penalització cobrada en una targeta, o la venda d'un val regal bescanviable per qualsevol servei, pot no ser una operació que s'hagi de facturar en el moment del pagament. Cada compte connectat té les seves pròpies regles de tractament, que decideixen què passa amb un cobrament espontani, el que no paga una factura que ja tinguessis a Factuarea:

• Facturar-lo, opcionalment amb el seu propi concepte i tipus d'IVA.
• No facturar-lo, indicant un motiu d'una llista tancada. No es crea factura, Payment ni registre de VeriFactu; el cobrament queda al llistat de cobraments no facturats.

Les regles s'avaluen per ordre de position i decideix la primera que coincideix. Si cap no coincideix, el cobrament es factura com es descriu a la resta d'aquesta pàgina.

Condicions

La metadata és la del PaymentIntent fusionada amb la de la sessió de Checkout o la de la factura de Stripe (guanya aquesta última si una clau es repeteix). Les descripcions que es comparen són la del PaymentIntent, les de les línies del Checkout, i les de la factura de Stripe i les seves línies.

Resultats

Els valors de non_invoice_reason són indemnity_not_subject, multipurpose_voucher i invoiced_elsewhere (el cobrament ja es factura en un altre sistema). Una combinació que incompleix aquestes regles respon 422 (charge_rule_invalid, amb el camp a error.param), i un compte admet fins a 50 regles (charge_rule_limit_reached).

Les regles mai s'apliquen al cobrament que paga una factura creada a Factuarea (el que porta metadata.factuarea_invoice) ni als cicles de subscripció.

Exemples i la seva base normativa

Penalització per cancel·lar o no presentar-se, sense bestreta prèvia. La consulta vinculant de la Dirección General de Tributos (DGT) V0839-20 considera que el càrrec a la targeta per cancel·lar fora de termini o no presentar-se, sense bestreta prèvia, té naturalesa indemnitzatòria, per la qual cosa no hi ha operació subjecta a l'IVA. Es basa en l'art. 78.Tres.1º LIVA: les indemnitzacions que, per la seva naturalesa i funció, no siguin contraprestació d'una operació subjecta no formen part de la base imposable. Si el client havia pagat una bestreta que retens, el tractament és diferent i es corregeix amb una rectificativa manual.

{
  "condition": { "type": "metadata_equals", "key": "type", "value": "penalty" },
  "outcome": "do_not_invoice",
  "non_invoice_reason": "indemnity_not_subject"
}

Val univalent. Quan el servei i el seu tipus d'IVA es coneixen en vendre el val, la seva venda ja és l'operació subjecta i es factura al tipus d'aquest servei (Resolució de la DGT de 28-12-2018, BOE-A-2018-18094).

{
  "condition": { "type": "description_contains", "value": "val regal" },
  "outcome": "invoice",
  "concept": "Val regal",
  "vat_rate": 10
}

Val polivalent. Quan encara no es coneix el servei o el tipus, la seva venda no està subjecta a l'IVA i l'impost es merita en bescanviar-lo (mateixa Resolució, apartat tercer). Els cobraments exclosos així conserven el seu motiu multipurpose_voucher.

{
  "condition": { "type": "payment_link", "value": "plink_1Pabc2DEFghi3JKL" },
  "outcome": "do_not_invoice",
  "non_invoice_reason": "multipurpose_voucher"
}

A l'aplicació, aquestes tres vénen com a plantilles, cadascuna amb la seva base normativa i el recordatori de confirmar-ho amb el teu assessor.

Gestionar les regles

Sis operacions sota connected-accounts/{account}, amb els scopes stripe_autoinvoicing:read (els llistats) i stripe_autoinvoicing:write (la resta). L'id d'una regla és un UUID v7, i una regla o un compte d'una altra empresa respon 404 (charge_rule_not_found, connected_account_not_found).

• Crear respon 201 amb la regla, col·locada al final de la llista.
• Actualitzar és un PUT complet: torna a enviar condition, outcome, concept, vat_rate i non_invoice_reason, i no canvia la position.
• Reordenar rep tots els id de les regles del compte en el nou ordre: { "rule_ids": ["…", "…"] }. Una llista incompleta, repetida o amb un id que no és del compte respon 422 (charge_rule_invalid) i no canvia res.
• Eliminar respon 204. Els cobraments que havia exclòs conserven el seu registre.

{
  "id": "0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f",
  "object": "charge_rule",
  "position": 1,
  "condition": { "type": "metadata_equals", "key": "type", "value": "penalty" },
  "outcome": "do_not_invoice",
  "non_invoice_reason": "indemnity_not_subject",
  "concept": null,
  "vat_rate": null,
  "created_at": "2026-10-07T09:30:00+00:00",
  "updated_at": "2026-10-07T09:30:00+00:00"
}

Cobraments no facturats

Cada cobrament que exclou una regla queda registrat una sola vegada, sigui quin sigui el nombre d'esdeveniments que Stripe enviï per ell. El llistat es pagina per cursor (limit d'1 a 100, 25 per defecte, starting_after i ending_before), del més recent al més antic, i es pot acotar a un període amb occurred_from i occurred_to (YYYY-MM-DD, tots dos inclosos, segons la data del cobrament):

{
  "data": [
    {
      "id": "0192f3b8-1e4a-7f20-8c3d-5e6f7a8b9c0d",
      "object": "non_invoiced_charge",
      "connected_account_id": "0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081",
      "transaction_id": "pi_3PenaltyAbC",
      "amount": 30.0,
      "refunded_amount": 10.0,
      "net_amount": 20.0,
      "currency": "EUR",
      "description": "Penalització per no presentar-se",
      "reason": "indemnity_not_subject",
      "charge_rule_id": "0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f",
      "occurred_at": "2026-10-07T20:15:00+00:00",
      "refunded_at": "2026-10-08T09:02:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

amount, refunded_amount i net_amount van en unitats majors de la divisa del cobrament (currency), amb l'escala decimal que Stripe fa servir per a aquesta divisa (3.000 JPY és 3000, 30,00 EUR és 30). charge_rule_id és null quan la regla que va excloure el cobrament es va eliminar després. La safata mostra cadascun d'aquests esdeveniments com a excluded_by_charge_rule.

• Una devolució d'un cobrament no facturat no crea rectificativa ni va a revisió manual: es registra com a refund_of_non_invoiced_charge i se suma al refunded_amount del cobrament (devolucions completades i pendents), amb la data de l'última a refunded_at. net_amount és el que es queda el comerç: amount menys refunded_amount. Si una devolució pendent acaba fallant o es cancel·la, es torna a restar.
• En l'enviament trimestral, el ZIP i l'email a la gestoria afegeixen cobros_sin_factura_Q{quarter}_{year}.csv amb els cobraments del trimestre i les devolucions fetes en ell: cada devolució compta en el trimestre en què es produeix, com a línia negativa quan el cobrament és d'un trimestre anterior. Envia include_non_invoiced_charges: false per deixar fora el fitxer.
• Una disputa d'un cobrament no facturat no anul·la cap cobrament.

Devolucions i factures rectificatives

Una factura emesa és fiscalment irreversible — mai s'esborra ni s'anul·la un cop pagada. L'única manera legal de desfer-la és una factura rectificativa. Per això, quan Stripe retorna un cobrament que Factuarea va facturar, Factuarea tanca el cicle fiscal per tu: el webhook charge.refunded genera automàticament una factura rectificativa enllaçada (amb el seu propi registre R de VeriFactu), sense rectificar a mà.

Ho controla refunds_enabled (per defecte true). Només actua mentre l'auto-facturació està activada — el gating és enabled && refunds_enabled. Una empresa que mai va activar l'auto-facturació no veu cap canvi.

La rectificativa s'emet sempre per diferències (AEAT TipoRectificativa: I), perquè una devolució és un abonament amb imports negatius. Porta el motiu de correcció devolucion; si l'original és una factura simplificada (F2), la rectificativa s'emet com a R5 automàticament.

Cada document es numera en una sèrie del seu propi propòsit: la rectificativa va a la sèrie de rectificatives per defecte de l'empresa (R-2026-001…; RS per a una R5), i una factura simplificada autofacturada, a la sèrie de simplificades per defecte, no a la sèrie del compte. Qualsevol d'elles es crea al moment si l'empresa no en té cap.

La factura original es localitza per dos camins — per la metadada factuarea_invoice del cobrament (Flux A) o per l'UUID determinista derivat del payment_intent (Flux B) — així que les devolucions de cobraments emesos abans que existís aquesta funció també es rectifiquen.

Cada rectificativa automàtica emet l'esdeveniment invoice.corrective_auto_created (que porta la rectificativa, la factura original, el refund_id d'origen i el provider), i pots llistar-les amb Llistar rectificatives auto-facturades.

Cicles de subscripció

Si cobres amb Stripe Billing al teu compte connectat — subscripcions recurrents mensuals o anuals — Factuarea pot emetre una factura automàticament per cada cicle cobrat. Cada renovació que cobra Stripe produeix la seva pròpia factura conforme a VeriFactu, espejant el desglossament real (línies, període, impostos) que Stripe ja va calcular, igual que els cobraments únics.

És un toggle separat, subscription_autoinvoicing_enabled (per defecte false), per sobre del flag general enabled. Tots dos han d'estar actius perquè un cicle es facturi — activar només les subscripcions no fa res mentre l'auto-facturació està globalment desactivada.

curl -X PATCH https://api.factuarea.com/v1/companies/{company}/stripe-autoinvoicing/config \
  -H "Authorization: Bearer fact_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0192f3a4-…" \
  -d '{
    "enabled": true,
    "subscription_autoinvoicing_enabled": true
  }'

Quins cicles es facturen

Factuarea factura el cicle de facturació estàndard i deriva la resta a revisió o l'ignora, segons el billing_reason de Stripe:

• Els trials no facturen. Un cicle el invoice.total del qual és 0 € (un període de prova, o un cicle cobert íntegrament per crèdit) no emet factura; el primer cobrament real després del trial es factura amb normalitat.
• Els prorrateigs standalone (un upgrade/downgrade cobrat pel seu compte, fora del cicle regular) no s'auto-facturen avui — van a revisió manual perquè decideixis. Apareixen a la safata com a subscription_proration_review, que és accionable però no reprocessable: el billing_reason no canvia mai, així que la factura s'ha d'emetre a mà. El cicle regular següent es factura com sempre.
• La decisió F1/F2 és la mateixa. El NIF del destinatari es llegeix dels customer_tax_ids de la invoice (més la fitxa del client resolt); amb NIF el cicle és una factura ordinària (F1), sense ell i igual o per sota del llindar una simplificada (F2), i sense ell per sobre del llindar (o amb "exigir NIF" activat) va a revisió manual — idèntic a les regles de la secció de decisió. S'apliquen el mateix espejament de línies/IVA de Stripe Tax, la conversió a EUR i la validació de total.

Cada cicle és la seva pròpia factura

Un cicle de subscripció es converteix en una factura solta — no crea ni toca cap factura recurrent de Factuarea. Les dues són independents: Stripe porta la cadència i cada invoice.paid produeix una factura.

L'esdeveniment sortint

Una factura de cicle de subscripció emet un esdeveniment diferent, invoice.subscription_auto_created (a més de payment.received), de manera que un receptor de webhooks pot distingir els cicles de subscripció dels cobraments únics. Un cobrament únic continua emetent invoice.auto_created com abans. El llistat de cobraments auto-facturats (Llistar cobraments auto-facturats) exposa el context de subscripció (subscription_id, stripe_invoice_id, period_start, period_end) per als cobraments de cicle (null per a cobraments únics), i un filtre opcional origin (subscription/oneshot).

Aquest mateix context viatja també a la factura mateixa, com a claus de metadata de sistema per les quals pots filtrar els llistats. A Metadata i conciliació hi tens la taula completa —quines claus s'escriuen sempre i quines s'ometen quan no apliquen— i dues receptes a punt: totes les factures d'una subscripció, i les factures d'un sol període de facturació.

Factures soltes de Stripe

Una factura que crees a Stripe a mà (manual) o que surt d'un pressupost acceptat (quote_accept) es factura des del seu esdeveniment invoice.paid, amb les seves línies reals, sempre que el compte tingui l'auto-facturació activada. Si no, espera a la safata com a autoinvoicing_disabled, aparcada, perquè la puguis reprocessar.

• El cobrament s'identifica pel PaymentIntent que va pagar la factura (l'id de la factura quan no n'hi ha), de manera que la factura de Factuarea és la mateixa que s'hauria emès a partir del pagament mateix.
• S'apliquen les regles de tractament, amb la descripció i les línies de la factura de Stripe.
• La decisió F1/F2, la conversió a EUR i la validació del total són les mateixes que en qualsevol cobrament.

Un cobrament, una factura

Un mateix cobrament pot arribar a Factuarea per diversos esdeveniments. Factuarea reconeix a què pertany cada pagament, així que mai produeix dues factures:

• El PaymentIntent d'una sessió de Checkout es factura amb les dades de la sessió (línies, NIF, metadata i Payment Link), arribi abans l'esdeveniment que arribi.
• El PaymentIntent d'una factura creada a Stripe o d'un cicle de subscripció no es factura com a cobrament espontani: queda a la safata com a handled_by_stripe_invoice, i la seva factura surt d'invoice.paid.
• Un esdeveniment reentregat, o un segon esdeveniment del mateix cobrament, produeix com a màxim una factura.

Valors per defecte d'un cop d'ull

Amb aquests valors per defecte, l'únic canvi de comportament un cop activada l'auto-facturació és que un cobrament sense NIF de fins a 400 € es converteix en factura simplificada en comptes d'esperar en revisió, i una devolució genera la seva factura rectificativa automàticament. Els cobraments amb NIF es comporten exactament igual que abans. Els cicles de subscripció queden desactivats fins que optis per ells amb subscription_autoinvoicing_enabled.