Anul·lació de cobraments

Un pagament que s'ha retornat — un rebut SEPA retornat, una retrocessió de targeta, un efecte impagat — ja té una via pròpia per registrar-se, i la factura que pagava torna al circuit de cobrament en lloc de quedar-se paid per sempre. Consulta Registrar pagaments.

Operació nova — POST /v1/invoices/{id}/payments/{payment_id}/reversal anul·la un pagament d'una factura de venda indicant un reason d'un catàleg tancat (direct_debit_return, card_dispute, misapplied_payment, bounced_effect, recording_error) i una note opcional. Retorna 200 amb el pagament ja anul·lat. Scope: invoices:write — no existeix una família de scopes payments:*.
El pagament no s'esborra mai — conserva el seu import, data, mètode i referència, i guanya is_reversed, reversed_at, reversal_reason, reversal_reason_text i reversal_note, els cinc publicats ja a tots els pagaments d'una factura. Un pagament anul·lat continua al ledger: llegeix is_reversed, no dedueixis l'anul·lació del fet que una entrada desaparegui.
La factura torna al circuit de cobrament — un import anul·lat deixa de computar a paid_amount i pending_amount, així que una factura paid passa a overdue si el seu venciment ja ha passat i a sent altrament, i torna a admetre un pagament. Només el ledger pot produir aquesta transició: l'endpoint genèric de canvi d'estat continua sense poder treure una factura de paid.
Esdeveniment nou payment.reversed — tanca el cicle que payment.received deixava explicat a mitges. El seu data.reversal porta el reason i un origin (gateway quan va ser la passarel·la la que va informar de la devolució, manual quan ho va registrar una persona). Consulta Esdeveniments.
Tool MCP nova revert_invoice_payment — el mirall de la ruta per a agents, amb el mateix scope invoices:write. Consulta el catàleg de tools.
Tres codis d'error nous, tots tres 422: payment_already_reversed, payment_reversal_reason_invalid i payment_reversal_invalid.

Anul·lar no és rectificar. Un rebut retornat significa que el client va recuperar els seus diners sense que l'operació es minori: el deute continua viu i no hi ha res a rectificar. Un reemborsament genuí sí que baixa els ingressos i conserva la seva rectificativa. Un rebut retornat tampoc no és el supòsit de crèdit incobrable de l'art. 80.Cuatro LIVA, que té els seus propis requisits formals. Consulta Anul·lació o rectificativa?.

Correcció de contracte (clients generats). POST /v1/invoices/{id}/payments i GET /v1/invoices/{id}/payments publicaven a l'spec OpenAPI el schema de factura, heretat del prefix del path, quan l'API retorna un cobrament — i el llistat anunciava a més un objecte singular en lloc d'un array. Totes dues publiquen ja InvoicePaymentDetail (un array al llistat). Cap resposta no ha canviat pel cable: és una correcció de documentació, no un canvi que trenca, perquè cap integració tipada no podia funcionar contra el tipus anterior. Si uses un SDK generat o el CLI, torna a generar-lo: el teu model d'aquestes dues operacions canviarà.

Nous endpoints1

Endpoint	Descripció
POST`/v1/invoices/{invoice}/payments/{payment}/reversal`	Anul·lar un pagament d'una factura