Entities and cadence¶

FG.AI WMS imports three classes of entity through this contract — master data, documents, inventory. Each has a different shape, a different cadence, and a different consequence of arriving late or wrong. All three classes are scoped by consignor_id per WMS ADR-0041 and ADR-0044; see Consignor and 3PL for the contract surface.

Master data¶

Master data describes the stable structural facts about a warehouse operation: who the consignors are, 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/consignors`	Consignor (goods owner) entities for 3PL operations. Required before consignor-scoped documents are accepted; see Consignor and 3PL.
`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, `consignor_id`, `track_by` mode (`NONE` / `LOT` / `SERIAL` / `LOT_AND_SERIAL` — see Lot tracking), `hazmat_profile` + `temperature_profile` JSONB attributes (see Hazmat and temperature).
`POST /wms-ingest/v1/master/boms`	Bills of materials for assembled / kitted / refurbished SKUs (see WMS ADR-0042 for the three kitting patterns).
`POST /wms-ingest/v1/master/locations`	Warehouse / zone / bin hierarchy (`kind ∈ {WAREHOUSE, ZONE, BIN}`); zones carry `hazmat_classes_allowed` + `temperature_range_celsius` per WMS ADR-0034.
`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. v1 schema accepts these; behavior activates in v1.6 per WMS ADR-0033.
`POST /wms-ingest/v1/master/serials`	Serial registrations for serial-tracked SKUs. v1 schema-only; activates in v2.

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`). Carries `fulfillment_mode` for drop-ship support (see Drop-ship).
`POST /wms-ingest/v1/documents/sales-orders`	Sales Order (`SO`). Per-line `fulfillment_mode` distinguishes from-stock vs. drop-ship vs. cross-dock.
`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 — generic MES production / assembly per WMS ADR-0008; see Extended document types.
`POST /wms-ingest/v1/documents/vas-orders`	VAS Order — gift wrap, labeling, custom packaging; bound to an outbound Shipper.
`POST /wms-ingest/v1/documents/refurbish-orders`	Refurbish Order — refurbishment that may produce a refurbished SKU variant; per WMS ADR-0025 fan-out, owned by `production-service`.
`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. The split into VasOrder + RefurbishOrder is the 2026-05-24 amendment that aligned the document set with the chain-service fan-out from WMS ADR-0025. From this contract’s perspective there is still one ingest endpoint per document type; internally FG.AI routes the upsert to the correct chain service (procurement / fulfillment / production / transfer).

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.