Side-partner adapter API

This page describes the generic Path C adapter pattern for side partners whose WMS owns the upstream business records but wants FG.AI to execute warehouse work. It is the partner-facing version of the RTA model: the partner calls a FG.AI-hosted adapter API, and the adapter translates into FG.AI canonical WMS/WES internals.

Use this pattern when all of these are true:

• The partner can call REST APIs we provide.

• The partner will push master data and executable documents to FG.AI.

• FG.AI will call the partner’s documented APIs for completion or inventory updates.

• The partner-specific protocol should not leak into core WMS service contracts.

If the partner wants to keep its own planner and drive a WES directly, use wes-contract instead. If the partner is a general connector candidate that should become a reusable product integration, use FlexSync when available.

Integration boundary

Partner WMS
  -> FG.AI side-partner adapter API
      -> FG.AI canonical WMS/WES internals

FG.AI side-partner adapter
  -> Partner documented APIs

The adapter is the only partner-specific boundary. It owns:

• inbound REST endpoints exposed to the partner;

• partner authentication, request validation, idempotency, and raw-request audit;

• field mapping into FG.AI canonical SKU, location, work-order, label, and cancellation concepts;

• bridge-mode staging for UAT when real downstream services are not ready;

• outbound partner calls for work completion and inventory transitions;

• retries, token refresh, dead-letter handling, and partner-specific response interpretation.

Core WMS services should receive canonical commands/events, not partner-shaped payloads.

OpenAPI

The reusable adapter contract is published as:

Artifact	Link
Source	openapi/wms-rta-adapter/v1/wms-rta-adapter.yaml
Redoc portal	Open adapter API portal ->

The first concrete implementation is wms-rta-adapter. Other side partners with the same topology should clone the resource model and specialize only partner-specific names, examples, and outbound callbacks.

Inbound resources

Base path:

/wms-rta/v1

The generic resource set is:

Method	Path	Purpose
POST	/skus	Push SKU master data.
POST	/locations	Push warehouse, zone, bin, staging, dock, or workstation master data.
POST	/work-orders	Push work orders and optional pre-pick label bindings.
POST	/work-orders/{woCode}/cancel	Cancel a previously pushed work order.
GET	/requests/{requestId}	Inspect durable request status and per-item results.
GET	/health	Liveness probe.

Every write carries:

Field	Meaning
requestId	Caller-supplied UUID idempotency key.
siteCode	Partner site identifier.
warehouseCode	Partner warehouse identifier when the request is warehouse-scoped.
items[]	Batch of partner records for the resource.

The adapter returns 202 Accepted for accepted write batches. The request may be staged in bridge mode or forwarded to canonical WMS services depending on runtime mode.

Work orders and labels

Work orders may carry labelBindings[]. This supports partners whose WMS owns parcel labels and prints them before picking starts.

The adapter treats labels as opaque identifiers:

• Partner owns label content, carrier integration, label format, and print timing.

• Adapter stores the label binding and maps it to canonical execution label bindings.

• FG.AI WES can use scanned labels for scan-to-claim and container/task binding.

• FG.AI does not generate, parse, or print the partner’s parcel labels.

For side partners like RTA, printMode is PRE_PICK. Internally the adapter maps this to the WES-contract pre-pick label binding model.

Cancellation

Cancellation is not a delete. The adapter maps cancellation requests to canonical FG.AI cancellation semantics and returns one of four outcomes:

Outcome	Meaning
ACCEPTED	All bound work was pre-custody and cancellation applied cleanly.
ACCEPTED_PARTIAL	Some work cancelled; some was already too late.
TOO_LATE	Execution passed the cancellation boundary.
UNKNOWN	State could not be determined; manual reconciliation required.

For work orders, “too late” means the output reached the declared destination/custody location. Work in progress at an intermediate station can still be cancelled and compensated.

If labels were bound to the work order, the cancellation response may also report:

• voidedLabels[]

• tooLateLabels[]

• unknownLabels[]

The partner remains responsible for any carrier-side or upstream business reversal when a label is already physically used or the cancellation is too late.

Authentication recommendation

For dev/UAT:

• TLS;

• bearer API key per partner site;

• IP allowlist where the partner provides stable egress CIDRs;

• per-site rate limit;

• idempotency via requestId.

For prod-intl:

• mTLS client certificate for partner edge identity;

• optional bearer API key for app-level rotation and site scoping;

• same requestId idempotency behavior.

Do not enable prod-cn until explicitly authorized for that partner and environment.

Bridge mode

Bridge mode exists to unblock UAT before all real WMS/WES internals are ready.

In bridge mode the adapter:

• accepts real partner requests;

• validates and persists raw plus normalized payloads;

• exposes request status for audit;

• stages accepted SKU/location/work-order data;

• uses staged data to emit synthetic outbound execution events;

• posts completion and inventory transition payloads to the partner’s real UAT endpoints.

Bridge mode must be dev-intl only. It must not be enabled for production.

Suggested runtime flags:

WMS_RTA_BRIDGE_MODE=true
WMS_RTA_SYNTHETIC_EVENTS_ENABLED=true

CI and deployment rules should reject these flags outside dev-intl.

Retirement criteria

Bridge mode retires in pieces:

Bridge behavior	Retire when
Staging as source of truth	Real SKU/location and work-order ingestion paths are live and adapter can forward to them.
Synthetic outbound events	Real movement, work-order lifecycle, and pick-completion events are available and consumed by the adapter.
Bridge-only admin views	Normal integration audit logs cover raw request, normalized command, outbound attempt, and DLT state.
Dev-only auth shortcut	Production mTLS/API-key onboarding is complete and tested.

The adapter itself survives. Only the UAT staging and synthetic-event shortcuts retire.

Implementation plan

1. Publish the adapter OpenAPI and generate partner-facing Redoc.

2. Implement inbound controllers for SKUs, locations, work orders, and cancellation.

3. Add request audit, idempotency, validation, and per-item result storage.

4. Add bridge staging tables and status lookup.

5. Add canonical translation from staged records to FG.AI SKU/location/work-order commands.

6. Add pre-pick label binding translation.

7. Add cancellation translation and outcome mapping.

8. Add synthetic event generator for UAT.

9. Add outbound partner client framework: auth, retry, DLT, response classification.

10. Retire bridge mode when real WMS/WES event sources are ready.

Related

• Side-partner architecture

• Side-partner interface mapping

• Side-partner onboarding

• OpenAPI reference

• wes-contract cancellation guide

• wes-contract label printing guide