Entities and cadence¶

FG.AI WMS imports three classes of entity through this contract. Each has a different shape, a different cadence, and a different consequence of arriving late or wrong.

Master data¶

Master data describes the stable structural facts about a warehouse operation: what a SKU is, what units of measure it ships in, what a bin is, where parties (customers, suppliers, carriers) are located. It changes slowly and is referenced by every document and movement.

Endpoint	What it carries
`POST /wms-ingest/v1/master/uoms`	Units of measure (EA, KG, M, L, custom).
`POST /wms-ingest/v1/master/skus`	SKU catalog with descriptions, base UoM, lot/serial-tracking flags, hazmat class, temperature-controlled class.
`POST /wms-ingest/v1/master/boms`	Bills of materials for assembled / kitted / refurbished SKUs.
`POST /wms-ingest/v1/master/locations`	Warehouse / zone / bin hierarchy (`kind ∈ {WAREHOUSE, ZONE, BIN}`).
`POST /wms-ingest/v1/master/addresses`	Postal addresses for warehouses, customers, suppliers, and carriers.
`POST /wms-ingest/v1/master/lots`	Lot registrations for lot-tracked SKUs.
`POST /wms-ingest/v1/master/serials`	Serial registrations for serial-tracked SKUs.

Cadence: sync at onboarding (typically via ?mode=bulk), then push every change as it happens (?mode=upsert). Steady-state volume is tiny — typically dozens to hundreds of upserts per day per warehouse.

Consequences of arriving late or wrong: documents and inventory referencing missing master data are quarantined (see Normalization and quarantine). The most common rollout mistake is pushing documents before the master data that they depend on.

Documents¶

Documents are the events that drive work in a warehouse: purchase orders, sales orders, receivers, shippers, work orders, transfer orders. They have a lifecycle (open → released → in-progress → closed) and a fixed identity over that lifecycle.

Endpoint	Document type
`POST /wms-ingest/v1/documents/purchase-orders`	Purchase Order (`PR` / `PO`).
`POST /wms-ingest/v1/documents/sales-orders`	Sales Order (`SO`).
`POST /wms-ingest/v1/documents/receivers`	Receiver — expected inbound from a PO or ASN.
`POST /wms-ingest/v1/documents/shippers`	Shipper — outbound shipment.
`POST /wms-ingest/v1/documents/work-orders`	Work Order — production, assembly, refurbish.
`POST /wms-ingest/v1/documents/transfer-orders`	Transfer Order — inter-warehouse movement.
`DELETE /wms-ingest/v1/documents/{source_id}?type=…`	Cancel a document.

See WMS ADR-0008 for the generic MES vocabulary the document types share with WorkOrder semantics — this lets the same data model grow into manufacturing later without rename or migration.

Cadence: per-event. Push to FG.AI as the upstream creates or updates each document. A single warehouse may produce hundreds to low-thousands of document events per day.

Consequences of arriving late or wrong: a missing document is work the FG.AI planner cannot schedule. A document with bad master-data references is quarantined and surfaces in a supervisor queue rather than failing silently.

Inventory¶

Inventory is the truth state of what is on hand: quantities per (warehouse, sku, location) with optional lot or serial qualifiers.

Endpoint	What it carries
`POST /wms-ingest/v1/inventory/snapshot`	Full or partial point-in-time snapshot.
`POST /wms-ingest/v1/inventory/movements`	Delta movements between snapshots.

Cadence:

At onboarding cutover — one full snapshot per warehouse marks the baseline FG.AI takes over. Send scope=FULL after a clean operational cutoff (e.g. end of last shift before go-live).
During overlap — if the upstream WMS keeps running for a transition period, push deltas via /inventory/movements so FG.AI’s view stays in sync. Tag each movement with correlation_id for idempotency.
After FG.AI is authoritative — inventory writes flow through FG.AI WES → FG.AI WMS, not through this contract. The upstream stops pushing inventory. It may continue receiving inventory.adjusted webhooks if it wants to mirror FG.AI’s state back into its own system.

Consequences of arriving late or wrong: the FG.AI planner schedules against the wrong stock position. This is the worst class of integration bug because it manifests as physical short-picks on the floor. Always verify the cutover snapshot is correct before flipping FG.AI to authoritative.

Cadence summary¶

Onboarding ──► bulk master ──► bulk inventory snapshot ──► open documents
                                                                 │
                                                                 ▼
Steady-state ──► trickle upserts (master + documents) ──► FG.AI planner active
                                                                 │
                                                                 ▼
Overlap (optional) ──► inventory deltas during transition
                                                                 │
                                                                 ▼
Post-cutover ──► FG.AI authoritative; only document upserts continue;
                 inventory writes flow through FG.AI WES

Identity convention¶

Every entity carries a partner-supplied source_id — the upstream’s natural key. On first acceptance, FG.AI assigns a stable internal_id. Subsequent upserts with the same (partner_id, source_id) mutate the same FG.AI entity. See Identity mapping for the full rules.