Skip to main content

Proxy Mode

When requested by a tenant, the Customer Order service can be configured to proxy incoming requests to a specified URL. This allows the service to act as a middleman between the tenant and the external service, while still providing the ability to access the data through HiiRetail APIs and Frontends.

Configuration​

To enable the proxy mode, the tenant must connect the HiiRetail team and provide the URL of the external service. The team will then set up the tenant to use the proxy mode. After the proxy mode is enabled, the tenant will be able to configure the authentication method for the external service. At this point, the tenant will be able to access the Customer Order service through the HiiRetail API while the service will proxy the requests to the configured external service.

External service that is being proxied must be able to handle the requests from the Customer Order service. To learn more about the format that the external service must implement, please refer to the External Service Configuration documentation.

Authentication​

While in proxy mode, the Customer Order wil authenticate the requsts to the external service using the configured authentication method. To set up the authentication, an admin user on the tenant's side must provide the necessary credential by using the PUT: /api/v1/proxy-config endpoint.

Proxy mode currently supports the following authentication methods:

  • Basic Authentication
{
  "type": "basic",
  "config": {
    "username": "admin",
    "password": "password"
  }
}
  • OAuth2
{
  "type": "oauth2",
  "config": {
    "clientId": "client_id",
    "clientSecret": "client",
    "authUrl": "https://example.com/token"
  }
}

Outgoing Events (PosLog)​

When using the proxy approach, the external OMS must subscribe to PosLogs to receive updates about customer orders from the store -- for example, when an order is picked up by the customer.

PosLogs are delivered via WebHook through the Hii Retail ExternalEvents framework. Note that PosLogs are emitted for a variety of POS activities, including login, regular sales, and refunds, not only customer order events. The external system must filter the PosLog stream to identify the entries relevant to customer orders and take appropriate action based on those events.

note

When using the Events approach, dedicated customer order events are available via WebHook in addition to PosLogs, removing the need for filtering.

Limitations​

While in proxy mode, the Customer Order service will only provide access to the read endpoints. Any of the Order Updates must be done through the external service directly. The service also maps the responses from the external service to comply with the HiiRetail API standards.

The following endpoints are available in the proxy mode:

  • GET: /api/v1/business-units/{businessUnitId}/customer-orders/{customerOrderId}
  • POST: /api/v1/business-units/{businessUnitId}/customer-orders:search

Any other endpoints will return a 405 Method Not Allowed error if proxy mode is on.