Facture fournisseur (supplier_invoice)
Une supplier_invoice représente une facture reçue d'un fournisseur. Son modèle sépare le cycle de réception et d'approbation, l'avancement du règlement et l'existence d'un litige afin que ces trois dimensions puissent évoluer sans s'écraser mutuellement.
Rôle
La facture fournisseur est le document central du flux accounts payable. Elle peut être rapprochée d'un ou plusieurs bons de commande, soumise à approbation, planifiée pour paiement puis imputée à un paiement fournisseur.
Le champ type distingue une facture (invoice) d'un avoir fournisseur (credit_note). Un avoir peut référencer sa facture d'origine via source_invoice_id.
Identifiant et structure
Chaque facture fournisseur porte un identifiant préfixé par sinv_.
{
"object": "supplier_invoice",
"id": "sinv_4a7b2e9f1c3d8a5e",
"merchant_id": "mer_1a2b3c4d5e6f7a8b",
"supplier_id": "cmp_3a8f1d9c2b4e7f6a",
"supplier_contact_id": null,
"type": "invoice",
"source_invoice_id": null,
"status": "approved",
"settlement_status": "scheduled",
"disputed": false,
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"currency": "eur",
"reference": "SUP-2026-0042",
"source_reference": "ERP-AP-7842",
"issue_date": "2026-06-17",
"received_at": "2026-06-18T09:00:00.000Z",
"due_date": "2026-07-17",
"scheduled_payment_date": "2026-07-15",
"paid_at": null
}Champs
| Champ | Type | Description |
|---|---|---|
id | string | Identifiant de la facture fournisseur (préfixe sinv_). |
object | string | Toujours "supplier_invoice". |
merchant_id | string | Marchand qui reçoit la facture. |
supplier_id | string | Fournisseur (cmp_…). |
supplier_contact_id | string | null | Contact fournisseur associé, si connu. |
type | enum | invoice ou credit_note. |
source_invoice_id | string | null | Facture fournisseur d’origine pour un avoir. |
status | enum | Cycle de vie : received, pending_approval, approved, cancelled. |
settlement_status | enum | Règlement : unpaid, scheduled, partially_paid, paid. |
disputed | boolean | Indique si la facture est actuellement contestée. |
amount_excluding_tax | integer | Montant HT en centimes. |
amount_tax | integer | Montant de taxe en centimes. |
amount_including_tax | integer | Montant TTC en centimes. |
currency | string | Devise ISO 4217 en minuscules. |
reference | string | null | Numéro de facture attribué par le fournisseur. |
source_reference | string | null | Référence dans votre système source. |
issue_date | date | null | Date d’émission indiquée par le fournisseur. |
received_at | datetime | null | Date de réception de la facture. |
due_date | date | null | Date d’échéance. |
approved_at | datetime | null | Date d’approbation. |
scheduled_payment_date | date | null | Date de paiement planifiée, le cas échéant. |
paid_at | datetime | null | Date de règlement complet, lorsqu’elle est connue. |
document_file | file | null | Document de facture joint. |
metadata | object | Map plate de scalaires `string | number | boolean`, selon la convention metadata de l’API. |
created_at | datetime | Date de création. |
updated_at | datetime | Date de dernière mise à jour. |
Cycle de vie
status répond uniquement à la question « où en est le document dans son traitement ? ». La planification ou l'exécution d'un paiement ne change pas cet axe.
| status | Description |
|---|---|
received | Facture reçue et enregistrée. Statut initial. |
pending_approval | Soumise au circuit d’approbation. |
approved | Approuvée pour traitement et paiement. |
cancelled | Annulée. Fin de vie du document. |
Règlement
settlement_status suit séparément l'avancement du paiement. La valeurscheduled appartient à cet axe : elle indique qu'un décaissement est planifié, sans faire de la planification une étape du cycle de vie de la facture.
| settlement_status | Description |
|---|---|
unpaid | Aucun règlement n’est encore engagé sur la facture. |
scheduled | Un paiement fournisseur a été planifié pour cette facture. |
partially_paid | Une partie du montant a été réglée. |
paid | Le montant total a été réglé. |
Lorsqu'un paiement fournisseur est appliqué au document, le règlement progresse vers partially_paid ou paid selon le montant effectivement imputé.
Litiges
Le booléen disputed constitue un troisième axe indépendant. Ouvrir un litige ne remplace ni status ni settlement_status ; une facture peut par exemple rester approved tout en étant contestée.
POST /v1/supplier-invoices/sinv_4a7b/dispute
{}POST /v1/supplier-invoices/:id/resolve-dispute clôt le litige et remetdisputed à false. La requête précise si le cycle reprend en received ou approved.
Bons de commande
Une facture fournisseur peut être liée à un ou plusieurs bons de commande. Les relations sont consultables via GET /v1/supplier-invoices/:id/purchase-orderset modifiables via POST /v1/supplier-invoices/:id/purchase-order-links.
Les lignes peuvent également référencer une ligne de bon de commande avec purchase_order_line_item_id pour conserver un rapprochement ligne à ligne.
Actions métier
| Endpoint | Effet sur les axes |
|---|---|
POST /v1/supplier-invoices/:id/submit-for-approval | status : received → pending_approval |
POST /v1/supplier-invoices/:id/approve | status : received/pending_approval → approved |
POST /v1/supplier-invoices/:id/schedule | settlement_status → scheduled ; status reste approved |
POST /v1/supplier-invoices/:id/dispute | disputed → true ; status et settlement_status restent indépendants |
POST /v1/supplier-invoices/:id/resolve-dispute | disputed → false ; le cycle reprend en received ou approved |
POST /v1/supplier-invoices/:id/cancel | status → cancelled |
Événements
| Événement | Déclencheur |
|---|---|
supplier_invoice.received | Une facture fournisseur vient d’être enregistrée. |
supplier_invoice.updated | La facture ou son cycle métier a été mis à jour. |
supplier_invoice.approved | La facture vient d’être approuvée. |
supplier_invoice.partially_paid | Le règlement devient partiel. |
supplier_invoice.paid | La facture est entièrement réglée. |
supplier_invoice.overdue | La facture est échue et reste ouverte. |
supplier_invoice.disputed | Un litige est ouvert sur la facture. |
supplier_invoice.cancelled | La facture est annulée. |