Use cases

The aim of the SalesOrders-API is to be useful for implementing use cases related to sales in the "Retail" vertical.

Initially, the API will only support a small set of use cases:

  • Fetching sales order information
  • Receiving notifications about newly created sales orders
  • Creation of new sales orders
  • Updating status of sales orders (and related entities such as productions and fulfillments)

Fetching sales order information

A main use case of the SalesOrders-API is the ability to page through existing sales orders.

For paging through existing sales orders, the SalesOrders-API provides the endpoint GET /org/{org-id}/sales-orders/. That endpoint follows the normal paging-pattern of the enfore-APIs in that the client must specifiy a time-window via from and to and can then page within that window using offset and limit.

For example, the following requests can be used to access the first 200 sales orders whose transaction timestamp lies between 1pm and 3pm CEST on May 1st 2019:

  • GET /org/{org-id}/sales-orders/?from=2017-05-01T11%3A00%3A00Z&to=2017-05-01T13%3A00%3A00Z&limit=50&offset=0 (fetches items 0 to 49)
  • GET /org/{org-id}/sales-orders/?from=2017-05-01T11%3A00%3A00Z&to=2017-05-01T13%3A00%3A00Z&limit=50&offset=50 (fetches items 50 to 99)
  • GET /org/{org-id}/sales-orders/?from=2017-05-01T11%3A00%3A00Z&to=2017-05-01T13%3A00%3A00Z&limit=50&offset=100 (fetches items 100 to 149)
  • GET /org/{org-id}/sales-orders/?from=2017-05-01T11%3A00%3A00Z&to=2017-05-01T13%3A00%3A00Z&limit=50&offset=150 (fetches items 150 to 199)

Receiving notifications about newly created sales orders

Often times, clients are interested in sales orders that are newly created (for example via the enforePOS client UI). To not have to continously poll the paging endpoint, the sales order API provides a way to register for newly created sales orders via the subscription API.

The event type for newly created sales orders is SALES_ORDERS_NEW.

Whenever a new sales order is created, the registered callback will be invoked with the newly created sales order as payload.

Creation of new sales orders

Another use case for the API is the creation of new sales orders. This can, for example, be used to inject orders received by a third-party shop system into the enfore platform.

Note that sales orders cannot be created directly. Instead, one must first create a sales order draft, that can be processed on the enfore platform to become a sales order.

Sequence diagram: Create sales order

Updating status of sales order

Once a sales order has been created (either via the API or via the enfore POS client application), the API provides ways to modify the status of the sales order as well as of related object such as productions and fulillments.

Note that not all status transitions are valid, for example a sales order with a delivery (fulfillment) in status PENDING cannot be set to status COMPLETED. See the domain model documentation for more information on the different status types and how they interact.