Extended document types¶
FG.AI WMS uses a deliberately generic MES vocabulary per WMS ADR-0008, so the same data model that handles light VAS today extends to manufacturing later without rename or migration. This page documents the nine document types the ingest API accepts in v1, the chain service each routes to internally, and what changes from caller perspective when the per-chain-service fan-out (WMS ADR-0025) is invisible.
The nine document types¶
Endpoint |
Document type |
Chain service (internal) |
Typical use case |
|---|---|---|---|
|
|
|
Internal request that becomes a PO once approved upstream. |
|
|
|
Order to vendor; drives expected inbound. |
|
|
|
Customer order; drives outbound flow. |
|
|
|
Expected inbound shipment from a PO or ASN; closes with putaway. |
|
|
|
Outbound shipment; closes with carrier handoff. |
|
|
|
Generic execute-a-Routing-against-a-BOM-to-produce-N-units document. v1 use cases: assembly, light manufacturing. |
|
|
|
Value-added services (gift wrap, labeling, kitting, custom packaging) attached to an outbound Shipper. |
|
|
|
Refurbishment that may produce a refurbished SKU variant. v1 use case: returns-to-resaleable conversion. |
|
|
|
Inter-warehouse or cross-zone movement; orchestrated as a saga per WMS ADR-0006. |
The per-chain fan-out is invisible to ingest callers: you POST to the endpoint that matches the document type, and FG.AI routes it internally. The chain-service identity surfaces in the chain_service field of document.state-changed webhooks for callers that want to subscribe to chain-specific events.
WorkOrder — the generic MES anchor¶
The WorkOrder document type is the architectural anchor of WMS ADR-0008. Its shape is intentionally manufacturing-shaped even when the workload is light VAS:
POST /wms-ingest/v1/documents/work-orders?mode=upsert
{
"work_order": {
"source_id": "WO-2026-00100",
"consignor_id": "acme-corp",
"routing_ref": "RT-ACME-PACK-STD", ◄── reference to PSpec Routing
"bom_ref": "BOM-ACME-WIDGET-RED", ◄── reference to PSpec BOM (optional if Routing is purely transformative)
"target_sku_ref": "ACME-WIDGET-RED-GIFT",
"target_qty": 50,
"due_at": "2026-06-15T17:00:00Z",
"scheduled_window": {
"from": "2026-06-15T08:00:00Z",
"to": "2026-06-15T17:00:00Z"
}
}
}
routing_ref and bom_ref resolve against the PSpec sibling product (per WMS ADR-0026). FG.AI snapshots the recipe into the WorkOrder at creation time, computes estimates (expected duration, expected cost, expected component consumption), stores them, and reconciles actuals on close. The split is in WMS ADR-0028: WMS owns estimates; WES owns execution.
A v1 caller does not need to know which chain or recipe layer is involved. From the contract surface a WorkOrder is just a structured request: produce N of SKU X by deadline Y, optionally using these inputs.
VasOrder — light value-added services¶
A VasOrder is bound to an outbound Shipper. The vocabulary is shared with WorkOrder, but the document is fulfillment-scoped (the wrapped/labeled item still belongs to the Shipper). v1 use cases:
Gift wrap an outbound line item before pack-out
Apply a customer-branded label to a generic SKU before ship
Insert a gift card or marketing collateral into a carton
POST /wms-ingest/v1/documents/vas-orders?mode=upsert
{
"vas_order": {
"source_id": "VAS-2026-00500",
"consignor_id": "acme-corp",
"linked_shipper_ref": "SHIP-2026-00200", ◄── bound to outbound shipper
"linked_so_line_frns": [...],
"routing_ref": "RT-GIFT-WRAP-STD",
"operations": [
{ "op_code": "WRAP", "params": { "paper_sku": "WRAP-RED-XL" } },
{ "op_code": "INSERT", "params": { "card_sku": "CARD-VALENTINE-2026" } },
{ "op_code": "SEAL" }
],
"scheduled_window": { "from": "2026-06-15T08:00:00Z", "to": "2026-06-15T17:00:00Z" }
}
}
A VasOrder typically does not produce a new SKU; it records VAS state on the source Shipper line.
RefurbishOrder — production-flow refurbishment¶
A RefurbishOrder converts a returned or used unit into a resaleable variant. It is owned by production-service. Typical v1 use case: a customer return triggers a RefurbishOrder that converts the returned item back to A-stock, B-stock, or scrap.
POST /wms-ingest/v1/documents/refurbish-orders?mode=upsert
{
"refurbish_order": {
"source_id": "REF-2026-00012",
"consignor_id": "acme-corp",
"source_sku_ref": "ACME-WIDGET-RED",
"target_sku_ref": "ACME-WIDGET-RED-REFURB-A",
"source_qty": 4,
"routing_ref": "RT-WIDGET-REFURB-INSPECT",
"linked_customer_return_ref": "CR-2026-00088",
"scheduled_window": { "from": "2026-07-01T08:00:00Z", "to": "2026-07-01T12:00:00Z" }
}
}
The dedicated linked-CustomerReturn relationship activates with returns flow (v1.5 per WMS ADR-0030); the v1 schema accepts the field and stores it as a reference even when the CustomerReturn document type is not yet available.
TransferOrder — saga-orchestrated movements¶
A TransferOrder triggers the cross-warehouse transfer saga per WMS ADR-0006. The ingest API surface is straightforward; the saga internals (intent → outbound → carrier transit → inbound → reconciliation) are not exposed to callers. State changes surface through document.state-changed webhooks.
POST /wms-ingest/v1/documents/transfer-orders?mode=upsert
{
"transfer_order": {
"source_id": "XFR-2026-00099",
"consignor_id": "acme-corp",
"destination_consignor_id": "acme-corp",
"from_warehouse_ref": "wh-tokyo-01",
"to_warehouse_ref": "wh-osaka-02",
"lines": [
{ "sku_ref": "ACME-WIDGET-RED", "qty": 50, "uom_ref": "EA" }
],
"due_at": "2026-06-20T12:00:00Z"
}
}
Cross-consignor transfers require elevated 3PL admin permission per Consignor and 3PL.
Why this vocabulary, not domain-specific names¶
The decision in WMS ADR-0008 was to not name these documents VasTask, RefurbishJob, MfgOrder, etc. Domain-specific names would force a rename when the data model extended into manufacturing. Generic MES vocabulary (WorkOrder + Routing + BOM + Operation) gives the v1 light VAS workload exactly the same shape as a future full MES workload. Code, schema, APIs, and analytics queries all stay valid as the use case grows.
Cancellation¶
All nine types accept the same cancellation shape:
DELETE /wms-ingest/v1/documents/{source_id}?type=work_order
{
"cancelled_at": "2026-06-14T15:00:00Z",
"reason": "customer-cancelled",
"correlation_id": "..."
}
The downstream consequences vary by chain service and by document state at cancel time. See Errors for the failure modes and Webhooks for the state-changed events that result.