Skip to main content

Connecting your system

Order Response reads from a system you operate. Until you register one, every request returns 404 — there is nothing else for it to read.

Two things are needed: register your system with Hii Retail, and implement one endpoint for it to call.

Registering your system​

Register a target for the service key order-response with the Logistics Proxy Configuration service. You supply the base URL of your system and the credentials Hii Retail should use.

Scopeper tenant — each tenant registers its own system
AuthenticationHTTP Basic, or OAuth2 client credentials
Credentialsheld in Secret Manager, never in this service's configuration

⚠ Configuration is cached for up to 10 minutes. A change to your URL or credentials can take that long to take effect. When rotating credentials, keep the old ones valid until the window has passed, or requests will fail with 502 in between.

The endpoint you must implement​

Hii Retail appends /order-responses to the base URL you registered:

GET <your-base-url>/order-responses?businessUnitIds=BU1,BU2&itemIds=I1,I2

⚠ Your base URL carries its own prefix and version. If you register https://erp.example.com/api/v1, the call goes to https://erp.example.com/api/v1/order-responses. Do not include /order-responses in the URL you register, or it will be appended twice.

Both parameters arrive comma-separated, however the original caller supplied them. If a caller repeats businessUnitIds three times, your system receives one parameter with three comma-separated values.

What Hii Retail sends​

AuthorizationBasic or Bearer, depending on how you registered — see below
Tenant-Idthe tenant, resolved from the verified caller token or header
businessUnitIdsquery parameter, comma-separated
itemIdsquery parameter, comma-separated

Authorization follows the scheme you registered:

You registeredHii Retail sends
HTTP BasicAuthorization: Basic <credentials>, where <credentials> is the base64 encoding of username:password — the two values you registered, joined by a single colon
OAuth2 client credentialsAuthorization: Bearer <access-token>, using a token Hii Retail mints from your authorizationUrl with the registered clientId and clientSecret

⚠ Header names in HTTP are case-insensitive, and you should treat them that way — most frameworks lower-case them for you. Tenant-Id is the canonical spelling used throughout these docs; on the wire this service sends it lower-cased as tenant-id. Match it case-insensitively and either spelling works.

The tenant header always originates from a verified token or a verified header — never from something a caller put in a path, query or body. If you serve several tenants from one system, this header is how you tell them apart.

What you must return​

The same shape this service returns to its callers:

{
  "items": [
    {
      "itemId": "I1",
      "businessUnits": [
        {
          "businessUnitId": "BU1",
          "shipments": [
            { "deliveryDateTime": "2026-06-20T10:00:00Z", "confirmedQuantity": 100 },
            { "deliveryDateTime": "2026-07-04T10:00:00Z", "confirmedQuantity": 20 }
          ]
        }
      ]
    }
  ]
}

🛑 Get the shipments right; the business-unit total is computed from them. You may include a business-unit confirmedQuantity, but it is ignored — Hii Retail always recomputes it as the sum of that business unit's shipments. A total that disagrees with your own shipment list is silently replaced, so the caller sees a number you did not send and nothing reports the difference.

If a confirmation has no shipment breakdown, return it as a single shipment with its delivery date. That is the only way its quantity reaches the caller.

Testing before you connect a real system​

Hii Retail provides a mock you can register instead of your own system, to check the flow end to end before pointing at anything real. Ask your Hii Retail contact for the Logistics Proxy Mock.

Two things to expect​

Every request reaches your system. There is no caching of results — only of your configuration. A caller polling this endpoint is polling your ERP. If that is a concern, rate-limit at your end or put a cache in front of it; Hii Retail will not absorb the load for you.

Your availability is the endpoint's availability. If your system is unreachable, callers get a 502. Order Response holds no copy of your data and cannot answer without you — which is the point, but it means an outage in your system is visible to every Hii Retail caller of this endpoint.