Data Management3 min

Facture d’origine d’un avoir

Relier un avoir à sa facture d’origine sans créer d’allocation ni modifier les soldes.

originalInvoiceId désigne la facture à l’origine d’un avoir. Il ne représente aucun montant imputé : ajouter, remplacer ou retirer ce lien ne crée pas d’allocation et ne change ni solde ni statut de paiement. La création de l’avoir conserve son comportement financier habituel.

Créer et compléter un avoir

POST /api/public/v1/credit-notes accepte le champ multipart facultatif originalInvoiceId : transmettez l’UUID de la facture dans Billabex, et non sa référence GEXTIA. Un champ omis, vide ou contenant le texte null crée l’avoir sans lien.

Si la facture arrive plus tard, retrouvez-la par son identifiant source :

GET /api/public/v1/invoices?organizationId=<organizationId>&filters=sourceId:is:<sourceId>

Encodez les valeurs des paramètres de query dans l’URL. Transmettez ensuite l’UUID obtenu, avec le scope credit-notes:all :

PUT /api/public/v1/credit-notes/{creditNoteId}/original-invoice
Content-Type: application/json

{ "originalInvoiceId": "123e4567-e89b-42d3-a456-426614174000" }

Le même endpoint remplace un lien existant. Pour le retirer :

{ "originalInvoiceId": null }

Le PUT exige le champ, même pour un retrait. Les champs inconnus sont refusés. La réponse 200 contient l’avoir actualisé, avec originalInvoiceId. Ce champ est aussi présent dans les listes et les détails, avec null en l’absence de lien. Répéter la valeur courante ne produit aucun événement supplémentaire. Les intégrations qui ne transmettent pas ce champ continuent de fonctionner.

Validation et suppression

La facture doit exister dans la même organisation, sur le même compte client et dans la même devise. Les références invalides ou incompatibles donnent 400 :

  • app-invoicing.credit-note.original-invoice-invalid : UUID invalide ou facture indisponible.
  • app-invoicing.credit-note.original-invoice-account-mismatch : compte différent.
  • app-invoicing.credit-note.original-invoice-currency-mismatch : devise différente.

Un avoir cible introuvable donne 404. Les droits d’écriture restent requis. Le lien documentaire reste modifiable lorsque readOnlyReason signale un avoir synchronisé ; les restrictions sur ses montants et sa suppression restent en vigueur.

Si la facture est supprimée, son UUID reste sur l’avoir comme trace documentaire. L’avoir n’est pas supprimé et son lien reste corrigeable. Répéter cette référence conservée reste sans effet ; essayer de la poser sur un autre avoir est refusé. Le nettoyage des allocations financières existantes lors de la suppression de facture reste indépendant de cette référence.

MCP et webapp

Le MCP accepte originalInvoiceId dans create-credit-note et propose set-credit-note-original-invoice, avec le scope mcp:write. get-credit-note et list-credit-notes renvoient la référence. La webapp permet la sélection à la création et dans le détail de l’avoir.

Pour GEXTIA, conservez reversed_entry dans l’ETL jusqu’à la disponibilité de la facture Billabex. Ne créez pas de /credit-allocations à partir de cette seule référence : une allocation exige un montant réellement imputé, qui pourrait être déjà pris en compte dans les soldes synchronisés.