wes-contract — Developer integration¶
wes-contract is the planner-to-executor REST contract on the FlexGalaxy.AI platform. It lets any planning system — a WMS, OMS, or ERP — hand work off to any Warehouse Execution System (WES) and receive real-time + reconciled feedback from it.
This site is for developers building either side of the contract: a planner adopting it to dispatch work, or an executor adopting it to receive work and report results. Both sides are documented identically; the contract is symmetric in framing and asymmetric only where the underlying flow is.
The contract is vendor-agnostic. FG.AI WMS is the reference planner implementation; FG.AI WES is the reference executor implementation. Third-party planners and executors are first-class consumers — the same OpenAPI 3.1 document, the same message shapes, the same authentication scheme.
Roles¶
A wes-contract deployment has exactly two roles per warehouse:
Role |
What it owns |
|---|---|
Planner |
Documents (PR / PO / SO / Receiver / Shipper / WorkOrder / TransferOrder), master data, the inventory ledger, the movement log, the accounting close. |
Executor |
Who does what when on the floor: task sequencing, dispatch to humans / robots / AS/RS / conveyors / sortation, real-time capacity, simulation, optimization. |
A planner stays in control of what happens; an executor decides how it happens. The contract is the seam between them.
Architecture at a glance¶
┌──────────────────────────────────────┐
│ Planner │
│ documents, inventory, master data │
│ realtime + confirmation servers │
│ dispatch publisher │
│ reconciler │
└──────────────────────────────────────┘
▲ │
realtime + │ │ dispatch
confirmation │ │ (planner → executor;
(executor → planner) │ │ webhook / Kafka / pull)
│ ▼
┌──────────────────────────────────────┐
│ Executor │
│ orchestrates workers, robots, MHE │
│ posts realtime as work completes │
│ posts confirmation at window close │
└──────────────────────────────────────┘
The three endpoint families¶
The contract is intentionally not a single endpoint with a mode flag. It is three families with three different consistency models. Conflating them is the most common implementation mistake.
Family |
Direction |
Consistency |
Detail |
|---|---|---|---|
planner → executor |
At-least-once, per-warehouse ordered |
Work-release events as documents transition to executable state. |
|
executor → planner |
Best-effort, sub-second to seconds latency |
Continuous floor feedback: movements, exceptions, work-status, capacity. |
|
executor → planner |
Authoritative, per-shift / per-window |
Cumulative window totals, cycle counts, inventory snapshots. The accounting path. |
Confirmation is also the trigger for reconciliation — the planner compares the realtime stream sum against the confirmation summary for the same window and either marks the window RECONCILED or flags a DISCREPANCY for supervisor resolution.
Topics¶
Versioning¶
Semver. The contract major version is in the URL (/wes/v1/); breaking changes ship as /wes/v2/. Minor versions add optional fields only. Pin to a specific version (e.g. wes-contract:1.2.0) and upgrade deliberately.
Both the REST realization (v1.2 — current) and the gRPC realization (v1.3, additive — see About gRPC) track major versions in lockstep. The gRPC path is optional; REST is the universal baseline.