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

  • Z Report - Broadly speaking, a Z Report acts like a set grouping of sales within a Trading Day for a specific Terminal (ie source of data entry).
  • Batch - One or more items submitted to the server together belonging to a common set of criteria (eg outlet, trading day).
  • Trading Day - A date (with no time component) that represents the day the sales 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.

Sales Integration

Overview

This section is targeted at 3rd party integrators who want to submit sales from another system into the PowerEPOS cloud backend system. Our Partner Service offers a simplified sales model to make it easy to translate sales data from other systems into the minimum requirements for sales data in PowerEPOS.

Z Reports

It is important to understand that all sales are allocated to a Z Report. This can be done automatically by the system or the integrator can explicitly request a Z Report to be allocated which they can then use for one or more batch submissions into the system. In broad terms, you can think of a Z Report as representing sales for a trading day (ie a single day of operation for the outlet). It is possible to have multiple Z Reports for the same trading day representing smaller periods within the trading day, however in the majority of cases an integrator would typically only work with a single Z Report per trading day.

Z Reports remain in an unfinalised (ie open) state until the integrator explicitly finalises (closes) them, or a Z Report is allocated for a new trading day and the integrator has explicitly enabled automatic finalisation of Z Reports from previous trading days. Sales can only be added to a Z Report when it is in an unfinalised state. If the Z Report has been finalised and new sales are submitted for that same trading day then an additional Z within that trading day must be created to store the new sales. You are not required to finalise a Z Report, but it is recommended as this indicates to the system that you have finished submitting sales for that period and may affect the ability for those sales to be exported out of PowerEPOS in the future.

Integration Notes

Sales are submitted in batches to the Partner Services using a PartnerSalesBatchRequest.

A PartnerSalesBatchRequest has two "SPECIAL" fields, "ZReportID" and "ZReportTarget". Only one of these two fields should ever be populated for a batch request.

  • Populate the ZReportID field when you are using the End to End Z Report Lifecycle Flow

OR

  • Populate the ZReportTarget field when you are using the Automatic Z Report Lifecycle Flow

The PartnerSalesBatchRequest model also has a field called BatchOptions. These options contain an optional field called AllowPartialBatchSubmission. This field (when true) tells the system to allow some of the batch of items to be stored in the system, even if others in the batch cannot be stored. So for example if you submitted a batch of 10 items, and one of those items had something wrong in the data, then 9 would be stored successfully and one would fail. The response would indicate which one failed and why. If this field is omitted or false, the entire batch will be rolled back in the event any of the items in the batch cant be stored. There is also a field called AutoFinalisePreviousTradingDays which can optionally be enabled to get the system to automatically finalise any open Z Reports that may exist from this integration for previous trading days.

The PartnerSalesBatchResponse model returns information about the batch submission status of each item within the batch (BatchItemResults field).

Z Reports are allocated using a PartnerZReportRequest. The PartnerZReportResponse model contains the allocated Z information for the resolved Z Report.

Z Reports are finalised using a PartnerZFinaliseRequest. The PartnerZFinaliseResponse model contains the state of the Z Report after the request has completed.

Sale items are defined in the PartnerSalesTransactionItem model. Sale items need to either reference a PLU number that exists in the POS's configuration database (by supplying the PLUNumber field), OR, the integration can supply the name of the sale item using the PLUName field. When supplying the name, it is recommended that you also supply MainGroupName and GroupName if possible. It is possible to also supply both PLUNumber AND any of the name fields. In this situation, the supplied names will be used in place of the names already configured in the POS's configuration for that PLU.

If you do not supply either PLUNumber or PLUName for each item, the transaciton will be rejected. If you do specify PLUNumber and the PLU cannot be found in the POS's configuration database then the transaction will be rejected. Specifying 0 as the PLU number will be treated the same as not supplying it at all.

Adjustments (Discounts / Surcharges)

In the PowerEPOS system, discounts and surcharges are referred to collectively as an "adjustment". The partner sales api has support for adjustments at both the order level (ie affecting all items) and/or the item level (affecting a single, or collection of items). A subset of sale items affected by a single adjustment is referred to as a bucket. The adjustment record type contains a BucketID field which is used for grouping a number of items under the same adjustment. For example, if you had a Buy 2, Get 1 Free discount you would group the 3 items that form that adjustment into their own bucket so that "Buy 2, Get 1 Free" discount only affects the value of those 3 items, and not any other items in the transaction.

The PartnerSalesTransaction model has a "TransactionAdjustments" field which is where all order level adjustments should be applied. The effects of any adjustments specified here are prorated across all items within the transaction automatically.

The PartnerSalesTransactionItem model has an "ItemAdjustments" field which is where any adjustments affecting that particular item are specified. The effects of adjustments specified here are expected to have been already prorated for that item. If the BucketID field is used for these item adjustments then the system creates a single adjustment combining the values from all adjustments with the same BucketID and prorates them across all linked items as per the proration already defined in the PartnerSalesTransactionAdjustment record. If the BucketID is field is not used for an item adjustment then the adjustment values are assumed to be specific to that item only.

  • Use BucketID when you have multiple items that are part of the same item level adjustment.
  • Leave BucketID null when that adjustment only applies to that item.

Technical Flows

There are a couple of flows that can be used to submit sales to the Partner Service via this method.

Integration Controlled Z Report Lifecycyle Flow

This method has the integrator explictly request a Z Report to be allocated (or retrieved if a match already exists) for their sales batch. They then explicitly tell the system which Z Report to associate each sale in the batch to. Once they have finished submitting sales, they then finalise the Z Report to indicate there are no more sales for that trading day.

If the integrator is using a flow where they trickle sales into the system intermittantly during the day, they can request the Z allocation once at the start of the day and then continue to use the ZReportID for the rest of the day. At some point they would ideally have an end of day flow where they finalise the Z Report. If the 3rd party system needs to be restarted during the day (for example), it is fine for them to request the Z Report allocation again. They will be returned the same unfinalised Z Report they were working on previously for that trading day.

This flow basically gives the 3rd party full control over the Z Report allocation for the sales.

Automatic Z Report Lifecycle Flow

  • The integrator simply submits a batch of sales via the PartnerSalesBatchRequest but populates the ZReportTarget field in the the PartnerSalesBatchRequest model instead of the ZReportID field. The ZReportTarget field defines a list of identifying critera for the sales so the system can automatically allocate a Z Report to the sales batch. The batch submission will return the ZReportID that was automatically allocated by the system for that batch.
  • (Optional) Once all sales for the trading day have been submitted, finalise any automatic Z Report IDs that were returned in the PartnerSalesBatchResponse using the PartnerZFinaliseRequest.

This method has the integrator let the system automatically allocate a Z Report for each of their sales batches. By default, any automatically allocated Z Reports will remain in an unfinalised state unless the PartnerSalesBatchRequestOptions field AutoFinalisePreviousTradingDays has been set to true. In this case, the system will automatically finalise any Z Reports created by the integration that were opened for previous trading day(s) when the batch request has completed. Alterantively (and optionally) they can explicitly tell the system to finalise the Z Report ID(s) that were returned during the batch submission(s) themselves to close them earlier than when the first batch submission occurs for the following trading day.

If the integrator sends sales in an adhoc manner, this flow is simpler. Sales should be submitted in ascending trading date order. If there are sales for multiple trading days then they should be submitted in batches from oldest to newest trading day. This will ensure sequential Z Counters for each trading day and is a requirement when using the AutoFinalisePreviousTradingDays batch option.

Sales Integration API