Facture (invoice)

Rôle

La facture est l'objet comptable central du cycle de facturation. Elle peut être créée de manière autonome ou directement depuis une commande. L'émission d'une facture consigne un fait comptable ; elle ne réserve ni ne valide automatiquement une capacité de crédit. Les mouvements d'exposition sont orchestrés explicitement dans les processus.

La facture dispose d'un pendant : l'avoir (credit_note), qui fonctionne selon les mêmes règles mais réduit le montant engagé plutôt que de l'augmenter, et référence la facture d'origine.

Identifiant et structure

Chaque facture porte un identifiant stable préfixé par inv_.

{
  "object": "invoice",
  "id": "inv_4a7b2e9f1c3d8a5e",
  "merchant_id": "mer_1a2b3c4d5e6f7a8b",
  "buyer_id": "cmp_3a8f1d9c2b4e7f6a",
  "type": "invoice",
  "source_invoice_id": null,
  "source_reference": "FAC-2026-00042",
  "metadata": {},
  "status": "sent",
  "settlement_status": "unpaid",
  "amount_excluding_tax": 100000,
  "amount_tax": 20000,
  "amount_including_tax": 120000,
  "currency": "eur",
  "reference": "FAC-2026-00042",
  "issue_date": "2026-06-17",
  "due_date": "2026-07-17",
  "document_url": null,
  "created_at": "2026-06-17T10:00:00.000Z"
}

Type

Le champ type distingue deux variantes du même objet.

Champs

La contrainte HT + taxe = TTC est imposée à la création et à chaque mise à jour. Les montants sont des entiers positifs en centimes.

Cycle de vie

Le champ status décrit uniquement le cycle de vie du document : rédaction, émission, transmission, réception puis éventuelle annulation ou passage en pertes. Le règlement n'écrase jamais ce statut.

Les transitions draft → issued → sent → received sont pilotées par les actions métier de la facture. Les allocations de paiement n'affectent pas cet axe.

Règlement

Le champ settlement_status suit indépendamment le niveau de règlement de la facture. Il est calculé à partir des imputations de paiement et n'altère pas le cycle de vie du document.

partially_paid et paid sont mis à jour automatiquement lors des allocations de paiement. Le document PDF ne peut être supprimé ou remplacé lorsquesettlement_status vaut paid.

Solde restant dû

Ormuz expose une projection invoice_balance qui représente le reste à payer courant d'une facture. Cette projection tient compte des paiements déjà appliqués ainsi que des avoirs qui réduisent la créance ; elle ne faut donc pas recalculer ce solde à partir du seul amount_including_tax.

Le solde est calculé à la demande depuis l'état financier courant et peut être utilisé dans les processus via fetch_invoice_balance. Il sert également de snapshot dans les événements d'échéance, notamment invoice.overdue et invoice.due_date_stage_reached, afin qu'une relance utilise directement le montant restant à payer au moment où l'événement est émis.

Une facture dont le solde est nul n'est pas considérée comme impayée, même si son montant facial reste inchangé. À l'inverse, une nouvelle imputation ou un avoir modifie immédiatement la projection utilisée par les futurs événements.

Litiges

Un litige n'est pas une valeur de statut de la facture. Il est porté par un dispute autonome, ce qui permet d'ouvrir ou de clôturer un dossier sans perdre ni le status ni le settlement_status courants.

Le booléen disputed est une projection : il vaut true tant qu'au moins un litige open couvre la facture elle-même ou une ligne contextualisée par cette facture. Plusieurs litiges ouverts sur la même invoice ne créent pas de double comptage dans le receivable.

Émission

Émettre une facture (status : draft → issued) se fait soit via l'endpoint dédié, soit atomiquement à la création.

Créer et émettre en une seule opération

POST /v1/invoices

{
  "merchant_id": "mer_1a2b3c",
  "buyer_id": "cmp_3a8f1d",
  "type": "invoice",
  "amount_excluding_tax": 100000,
  "amount_tax": 20000,
  "amount_including_tax": 120000,
  "currency": "eur",
  "reference": "FAC-2026-00042",
  "issue_date": "2026-06-17",
  "due_date": "2026-07-17",
  "issue": true
}

Émettre une facture existante

POST /v1/invoices/inv_4a7b/issue

L'émission n'est pas bloquée par une capacité de crédit et ne produit aucun mouvement de crédit implicite. Si le marchand souhaite refléter la facture dans son exposition, un processus peut explicitement exécuter le node de consommation de crédit.

Document PDF

Un fichier de facture peut être joint à n'importe quel moment. Les formats acceptés sont PDF, JPEG et PNG, dans une limite de 10 Mo. L'URL est stockée dans document_url après upload.

POST /v1/invoices/inv_4a7b/document
GET /v1/invoices/inv_4a7b/document
DELETE /v1/invoices/inv_4a7b/document

La suppression et le remplacement du document sont bloqués lorsque le settlement_status est paid.

Avoirs

Un avoir (type: "credit_note") est une facture en sens inverse : il réduit la créance due par l'acheteur. Il suit les mêmes axes que la facture (status, settlement_status, émission, document, lignes). Pour les balances de créance, un avoir rattaché à une facture source suit le périmètre analytique de cette facture, notamment son bucket d'échéance et son éventuel litige.

POST /v1/invoices

{
  "merchant_id": "mer_1a2b3c",
  "buyer_id": "cmp_3a8f1d",
  "type": "credit_note",
  "source_invoice_id": "inv_4a7b2e",
  "amount_excluding_tax": 20000,
  "amount_tax": 4000,
  "amount_including_tax": 24000,
  "currency": "eur",
  "reference": "AV-2026-00007",
  "issue": true
}

Le champ source_invoice_id pointe vers la facture d'origine à titre documentaire — il n'y a pas de couplage automatique de statut entre la facture et l'avoir. Une éventuelle extourne de consommation de crédit reste une action explicite du processus, à partir du mouvement de consommation concerné.

Commandes et lignes d'article

Liaison avec les commandes

Une facture peut être liée à une ou plusieurs commandes.

Lignes d'article

Les lignes d'article de la facture sont accessibles via GET /v1/invoices/:id/line-items. La structure est identique à celle des lignes de commande (champs product_name, quantity, amount_including_tax, etc.).

Allocation

L'endpoint GET /v1/invoices/eligible-allocation retourne les factures ouvertes et les avoirs flottants éligibles à une allocation de paiement, pour un acheteur et un marchand donnés.

GET /v1/invoices/eligible-allocation?buyer_id=cmp_3a8f&merchant_id=mer_1a2b

{
  "invoices": [
    {
      "id": "inv_4a7b",
      "net_due": 120000,
      "currency": "eur"
    }
  ],
  "credit_notes": [
    {
      "id": "inv_9c2e",
      "net_due": 24000,
      "currency": "eur"
    }
  ]
}

Dans les processus

Il n'existe pas de node dédié à la création ou aux transitions d'une facture. L'objet est piloté via des appels API directs ou via des actions HTTP dans un processus d'orchestration.

Trois helpers génériques sont disponibles pour manipuler une facture dans un processus :fetch_invoice récupère une facture par identifiant,refresh_invoice recharge son état courant depuis la plateforme, et fetch_invoice_balance retourne son solde restant dû courant.

Événements

Les changements de règlement émettent invoice.partially_paid ou invoice.paid. Les litiges restent indépendants du règlement et génèrent leurs propres événements via l'objet dispute lié.