Side-partner onboarding¶

This page describes the onboarding sequence for a Path C integration: what you (the partner) need to provide and do, what FG.AI does in parallel, and how the integration goes from contract-signature to first production POST.

For the runtime architecture you are integrating with, see side-partner-architecture. For the mapping patterns, see side-partner-interface-mapping. For day-2 operations, see side-partner-operations.

Before onboarding starts¶

Confirm these are true before any engineering work begins:

A Path C engagement agreement is signed, including the contractual retirement clause (you onboard as a FlexSync connector when FlexSync v1 GA’s; the per-partner adapter is then decommissioned).
The MAX_SIDE_PARTNERS=2 budget has room. FG.AI enforces a hard cap on simultaneous Path C partners. If the cap is full, your onboarding waits for FlexSync v1 GA.
A primary integration owner is named on each side. FG.AI has a dedicated partner-engineering contact; you should have an equivalent.

If any of these are missing, the conversation routes back to product/sales before any engineering provisioning happens.

What FG.AI needs from you¶

Item	Why FG.AI needs it	When
Your `/authenticate` endpoint URL per environment (your dev / uat / prod tiers — your vocabulary; FG.AI side uses dev / prod-intl / prod-cn per shim § Per-environment hostnames)	FG.AI’s adapter authenticates outbound calls against your auth endpoint	Day 0 (pre-provisioning)
Per-environment `(partner_app_id, partner_app_secret)` you have provisioned for FG.AI	The credentials the adapter uses to authenticate	Day 0; via the agreed secure channel (NOT email plaintext; NOT Slack DM)
Your outbound endpoint URLs per environment (e.g., per-document postback URL, inventory transitions URL)	The destinations the adapter posts to	Day 0
Your partner-side tenant identifier (the value you expect to see in `siteName` or equivalent on every outbound payload)	The adapter sets this on every outbound; FG.AI records it in the `(partner, tenant)` binding row	Day 0; per FG.AI tenant in scope
Your partner-side warehouse-code(s) (e.g., your `epCode` field) per FG.AI warehouse in scope	The adapter looks up your warehouse code from partner-registry config when emitting outbound	Day 0; per warehouse
Your partner-side outbound IP allowlist (the addresses your `/authenticate` + outbound endpoints will be served from) per environment	FG.AI’s per-`(partner, tenant)` NetworkPolicy egress rule	Day 0; per environment
Your token TTL declaration	The adapter uses TTL minus a refresh-lead margin to schedule proactive refreshes	Day 0; can be defaulted to 120 minutes if your `/authenticate` returns a stated TTL
Your error code semantics	The adapter’s response handler maps your codes to retry / DLT / alert behaviors	Day 0; covers your “success”, “partial success”, “auth failed”, “param error”, “server error”, “rate-limit” classes
Your idempotency expectations on inbound	The adapter dedups on `(partner_id, source_event_id)`; if you have a stricter idempotency requirement, FG.AI captures it	Day 0
Your SKU code semantics + sample data	FG.AI maps your `productCode` → FG.AI’s `sku.code` via `partner_sku_mapping` (EDI-03 primitive)	Day 0 + ongoing; bulk-import tooling provided
Your location code semantics + sample data	Same as SKU; `partner_location_mapping`	Day 0 + ongoing
Per-environment routing constraints (any IP-segmentation, geo-restrictions, time-of-day restrictions on your inbound endpoint)	FG.AI’s NetworkPolicy + Resilience4j config	Day 0
Test data for smoke testing	FG.AI runs four smoke tests at the end of onboarding (token fetch + dry-run outbound for each of your endpoint types + authentication-recovery test)	Day 1

What FG.AI provides to you¶

Item	When you receive it
OpenAPI 3.1 specs you will adapt to	Day 0 for `wms-partners/v1/` (`openapi/wms-partners/v1/wms-partners.yaml`, published and stable). For `pim/v1/` + `wms/v1/work-orders` the Path-C-specific spec is forthcoming (openapi-reference); until it ships, the canonical `wms-ingest/v1` item schemas (`Sku`, `Location`, `WorkOrder`, etc., in `openapi/v1/wms-ingest.yaml`) are the wire-shape contract for `items[]`, and the running `wms-partners-bridge-service` is the source of truth for the request envelope + UAT response shape.
Partner credentials for FG.AI’s `wms-partners/v1/authenticate` (your `partner_app_id` + `partner_app_secret`)	Day 0; via the agreed secure channel
Per-environment hostnames (dev / prod-intl / prod-cn) for every Path C surface — see side-partner-shim § Per-environment hostnames for the canonical table	Day 0; confirm the target environment + partition before any client code is written
JWKS endpoint URL per partition (intl + CN) for local JWT verification — `https://api.flexgalaxy.{ai,com}/wms-partners/v1/.well-known/jwks.json` (dev: `https://dev-api.flexgalaxy.com/wms-partners/v1/.well-known/jwks.json`)	Day 0; document during onboarding so your JWT library is wired correctly
Documentation of FG.AI’s domain model: SKU semantics, work-order shape, movement enum values, location hierarchy	The `dev/` documentation set you are reading now
Your FG.AI tenant ID(s)	Day 1, after FG.AI provisions your tenant in DotID
Sample event payloads from `wms.{tenant}.` and `wes.{tenant}.confirmation.` topics for the events the adapter will translate	Day 1, after FG.AI provisions your tenant + before code generation
Bulk-import tooling for SKU + location mapping tables	Day 1
Smoke-test confirmation of the adapter against your dev environment	Day 1 end (typically by end of week 1)
Operational contact channel for incident escalation	Day 0

The onboarding sequence¶

Week 0          Week 1                          Week 2                       Week 3+
─────────────   ─────────────                   ─────────────                ─────────────
Sign agreement  Provision tenant + adapter      Smoke-test against           Production
                  scaffolding                     dev environment             handoff
                                                                              (you're live)

You             You: provide per-env            You: implement inbound       You: production
  provide:        credentials, sample data,       mapping; smoke-test on       monitoring + alert
  Day-0 list      and outbound endpoint URLs      your side via dev tier       on partner-side
  above           Provide your error code
                  semantics + idempotency
                  expectations

FG.AI           FG.AI: scaffolds adapter        FG.AI: end-to-end smoke      FG.AI: operations
                  from template + populates       test the adapter against     handoff;
                  partner-specific code;          dev; verifies token          on-call rotation
                  provisions tenant in DotID;     fetch + outbound POSTs +     added; partner-
                  registers partner row +         retry behavior + auth        registry binding
                  binding row in partner-         recovery                     smoke-test sign-off
                  registry; provisions
                  SecretsManager + IRSA +
                  Kafka ACLs

The typical onboarding takes 2-3 weeks from agreement signature to first production POST. Most of week 0-1 is provisioning + coordination; weeks 1-2 are the technical integration; week 3+ is steady-state operations.

Your side of the onboarding¶

Implement inbound adaptation¶

You write the code that translates your payload shape to FG.AI’s REST surface (per side-partner-interface-mapping §”Inbound mapping”). Concretely:

SKU master push: translate your SKU records to POST /pim/v1/skus payloads.
Location master push: translate your warehouse/zone/bin records to POST /pim/v1/locations payloads.
Work order push: translate your work orders + task lists to POST /wms/v1/work-orders payloads.
Inventory delta query: implement polling against GET /wms-partners/v1/inventory-delta with paginated cursor handling.

You authenticate inbound writes per the stage-specific scheme summarized in side-partner-interface-mapping § Authentication for inbound writes: partner-bearer-JWT during the UAT bridge period (transitional convenience — one auth flow exercises both /wms-partners/v1/ reads and /pim/v1/* + /wms/v1/ writes); API key bearer in dev, mTLS at EKS ingress in prod-intl + prod-cn post-bridge-retirement per authentication.md canon. Idempotency uses the canonical (partner_id, correlation_id) tuple per idempotency — body fields on every POST; reusing the same correlation_id returns the original response (including the originally-minted server-assigned control_number) without re-processing.

Provide an `/authenticate` endpoint¶

Your /authenticate endpoint takes (partner_app_id, partner_app_secret) and returns a bearer token + declared TTL. The shape your endpoint returns is partner-specific; document it during onboarding so the adapter’s PartnerAuthenticationClient can wire it correctly.

Provide outbound endpoints¶

Your outbound endpoints receive the POSTs the adapter emits. Document the URL, request shape (typically JSON), and response error code envelope. Plan capacity for the expected event volume + retry behavior (the adapter retries on transient failures per the configured retry policy).

Smoke-test on your side¶

When FG.AI smoke-tests the adapter against your dev environment, you verify:

Your inbound endpoints receive correctly-shaped POSTs.
Your /authenticate endpoint receives valid credential exchanges and returns valid tokens.
Your outbound endpoints receive the expected POSTs with correct identity attribution (your tenant identifier + your warehouse code + your SKU/location codes).
Your error responses (success / partial success / auth failed / system error) trigger the documented adapter behaviors.

FG.AI’s side of the onboarding¶

Pre-flight verification¶

FG.AI verifies the prerequisites described above (MAX_SIDE_PARTNERS budget; signed agreement; credentials shared via secure channel; partner-side tenant identifier confirmed; outbound IP allowlist confirmed).

Provision the partner row + binding row¶

FG.AI inserts your partner row in the WMS partner-registry with integration_topology='PATH_C' and inserts a partner_tenant_binding row per FG.AI tenant in your scope. The binding row records the lifecycle state (active) and emits a Kafka event that triggers downstream provisioning automation.

Scaffold the per-partner adapter repo¶

FG.AI runs the bootstrap script against wes-partner-adapter-template to create your dedicated adapter repo (SiriusVoyager/wes-{your-partner-code}-adapter). The scaffolded repo includes a parent POM inheritance chain, the wes-partner-adapter-common library dependency, templated k8s manifests + GitHub Actions + Dockerfile + application.yml, and stub PartnerEventTranslator + payload record classes.

Implement the partner-specific code in the adapter¶

FG.AI engineers fill in:

{YourPartnerName}AuthenticationClient calling your /authenticate endpoint
One or more {YourPartnerName}*Translator classes (per outbound endpoint type)
Partner payload records matching your outbound spec verbatim (one Java record per endpoint shape)
application.yml populated with your per-environment hosts, auth URLs, postback URLs, retry policy, circuit-breaker thresholds, and Kafka subscription topic list

Provision cloud resources¶

FG.AI’s per-tenant Terraform provisions: SecretsManager entry for your credentials, IAM role (IRSA) for the per-tenant pod, per-tenant Kafka ACLs, Helm values for the Helm release.

Install + smoke-test the per-tenant Helm release¶

FG.AI helm installs the per-(partner, tenant) release in the shared partner-adapters k8s namespace and runs four smoke tests against your dev environment:

Token acquisition — adapter pod authenticates against your dev /authenticate endpoint and acquires a valid token.
Inventory transitions dry-run — synthetic wms.{tenant}.movement.v1 event published; adapter aggregates + POSTs to your inventory transitions endpoint; success response observed.
Per-document postback dry-run — coordinated synthetic per-document events published; adapter aggregates + POSTs to your per-document endpoint; success response observed.
Authentication-failure recovery — adapter’s cached token invalidated; next outbound POST triggers refresh + retry; success response observed.

Handoff to operations¶

When the four smoke tests pass:

FG.AI confirms the binding row remains active after smoke-test sign-off (the three-state lifecycle is active / migrating / retired per side-partner-operations § Partner-tenant binding lifecycle; smoke-test verification is recorded on the row’s audit log, not as a separate state).
FG.AI adds your tenant to the on-call rotation’s Path C list.
FG.AI schedules a 30-day post-onboarding review to verify steady-state operation.
FG.AI notifies you that integration is live and shares your FG.AI tenant ID for your records.

Common pitfalls during onboarding¶

These are the issues FG.AI partner-engineering sees most often:

Wrong-environment credentials. dev credentials against your uat host produces auth failures. Verify env-matched (app-id, app-secret, host) tuples end-to-end before smoke testing.
IP allowlist too narrow. Partner-side IP allowlists that don’t include FG.AI’s egress NAT range cause outbound POSTs to time out. Confirm FG.AI’s per-environment egress NAT addresses are in your allowlist before smoke testing.
Time skew. Bearer-token TTLs are wall-clock; if your auth endpoint and the FG.AI adapter pod disagree on time, refresh-lead margins may not fire correctly and outbound POSTs may hit auth failures mid-flight. Both sides should NTP-sync.
Missing partner_sku_mapping rows at production cutover. Inbound master-data writes establish the mappings; outbound expects mappings to exist. Plan the master-data bulk import to complete before any work-order push or movement-emitting activity.
Error code semantics mismatch. Your partial success code may share an HTTP status code with another semantic; the adapter’s response handler needs unambiguous code-to-semantic mapping. Document precisely during onboarding.

What happens after first production POST¶

Once you’re live, you’re in steady-state operation. The day-2 expectations (token rotation, error response behavior during incidents, what to do if you observe DLT growth) are covered in side-partner-operations.

The contractual retirement clause is a future event — when FlexSync v1 GA’s, FG.AI initiates the migration sequence covered there. Until then, you’re operating as a Path C partner with the adapter running per your engagement.