Host Integration

Host Integration

A host system (WMS/ERP) integrates against one vendor-neutral contract — the Host API, served by integration-host at /api/host/**. Vendor adapters (integration-sap, integration-manhattan) translate their native message formats into this same API, so the host specifics stay isolated in the adapter (anti-corruption layer).

SAP        ─►  integration-sap        ─┐
Manhattan  ─►  integration-manhattan  ─┼─►  /api/host/*  (integration-host)  ─►  order-management
other host ─►  (direct)               ─┘                                          master-data
                                                                                  txlog

Host API (integration-host, port 8092)

Inbound (host → openWCS):

Endpoint	Purpose
POST /api/host/orders	Create an outbound order (ship-to, service, route, label template, lines) → order-management OUTBOUND.
POST /api/host/asns	Create an ASN / expected receipt → order-management INBOUND.
POST /api/host/masterdata/skus	Upsert a list of SKUs into master-data (by code), each with its UoM hierarchy and barcodes inline (see below).
POST /api/host/inventory/adjustments	Signed stock adjustment → appended to txlog as StockAdjusted.

SKU sync (UoMs + barcodes)

The host pushes a JSON array of SKUs; each SKU carries its unit-of-measure hierarchy and barcodes inline. Intra-SKU references are by code, so the host never needs openWCS-generated UUIDs: a UoM names its parent by parentCode, a barcode names its packaging level by uomCode, and a barcode's type by name (EAN13, GTIN14, GS1-128, …).

This is an upsert, not a full-catalog replace: a SKU that is not in the batch is left untouched — neither it nor its UoMs/barcodes are removed. The full-replace is scoped to each SKU that is in the batch.

Within a synced SKU the host is authoritative over its nested data: the SKU's uoms/barcodes lists fully replace what is stored for it (a UoM or barcode the host omits for that SKU is removed). UoMs are matched by (sku, code), so their ids — and any stock referencing them — survive a re-sync. The whole batch is applied in one transaction. master-data does this via POST /api/master-data/skus/sync; the response is a per-SKU created/updated report.

[
  {
    "code": "SKU-1",
    "description": "Widget",
    "batchTracked": true,
    "uoms": [
      { "code": "EACH", "baseUnit": true },
      { "code": "CASE", "parentCode": "EACH", "qtyInParent": 12 }
    ],
    "barcodes": [
      { "value": "4006381333931", "uomCode": "EACH", "type": "EAN13" }
    ]
  }
]

Outbound (openWCS → host) — confirmations of receipts, picks, shipments, stock changes:

Mechanism	How
Pull	GET /api/host/confirmations?cursor= — a cursor feed over the txlog global replay; returns events after the cursor plus nextCursor. No host endpoint needed.
Push	POST /api/host/webhooks registers a callback; a scheduled dispatcher POSTs confirmations and advances each subscription's cursor only past delivered (2xx) events (at-least-once). Enabled by openwcs.host.webhook.enabled.

Idempotency: any host POST may send an Idempotency-Key header — a repeated key replays the stored response instead of re-processing, so a retry never double-creates an order/ASN/adjustment.

Contract: contracts/openapi/host-api.yaml.

Vendor adapters

• integration-sap (/api/integration/sap/**): orders/asns reshape SAP messages and resolve materials → SKUs, then call the Host API; also labels (per-shipper barcode, used by allocation) and routes/sync (host route feed → master-data Route catalog).
• integration-manhattan (/api/integration/manhattan/**): Manhattan orders/asns translated into the Host API (items → SKUs).

Both resolve vendor item/material codes to SKU ids via master-data (unknown → 422).

The real SAP/Manhattan wire protocols (OData/BAPI/IDoc, Manhattan REST) are skeletal — the adapters currently accept a representative JSON shape. The translation into the Host API is the part that's wired.

Related: Outbound Flow · Inbound and Inventory · API Reference.