FG.AI WMS — Developer integration¶
The FG.AI WMS public REST surface for developers. This site documents the two integration paths into FG.AI WMS:
The ingest API — used to push master data, documents, and inventory from an upstream system into FG.AI WMS so FG.AI’s planner can take over.
The outbound webhooks — emitted by FG.AI WMS so the upstream system can mirror FG.AI’s view of the world.
The audience is developers building any system that needs to feed FG.AI WMS or consume its state changes. The most common consumers are FlexSync per-vendor connectors (per WMS ADR-0024) and direct integrations from modern third-party WMS that prefer to call FG.AI’s API themselves instead of going through FlexSync.
What this is not¶
This is not the WMS↔WES contract. If you want a third-party WMS to keep its own planner and have FG.AI WES execute downstream, you want wes-contract instead. The two contracts are mutually exclusive per warehouse — pick one.
The two paths cover different ownership models:
Aspect |
wes-contract |
WMS ingest API (this site) |
|---|---|---|
Whose planner runs? |
The upstream’s |
FG.AI’s |
What is the upstream WMS? |
The planner — owns documents, inventory, master data |
A data source — pushes its state to FG.AI; FG.AI normalizes and takes over |
Who hosts the REST server? |
The upstream hosts realtime + confirmation |
FG.AI hosts everything; the upstream is a client |
Right tool when… |
The upstream’s planner intelligence is trusted and reused |
The upstream is legacy / API-poor / fixed-feature, and you want FG.AI’s planner to take over |
What FG.AI imports¶
Three classes of entity:
Class |
Endpoints |
Cadence |
|---|---|---|
Master data |
|
Slow-changing. Sync at onboarding, then on every change. |
Documents |
|
Per-event. Push as the upstream creates or updates them. |
Inventory |
|
Snapshot at cutover; deltas during overlap; quiet after FG.AI is authoritative. |
Once FG.AI has accepted the data, FG.AI’s planner runs against it: wave / waveless release, slotting, cartonization, dispatch to FG.AI WES. The upstream WMS is no longer in the planning loop.
Architecture at a glance¶
┌─────────────────────────────────────┐
│ Upstream system — DATA SOURCE │
│ ─ system of entry for customer ops │
│ ─ owns source-side documents + │
│ master data + inventory baseline │
└─────────────────────────────────────┘
│
│ ingest (master / documents / inventory)
▼
┌─────────────────────────────────────┐
│ FG.AI WMS — PLANNING + EXECUTION │
│ ─ normalizes incoming entities │
│ ─ assigns FG.AI internal_id │
│ ─ runs the FG.AI planner │
│ ─ dispatches to FG.AI WES │
│ ─ becomes authoritative inventory │
└─────────────────────────────────────┘
│
│ callbacks: document.state-changed
│ inventory.adjusted
│ master.normalization-conflict
▼
┌─────────────────────────────────────┐
│ Upstream system — RECEIVES │
│ state + adjustment callbacks │
└─────────────────────────────────────┘
The upstream stays the customer-visible system of entry (where users create POs, SOs, work orders). FG.AI does not replace it. FG.AI replaces the planning + execution loop behind it.
Topics¶
Versioning¶
URL-segment versioning. The base path is /wms-ingest/v1. Future breaking changes ship as /wms-ingest/v2. Minor versions add optional fields; patch versions are bug-fixes and clarifications.
Pin your generated clients to a specific minor version. “Latest” makes CI non-deterministic.