Proxy configuration

Several Hii Retail logistics services can answer a question from your own system instead of from Hii Retail's data: an OMS that owns your orders, an ERP that owns your stock. You tell them where your system is, and how to sign in to it, in one place: the logistics proxy configuration service.

This page covers what is the same for every service. What each service forwards, and what it does when your system cannot answer, is on that service's own page.

One configuration per tenant and service. Your admin stores an entry for each service key in the logistics proxy configuration service: customer-order, stock-transaction-query, click-and-collect-location and order-response. Each logistics service reads only its own entry, and calls your system at that entry's address with its credentials.

Which services read it

Service key (`service=`)	What is read from your system	Without a configuration	Described in
`customer-order`	one order, and order search	Hii Retail's own orders	Customer Order: proxy mode
`stock-transaction-query`	stock quantities	Hii Retail's own stock	Stock query API: configuring it
`click-and-collect-location`	the containers a customer order was packed in	Click and Collect's own containers	Click and Collect: picking
`order-response`	supplier confirmations of what is on order	`404`: the service has no data of its own	Order Response: connecting your system

⚠ The service also accepts the keys goods-received, stock-count and stock-corrections. No service reads them, so a configuration stored under them changes nothing.

Setting it

PUT https://logistics-proxy-config.retailsvc.com/api/v1/proxy-config?service=<service key>
GET https://logistics-proxy-config.retailsvc.com/api/v1/proxy-config?service=<service key>

One configuration per tenant and service key. The tenant is taken from your token. Configure each service you want proxied, even when they all point at the same system.
Permissions: lpc.proxy-config.set to write and lpc.proxy-config.get to read, both in the role lpc.admin.
PUT answers 204 and replaces what was stored. GET answers 404 when nothing is stored for that service.

The Logistics Proxy Configuration API reference has the full contract.

The body

With HTTP Basic:

{
  "type": "basic",
  "config": { "username": "hii-retail", "password": "s3cret" },
  "apiConfig": { "url": "https://erp.example.com/api/v1" }
}

With OAuth 2.0 client credentials:

{
  "type": "oauth",
  "config": { "clientId": "hii-retail", "clientSecret": "s3cret", "authUrl": "https://login.example.com" },
  "apiConfig": { "url": "https://erp.example.com/api/v1" }
}

Field	What it holds
`type`	`basic` or `oauth`
`config`	the credentials for that type. Every field is required
`apiConfig.url`	the base address of your system, an absolute `https` URL. Each service appends its own path to it, so include any prefix and version your system needs. The service's own page shows the paths

Leave out apiConfig to switch proxying off for that service and keep the credentials. Every service then treats the tenant as not configured.

A configuration with a malformed apiConfig.url or authUrl is refused with 400.

OAuth: what `authUrl` may be

authUrl is your identity provider's address, in either of two forms:

its issuer address, such as https://login.example.com. The service reads the discovery document at https://login.example.com/.well-known/openid-configuration and requests tokens from the token endpoint it names.
its token endpoint, such as https://login.example.com/oauth/token, for an identity provider without OpenID Connect discovery.

authUrl may be your identity provider's issuer address or its token endpoint. The service first asks for a discovery document at authUrl/.well-known/openid-configuration. If there is one, it requests the token at the token_endpoint it names; if there is none, it requests the token at authUrl itself. If the identity provider cannot be reached, the call fails with 502 Bad Gateway.

Tokens are requested with the client-credentials grant and no scope, with the client id and secret sent as HTTP Basic. A token is used until shortly before it expires. If your system rejects one with 401 before then, a new token is fetched and the request is repeated once.

Reading it back

GET shows password and clientSecret as ********. Everything else comes back as stored.

To change one field, send back what you read with that field changed. A ******** you send back keeps the stored secret; it is never stored as the secret itself. If nothing of that type is stored, a ******** is refused with 400, so send the real value the first time.

A masked secret sent back is kept. Reading the configuration shows the password as eight asterisks. Writing it back with a new address and the asterisks unchanged stores the new address and keeps the real password; Hii Retail never stores the asterisks.

The credentials are kept in a secret store, never in the logistics services' own configuration.

When a change takes effect

Within 10 minutes. Each service keeps the configuration it read for up to 10 minutes, and that includes remembering that there was none, so a first registration can take as long as a change.

When you rotate credentials, keep the old ones valid for 10 minutes after storing the new ones, or calls made in between will fail.

What every call to your system carries


`Authorization`	`Basic` with your username and password, or `Bearer` with a token from your identity provider
`Tenant-Id`	the tenant the call is made for. Match header names case-insensitively

Every call has a time limit. If your system does not answer in time, the caller gets 504 Gateway Timeout, and if your identity provider does not, 502 Bad Gateway. The service's own page says what else the caller gets when your system answers with an error.

Which services read it​

Setting it​

The body​

OAuth: what authUrl may be​

Reading it back​

When a change takes effect​

What every call to your system carries​