OBAPI OBAPI

Workflows & Relationships

Understanding how OBAPI objects relate to each other and how documents flow through their lifecycle.

Commercial document flow

The core B2B exchange follows a predictable pipeline:

graph LR P[Proposal] -->|signed| O[Order] O -->|fulfilled| S[Shipment] O -->|billed| I[Invoice] I -->|correction| CN[Credit Note] I -->|PDF| D[Download] O -->|PDF| D P -->|PDF| D S -->|PDF| D CN -->|PDF| D

A typical flow:

  1. Proposal (quotation) is created and sent to the customer
  2. Customer signs the proposal -- status changes to signed
  3. An Order is created from the proposal
  4. Goods are shipped via a Shipment
  5. An Invoice is generated for the order
  6. If needed, a Credit Note corrects the invoice
  7. Any document can be Downloaded as PDF

Not every step is mandatory. An invoice can exist without a prior proposal. A shipment can exist without a formal order.

Supplier-side mirror

The purchasing flow mirrors the sales flow:

graph LR SP[Supplier Proposal] -->|accepted| SO[Supplier Order] SO -->|delivered| R[Reception] SO -->|billed| SI[Supplier Invoice]

Invoice lifecycle

stateDiagram-v2 [*] --> draft draft --> validated : validate validated --> paid : payment received validated --> abandoned : write off paid --> [*] abandoned --> [*]
Status Meaning
draft Invoice created, not yet finalized
validated Finalized, sent to customer, awaiting payment
paid Fully paid
abandoned Written off, no longer expected to be paid

Order lifecycle

stateDiagram-v2 [*] --> draft draft --> validated : validate validated --> in_progress : start processing in_progress --> delivered : all shipped validated --> cancelled : cancel in_progress --> cancelled : cancel delivered --> [*] cancelled --> [*]

Proposal lifecycle

stateDiagram-v2 [*] --> draft draft --> validated : validate & send validated --> signed : customer accepts validated --> refused : customer declines signed --> billed : invoice created billed --> [*] refused --> [*]

Supplier order lifecycle

stateDiagram-v2 [*] --> draft draft --> validated : validate validated --> approved : approve approved --> ordered : send to supplier ordered --> received_partially : partial delivery ordered --> received_completely : full delivery received_partially --> received_completely : remaining delivered validated --> cancelled : cancel approved --> refused : refuse received_completely --> [*] cancelled --> [*] refused --> [*]

Shipment lifecycle

stateDiagram-v2 [*] --> draft draft --> validated : ship validated --> closed : delivered closed --> [*]

Entity relationships

erDiagram THIRDPARTY ||--o{ CONTACT : "has" THIRDPARTY ||--o{ PROPOSAL : "receives" THIRDPARTY ||--o{ ORDER : "places" THIRDPARTY ||--o{ INVOICE : "is billed" PROPOSAL ||--o| ORDER : "becomes" ORDER ||--o{ SHIPMENT : "fulfilled by" ORDER ||--o{ INVOICE : "billed as" INVOICE ||--o{ CREDITNOTE : "corrected by" CONTRACT ||--o{ INTERVENTION : "serviced by" PROJECT ||--o{ TASK : "contains" BOM ||--o{ MANUFACTURING_ORDER : "produces"

How to navigate between entities

From To How
Order Shipments List shipments, filter by order_ref matching the order's ref
Order Invoice List invoices, the invoice may reference the order via its lines
Proposal Order When a proposal is signed, the resulting order is created
Invoice Credit Note A credit note has related_invoice_ref pointing to the original invoice
Contract Interventions An intervention has contract_ref linking to the contract
Project Tasks GET /obapi/v1/projects/{id} includes tasks array, or use GET /obapi/v1/tasks?project_id={id}
Supplier Order Reception A reception has origin_type: "supplier_order" and origin_id linking to the order
BOM Manufacturing Order A manufacturing order has bom_ref linking to the BOM
Expense Report Project Each expense line may have a project_ref

Download any document

The Download endpoint is a universal gateway to PDF files:

GET /obapi/v1/download/{id}?type={type}

Supported types: invoice, creditnote, order, proposal, shipment, supplier-proposal, supplier-order, supplier-invoice, reception, contract, intervention, expense-report.