PowerEPOS Partner Services Overview
The PowerEPOS Partner Service is an API/Service for allowing third parties to interface with the PowerEPOS backend cloud system. An example would be a 3rd party integration needing to submit sales data into the PowerEPOS backend system.
Vocabulary
Before proceeding it will be good to familiarise yourself with the vocabulary used by this API
- Stock Order - Broadly speaking, a Stock Order represents a single "order" comprising of a purchase order (optional), stock invoice and goods receipt.
- Trading Day - A date (with no time component) that represents the day the stockmovements should be recorded against. Consider an outlet that operates over midnight, the period after midnight but before the first full session of that following day is really part of the previous day. For example a pub operation would typically have a trading period of 6am to 6am. This means that all sales from 6am until 6am the following day are considered part of the same day's sales (ie trading day).
- Adjustment - Adjustment is a term used to collectively refer to either a discount or surcharge in the PowerEPOS system.
Date/Time Formats
Important: All DateTime fields in the Partner Service models (unless explictly stated) should be considered to be in outlet "Local" time. They should be submitted in a generic "yyyy-MM-dd HH:mm:ss" format with no timezone information included. The server will process and store that value as the date/time relative to the outlet it is posted for.
eg
"2021-01-01 10:25:30" for 1st Jan, 2021 @ 10:25:30 am
you can also include milliseconds if required, eg
"2021-01-01 10:25:30.123" for 1st Jan, 2021 @ 10:25:30.123
Technically these formats are also valid, but it is recommended that you use the above format.
"2021-01-01T10:25:30" for 1st Jan, 2021 @ 10:25:30 am (T has no effect)
"2021-01-01T10:25:30Z" for 1st Jan, 2021 @ 10:25:30 am (trailing Z (UTC identifier) will be ignored, time is still considered outlet local time by the server)
Getting Started
Please see our onboarding documentation for getting setup with credentials.
Stock Integration
Overview
This section is targeted at 3rd party integrators who want to submit stock orders from another system into the PowerEPOS cloud backend system. Our Partner Service offers a simplified stock order model to make it easy to translate stock invoice data from other systems into the minimum requirements for stock orders in PowerEPOS.
Integration Notes
Stock Orders are submitted individally to the Partner Services using a AddStockOrderRequest.
The AddStockOrderResponse model returns information about the attempted stock order submission. It may also contain (when applicable) details relating to individual line items within the stock order (LineItemFailureResults field).
Stock Order line items are defined in the AddStockOrderRequestLineItem model. Line items must provide a "Supplier Product Code" when the ItemType is set to one of the Stock based options.
Please review the comments next to each field in the api models for more information about how to use them.
Adjustments (Delivery Fee, Discounts or Surcharges)
In the PowerEPOS system, delivery fee's, discounts and surcharges are referred to collectively as an "adjustment". The partner stock api has support for including adjustments when required. This is done as a line item by using an ItemType that matches the required adjustment type.
Technical Flows
There are a couple of flows that can be used to submit sales to the Partner Service via this method.
Validation and Model / Request Errors
The endpoints which process the request have strict model validation rules in place. If the request model is not valid, the endpoint will return a HTTP 400 Bad Request response with details of the validation errors. Validation rules at this step come from the model data annotations which are defined in the model classes. eg [Required] attributes etc.
The services which process the request will also perform business logic validation on the request data. Any failures will be returned in the response model and where applicable, specific line item validation failures may also be returned.