Bon de commande fournisseur (`purchase_order`)

Un purchase_order est un bon de commande émis par un marchand à destination d'un fournisseur. Il porte les montants, les lignes d'article et le statut d'avancement, et sert de point d'ancrage pour les factures fournisseur reçues en retour.

Rôle

Le bon de commande est l'objet d'entrée du cycle Accounts Payable (AP). Il formalise l'engagement du marchand envers un fournisseur avant que les marchandises ou services ne soient livrés et facturés. Son cycle de vie suit le parcours opérationnel : rédaction → approbation interne → envoi au fournisseur → réception → clôture.

Les factures fournisseur reçues peuvent être créées directement depuis le bon de commande ou liées a posteriori. Les lignes de facture peuvent référencer des lignes du bon de commande pour un rapprochement précis.

Le fournisseur est une company de la plateforme — les mêmes objets servent pour les acheteurs (flux AR) et les fournisseurs (flux AP).

Identifiant et structure

Chaque bon de commande porte un identifiant stable préfixé par po_.

JSON

"purchase_order":{22 items"object":"purchase_order"
"id":"po_3c8f1a9b2d4e7f6a"
"merchant_id":"mer_1a2b3c4d5e6f7a8b"
"supplier_id":"cmp_9b2e4f1a7c3d8e5f"
"supplier_contact_id":null
"source_reference":"erp::tenant-42::purchase_order::158"
"reference":"PO-2026-00158"
"supplier_order_reference":"CONF-SUP-8741"
"delivery_details":{1 item"address":{...}4 items
}
"status":"sent"
"currency":"eur"
"amount_excluding_tax":250000
"amount_tax":50000
"amount_including_tax":300000
"metadata":{}0 items
"approved_at":"2026-06-17T09:00:00.000Z"
"sent_at":"2026-06-17T10:30:00.000Z"
"cancelled_at":null
"fulfilled_at":null
"completed_at":null
"created_at":"2026-06-17T08:45:00.000Z"
"updated_at":"2026-06-17T10:30:00.000Z"
}

{
  "object": "purchase_order",
  "id": "po_3c8f1a9b2d4e7f6a",
  "merchant_id": "mer_1a2b3c4d5e6f7a8b",
  "supplier_id": "cmp_9b2e4f1a7c3d8e5f",
  "supplier_contact_id": null,
  "source_reference": "erp::tenant-42::purchase_order::158",
  "reference": "PO-2026-00158",
  "supplier_order_reference": "CONF-SUP-8741",
  "delivery_details": {
    "address": {
      "line1": "4 rue des Ateliers",
      "city": "Lyon",
      "postal_code": "69007",
      "country": "FR"
    }
  },
  "status": "sent",
  "currency": "eur",
  "amount_excluding_tax": 250000,
  "amount_tax": 50000,
  "amount_including_tax": 300000,
  "metadata": {},
  "approved_at": "2026-06-17T09:00:00.000Z",
  "sent_at": "2026-06-17T10:30:00.000Z",
  "cancelled_at": null,
  "fulfilled_at": null,
  "completed_at": null,
  "created_at": "2026-06-17T08:45:00.000Z",
  "updated_at": "2026-06-17T10:30:00.000Z"
}

Champs

Champ	Type	Description
`id`	`string`	Identifiant du bon de commande (préfixe po_).
`object`	`string`	Toujours "purchase_order".
`merchant_id`	`string`	Marchand émetteur.
`supplier_id`	`string`	Fournisseur destinataire (cmp_…). Requis à la création.
`supplier_contact_id`	`string \| null`	Contact fournisseur (ctc_…). Optionnel.
`source_reference`	`string \| null`	Identité ou provenance du bon dans votre système source.
`reference`	`string \| null`	Numéro métier du bon de commande attribué par le marchand.
`supplier_order_reference`	`string \| null`	Numéro de commande ou confirmation attribué par le fournisseur en réponse au bon.
`delivery_details`	`object \| null`	Informations ouvertes de livraison ou destination utiles au flux P2P.
`status`	`enum`	Statut du bon de commande : draft, approved, sent, cancelled, fulfilled, completed.
`currency`	`string`	Code devise ISO 4217 en minuscules (ex. eur).
`amount_excluding_tax`	`integer`	Montant HT en centimes.
`amount_tax`	`integer`	Montant de la taxe en centimes.
`amount_including_tax`	`integer`	Montant TTC en centimes. Contrainte : HT + taxe = TTC.
`metadata`	`object`	Map plate de scalaires `string \| number \| boolean`, selon la convention metadata de l’API.
`approved_at`	`datetime \| null`	Horodatage d'approbation interne.
`sent_at`	`datetime \| null`	Horodatage d'envoi au fournisseur.
`cancelled_at`	`datetime \| null`	Horodatage d'annulation.
`fulfilled_at`	`datetime \| null`	Horodatage de réception des marchandises ou services.
`completed_at`	`datetime \| null`	Horodatage de clôture comptable.
`created_at`	`datetime`	Date de création.
`updated_at`	`datetime`	Date de dernière mise à jour.

Cycle de vie

Le bon de commande suit un cycle linéaire depuis la rédaction jusqu'à la clôture. Seul le statut draft est modifiable.

Statuts

Statut	Description	Final
`draft`	Brouillon. Modifiable (montants, lignes, contact). Seul statut initial possible.	non
`approved`	Approuvé en interne. Non modifiable.	non
`sent`	Envoyé au fournisseur.	non
`fulfilled`	Marchandises ou services reçus.	non
`completed`	Clôturé — traitement comptable terminé.	oui
`cancelled`	Annulé. Accessible depuis draft, approved ou sent.	oui

Transitions

Action	Endpoint	Depuis	Vers	Timestamp renseigné
Approuver	`POST /:id/approve`	`draft`	`approved`	`approved_at`
Envoyer	`POST /:id/send`	`approved`	`sent`	`sent_at`
Réceptionner	`POST /:id/fulfill`	`approved, sent`	`fulfilled`	`fulfilled_at`
Clôturer	`POST /:id/complete`	`fulfilled`	`completed`	`completed_at`
Annuler	`POST /:id/cancel`	`draft, approved, sent`	`cancelled`	`cancelled_at`

Timestamps cumulatifs Les timestamps de progression sont cumulatifs : passer directement de approved à fulfilled renseigne également sent_at. Passer de draft directement à fulfilled renseigne approved_at et sent_atau même horodatage. De même, complete renseigne fulfilled_at s'il était encore null.

Lignes d'article

Les lignes décrivent le détail des produits ou services commandés. Elles peuvent être fournies à la création et remplacées atomiquement lors d'une mise à jour (tant que le bon de commande est en draft). Elles sont accessibles via GET /v1/purchase-orders/:id/line-items.

Champ	Type	Description
`id`	`string`	Identifiant de la ligne (préfixe li_).
`product_name`	`string`	Nom du produit ou service. Requis.
`description`	`string \| null`	Description complémentaire.
`product_reference`	`string \| null`	Référence produit dans votre catalogue.
`quantity`	`integer`	Quantité (entier positif).
`unit_amount_excluding_tax`	`integer`	Prix unitaire HT en centimes.
`unit_amount_including_tax`	`integer`	Prix unitaire TTC en centimes.
`amount_excluding_tax`	`integer`	Montant ligne HT (= unit_ht × quantity si absent).
`amount_tax`	`integer`	Montant taxe de la ligne.
`amount_including_tax`	`integer`	Montant ligne TTC (= unit_ttc × quantity si absent).
`currency`	`string`	Devise. Doit correspondre à la devise du bon de commande.

Si amount_excluding_tax ou amount_including_tax ne sont pas fournis, ils sont calculés automatiquement (unit_amount × quantity). La contrainte HT + taxe = TTC s'applique à chaque ligne.

Les lignes de facture fournisseur peuvent référencer une ligne de bon de commande via purchase_order_line_item_id pour un rapprochement ligne à ligne.

Factures fournisseur

Un bon de commande peut être associé à une ou plusieurs factures fournisseur via une relation plusieurs-à-plusieurs. Une facture peut aussi être liée à plusieurs bons de commande (livraisons partielles sur plusieurs PO).

Créer une facture depuis le bon de commande

POST /v1/purchase-orders/:id/supplier-invoices crée une facture fournisseur héritant automatiquement de la devise du bon de commande et établissant le lien entre les deux objets.

HTTP

POST /v1/purchase-orders/po_3c8f/supplier-invoices

{8 items"type":"invoice"
"amount_excluding_tax":250000
"amount_tax":50000
"amount_including_tax":300000
"reference":"FAC-FOURNISSEUR-2026-0042"
"issue_date":"2026-06-17"
"received_at":"2026-06-18T09:00:00.000Z"
"due_date":"2026-07-17"
}

{
  "type": "invoice",
  "amount_excluding_tax": 250000,
  "amount_tax": 50000,
  "amount_including_tax": 300000,
  "reference": "FAC-FOURNISSEUR-2026-0042",
  "issue_date": "2026-06-17",
  "received_at": "2026-06-18T09:00:00.000Z",
  "due_date": "2026-07-17"
}

La facture est créée avec status = received, settlement_status = unpaid et disputed = false. Ces trois informations évoluent indépendamment : réception/approbation, règlement et litige.

Lier des factures existantes

Endpoint	Effet
`GET /v1/purchase-orders/:id/supplier-invoices`	Liste les factures fournisseur liées.
`POST /v1/purchase-orders/:id/supplier-invoice-links`	Remplace atomiquement l'ensemble des liens. Envoie `{ "supplier_invoice_ids": ["si_…"] }`.
`DELETE /v1/purchase-orders/:id/supplier-invoice-links/:supplier_invoice_id`	Retire un lien sans toucher aux autres.

Les liens sont également gérables depuis la facture fournisseur via POST /v1/supplier-invoices/:id/purchase-order-links.

Dans les processus

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

Le bon de commande peut être passé comme entrée typée dans un processus — il est récupérable via le helper générique fetch_purchase_order à partir de son identifiant.

Dans un flux AP typique, le processus est déclenché par un événement de réception (purchase_order.fulfilled ou supplier_invoice.received), puis orchestre l'approbation de la facture et le paiement fournisseur.

Événements

Événement	Déclencheur
`purchase_order.created`	Bon de commande créé.
`purchase_order.updated`	Bon de commande mis à jour (montants, lignes, contact).
`purchase_order.approved`	Passé à approved.
`purchase_order.sent`	Passé à sent.
`purchase_order.fulfilled`	Passé à fulfilled — réception confirmée.
`purchase_order.completed`	Passé à completed — clôture comptable.
`purchase_order.cancelled`	Passé à cancelled.

Les événements de transition incluent le statut final dans leur payload. Le payload contient également supplier_id pour permettre de filtrer les événements par fournisseur dans un processus.

Suivant →Facture fournisseur

Bon de commande fournisseur (purchase_order)

Rôle

Identifiant et structure

Champs

Cycle de vie

Statuts

Transitions

Lignes d'article

Factures fournisseur

Créer une facture depuis le bon de commande

Lier des factures existantes

Dans les processus

Événements

Bon de commande fournisseur (`purchase_order`)