Documentation Powered by ReDoc

Transaction Engine API (${API_VERSION})

Download OpenAPI specification:Download

Transaction Engine API enables its clients to produce sales with the Transaction Engine business logic, integrations, receipt rendering and pricing across multie sales channels.

The API is primary geared towards point of sale (POS) clients operated by a cashier. However, it should also offer resources and extension points to use the API from other types of clients or even build other services on top of the API.

Authentication

BearerAuth

All authenticated endpoints expects a Bearer access token in the Authorization header

Authorization: Bearer <access_token>

How to obtain a valid JWT depends on the deployment. Tokens must be from a source trusted by the Transaction Engine to allow downloading of JWK sets. Regardless of source, the following application specific claims must be present in the token:

  • https://hiiretail.com/cashierId - The cashier number in the Transaction Engine
  • https://hiiretail.com/roles - A list of user roles
Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Core concepts

This section provides an overview the core concepts in the Transaction Engine API.

Before the API is used the client must obtain a valid JSON Web Token. The JWT is required in all secured API calls. See Authorization for more details.

Session life cycle

All API operations are performed on a unique client session. The session must be created before it can be used to create and populate transactions. Once a client is done it should preferrably logout to close the session. Abandoned sessions are eventually removed.

Session usage

  • The client creates a session with provided settings. Settings include country, store, workstation identifiers and optional layout configuration.
  • The Transaction Engine returns a unique session ID to be used to access resources within the session context.
  • The client can proceed to perform operations on the session, for example:
    • Add entities to the receipt. An entity is typically added by scanning a barcode on the client and then submit it using the register entity API call.
    • The entity is processed and validated on the Transaction Engine.
    • The updated active receipt is returned with details about the added entity and rendering data to visualize the receipt on the client.
  • When all items are added, the client can initiate payment for the transaction.
  • The Transaction Engine will process and validate the payment. Finalization of an order typically involves external integrations and can also include printing to a phyiscal printer among other things.
  • When the receipt is finalized a final copy of the receipt is returned to the client.
  • The client can continue to create new transactions or perform other operations in the same session
  • Once done, the client should end the session to remove it permanently.

Client response

All operations that manipulate the receipt returns a client response wrapper object that contains one of the following:

  • A boolean flag to indicate that nothing changed
  • An updated receipt model. Depending on the session settings, this is either the full receipt or the changes delta
  • A prompt request in which the Transaction Engine requests additional user input from the client

Request-response flow

Clients must use their session in a strict request-response flow, except for the async push events. This means that a client must wait for a response (or the timeout) before sending the next request. If this contract is broken the API will not behave correctly and will break with unexpected behavior.

Request-Response flow

If the second request would be sent before the first response the Transaction Engine would either

  1. interrupt the first request and serve the second request,
  2. return an HTTP 500 error or
  3. reject the second request with an HTTP 4XX

What scenario the client will see depends on timing and the type of requested resources.

There is a few exceptions to the request-response restriction, where the APIs allow concurrent requests.

  • Image resources
  • Status event subscriptions are active while issuing other requests

Prompt requests

The Transaction Engine can request additional input on most operations using a prompt request construct.

Prompt request

  • A client adds an entity that will require additional input. It could for example be an age restricted item, or an item that requires an alarm tag to be removed.
  • The Transaction Engine processes the item and determines that additional input is required
  • A prompt request is created and returned to the client. The Transaction Engine will suspend processing.
  • The client should display the request for additional input to its user and allow them to act on it. In the case of age restriction, the prompt request would ask for the customer's age. In the case of an alarm tag, it would remind the user to remove the tag.
  • When the input request is handled, the client sends the prompt response to the Transaction Engine.
  • The Transaction Engine will continue processing. The result of the processing could result in more prompt requests.
  • When the processing is completed, the Transaction Engine will return the active receipt with the added entity.

Controllable prompt requests

A controllable prompt request is a request for input that can be cancelled, modified or fulfilled from the Transaction Engine. Examples when controlled prompts are common include

  • EFT payments
  • Manager override use cases
  • Prompt requests that can be managed by a remote attendant

When a prompt request is controllable, clients must subscribe to events in order to detect when the request is updated or closed.

Controlled prompt request

  • A client adds an entity that will dispatch a request to an external system.
  • While waiting for a response, the Transaction Engine returns a controllable prompt that can offer feedback or allow for ways to cancel the operation.
  • The Transaction Engine can send one or more change prompt events to request that the client updates its user interface representation of the original prompt request. If the prompt allows for user input, the client can choose to submit a prompt response which will be processed by the Transaction Engine.
  • When the external system completes processing the Transaction Engine can request for a prompt to be using a close prompt event.
  • When the client hides the prompt, it should send a prompt response back to the Transaction Engine to get end the interaction with an updated receipt as response.

Receipt model

The receipt consists of entities that represents the lines in a receipt. The two major pieces of information in an entity are

  • The type safe information about the underlying receipt data. This is for example saleItem or loyaltyInfo data structures.
  • A layout block to help clients render a visual representation of the receipt.

The type safe information can be used in whatever way clients see fit. The data is documented and available as API models.

The layout and especially the DSL layout rows may however never be parsed in an attempt to deduce data about the entity. The structure of rows and cells vary depending on state not disclosed to the client. The layout information should only be used for its intended purpose, which is to render an entity similar to that on a printed receipt.

See also receipt rendering for more details on how to process layout DSL.

Status events

Status events is an asynchronous push notification feature that complements the Open API. It allows clients to listen for asynchronous changes to their session between, but especially during, an active request-response flow.

Clients should register for push status events when

  • A controllable prompt request is returned from Transaction Engine
  • An interactive EFT payment is initiated
  • It needs status notifications from any of the supported events that may be created in-between operations. This could for example be the suspended order count that is updated whenever a transaction is suspended within the store.

User experience

This section explains how API resources are used in user experience and user interface.

Menus

The menu tree resources in the API are intended to be used together with the command execution operations. Clients can get the menus and render them as a tree menu structure.

  • When a menu option with children is selected, display the children
  • When an option without children is selected, use the command to run the operation
  • The menu will only include choices that the user is authorized to use
  • Choices have optional conditions that should be used on the client to
    • Disable choices depending on the session state
    • Provide the current selected entity as an input parameter if required

If menus are used, clients are recommended to load them after creating a new session. The menus support caching so it is efficient to check for changes.

The API supports both a default menu and named menus. What names that are available depends on configuration in the Transaction Engine. Typically, Tranaction Engine offers the following named menus, but it is not limited to these.

  • default - the default menu (always available)
  • payment - payment specific menu
  • item - options to manipulate a receipt entity (availability may depend on application type)

Receipt rendering

For most interactive clients, the default DSL layout is recommended. It provides clients with a data structure consisting of rows and columns, similar to a flex-box layout.

  • Rows define basic font styling
  • Cells contain a text value to be rendered in the specified relative width and aligned and truncated according to the defined properties

The layout provided by the Transaction Engine is often configured to be similar to the printed receipt. If the receipt is rendered with the provided layout data it ensures that the content and visualization is the same across all sales channels. The limitation with the provided layout is that it can't make sure of device-specific features to enhance the user experience.

Price lookup tree

The price lookup (PLU) tree is similar to the menu trees but provides an hierarhical tree structure to browse and optionally register items that may not have a barcode. This may include fruit, bread and heavy items.

  • An PLU entry with children is a category. When selected it should display its children.
  • When a PLU entry with a posIdentity is selected, the value should be provided as input to the register entity resource.
    • The PLU entry includes unit of measure to allow clients to provide weight as an input parameter when registering the item. If not provided, the Transaction Engine will request the weight with a prompt request

Clients should load the PLU after the session has been created. It is recommended to update the price lookup tree between each receipt to receive updates to the tree structure. The resource supports caching and will only return a new structure when changed.

Input information

Input information

The purpose of the input information query is to support flexible user experience when details about the input may be required before trying to register it at the Transaction Engine. Examples of use cases for input information:

  • Self checkouts that should validate the item weight before sending it to the Transaction Engine.
  • Clients that need access to the item name or other properties for the user experience.
  • Validation of the input to check what type of value it represents in Transaction Engine. Typically, this means to check if the input is an item barcode, a loyalty card or something uknown.

The downside with the input information query is that it introduces an extra API call, so it's use should be weighted against its effect on throughput in the client.

Session management

Resources to create and manage the client session.

Create a new session

Create a new session. The created session is the client's unique identifier for future requests to the API. When the client is done, it should remove the session to invalidate it.

Clients must use their session in a strict request-response flow, except for the async push events. This means that a client must wait for a response (or the timeout) before sending the next request. If this contract is broken the API will not behave correctly and will break with unexpected behavior.

Authorizations:
BearerAuth
Request Body schema: application/json

The session settings

applicationType
required
string (ApplicationType)
Enum: "DEFAULT" "MOBILE_POS" "QUEUE_BUSTER" "SELFSCAN" "SELFSCAN_PAYMENT" "SELF_CHECKOUT" "UNATTENDED" "WEB_POS" "WEB_SHOP"

Application type categories. The application type is used to tailor use cases for different applications.

  • DEFAULT - Default application type. Use this for a regular POS client, or clients that behaves like a regular POS client.
  • MOBILE_POS - A Mobile POS application.
  • QUEUE_BUSTER - A Queue Buster application. If mobile, the queue buster is similar to a Mobile POS, but without options to finalize the order.
  • SELFSCAN - A Selfscan application. This application type should be used by selfscan terminals, where customers scan.
  • SELFSCAN_PAYMENT - A selfscan application that can perform payments. This application type should be used by selfscan terminals or application , where customers scan and can perform payment using the selfscan device API.
  • SELF_CHECKOUT - A self checkout application. This is a customer-facing application with specialized hardware.
  • UNATTENDED - A general application type for unattended clients. An unattended client could for example be a price inquiry terminal or a scale that requires a PLU integration.
  • WEB_POS - A web-based (thin) POS application.
  • WEB_SHOP - A web shop integration application.
attendantSupported
boolean

Flag indicating if the client supports monitoring and interactions from a remote POS attendant. A client that has set this flag must handle attendable prompts and attendant response events.

cashierLocale
string

The cashier session locale as an RFC 5646 language tag

evaluatePromotion
boolean

Flag to control if promotions are evaluated

extendedInfo
boolean

Flag indicating if the client wants to receive extended receipt information (for example tax and discount information for items)

itemValidationBehavior
string (ItemValidationBehavior)
Default: "IMMEDIATE"
Enum: "IMMEDIATE" "POSTPONED" "INHIBITED"

Enumeration for item validation behavior during item registration.

  • IMMEDIATE - Indicates that all validations performed during item registration are done immediately.
  • POSTPONED - Indicates that validations performed during item registration can be postponed, if their validation type supports postponed validation (e.g. age verification). If the validation is postponed, the registered sale item will have postponed validations. Postponed validations have to be validated before any tendering is started.
  • INHIBITED - Indicates that validations should not be run. Exceptions to the inhibition can be made so that validations that are absolutely necessary for an entity to be registered or a transaction to be finalized are run. This option is primarily meant to be used for transactions that have already been finalized before being sent to POS.
object (LayoutConfig)

Receipt layout configuration. This configuration determines how the receipt layout should be formatted for a client. The width and font settings only applies if layout type is HTML.

logoutBehavior
string (LogoutBehavior)
Enum: "AUTHORIZED" "DISCARD_TRANSACTION_FIRST"

Enumeration of the possible logout behaviors. This setting is used for logout requests to make the behavior flexible for the different type of API clients.

  • AUTHORIZED - Authorize logout with configured authorizes. This would deny logout when an active transaction exists. This is the expected behavior in a classic POS client.
  • DISCARD_TRANSACTION_FIRST - Discard (system cancel) any active transaction before logging out. This setting first performs a proper discard transaction command and then applies the normal authorized logout command. For proper receipt sequences, this is the recommended setting.
systemLocale
string

The system locale as an RFC 5646 language tag. This locale can be used at the client for i10n when formatting must be consistent with receipt formatting performed by the service.

This value can never be controlled by the connecting client and is only available once the session has been created.

useReceiptDelta
boolean

Flag to control if receipt deltas should be used. If set, modifications to the receipt are returned as deltas instead of full receipts.

country
required
string

The ISO 3166-1 2-alpha country code

retailStoreId
required
string

The retail store ID for the session

workstationId
required
string

Workstation ID for the session

Responses

Request samples

Content type
application/json
{
  • "applicationType": "DEFAULT",
  • "country": "SE",
  • "retailStoreId": "004217",
  • "workstationId": "001"
}

Response samples

Content type
application/json
{
  • "properties": [
    ],
  • "sessionId": "4A62362A-00CA-43B2-B242-46FCE9335EDE",
  • "settings": {
    }
}

Get session information

Get information about an existing session.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Responses

Response samples

Content type
application/json
{
  • "properties": [
    ],
  • "sessionId": "4A62362A-00CA-43B2-B242-46FCE9335EDE",
  • "settings": {
    }
}

Change the session settings

Change the settings in the client's active session. Note that workstation and retail store can't be changed. To change these properties a new session should be created.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Request Body schema: application/json

The new settings

applicationType
required
string (ApplicationType)
Enum: "DEFAULT" "MOBILE_POS" "QUEUE_BUSTER" "SELFSCAN" "SELFSCAN_PAYMENT" "SELF_CHECKOUT" "UNATTENDED" "WEB_POS" "WEB_SHOP"

Application type categories. The application type is used to tailor use cases for different applications.

  • DEFAULT - Default application type. Use this for a regular POS client, or clients that behaves like a regular POS client.
  • MOBILE_POS - A Mobile POS application.
  • QUEUE_BUSTER - A Queue Buster application. If mobile, the queue buster is similar to a Mobile POS, but without options to finalize the order.
  • SELFSCAN - A Selfscan application. This application type should be used by selfscan terminals, where customers scan.
  • SELFSCAN_PAYMENT - A selfscan application that can perform payments. This application type should be used by selfscan terminals or application , where customers scan and can perform payment using the selfscan device API.
  • SELF_CHECKOUT - A self checkout application. This is a customer-facing application with specialized hardware.
  • UNATTENDED - A general application type for unattended clients. An unattended client could for example be a price inquiry terminal or a scale that requires a PLU integration.
  • WEB_POS - A web-based (thin) POS application.
  • WEB_SHOP - A web shop integration application.
attendantSupported
boolean

Flag indicating if the client supports monitoring and interactions from a remote POS attendant. A client that has set this flag must handle attendable prompts and attendant response events.

cashierLocale
string

The cashier session locale as an RFC 5646 language tag

evaluatePromotion
boolean

Flag to control if promotions are evaluated

extendedInfo
boolean

Flag indicating if the client wants to receive extended receipt information (for example tax and discount information for items)

itemValidationBehavior
string (ItemValidationBehavior)
Default: "IMMEDIATE"
Enum: "IMMEDIATE" "POSTPONED" "INHIBITED"

Enumeration for item validation behavior during item registration.

  • IMMEDIATE - Indicates that all validations performed during item registration are done immediately.
  • POSTPONED - Indicates that validations performed during item registration can be postponed, if their validation type supports postponed validation (e.g. age verification). If the validation is postponed, the registered sale item will have postponed validations. Postponed validations have to be validated before any tendering is started.
  • INHIBITED - Indicates that validations should not be run. Exceptions to the inhibition can be made so that validations that are absolutely necessary for an entity to be registered or a transaction to be finalized are run. This option is primarily meant to be used for transactions that have already been finalized before being sent to POS.
object (LayoutConfig)

Receipt layout configuration. This configuration determines how the receipt layout should be formatted for a client. The width and font settings only applies if layout type is HTML.

logoutBehavior
string (LogoutBehavior)
Enum: "AUTHORIZED" "DISCARD_TRANSACTION_FIRST"

Enumeration of the possible logout behaviors. This setting is used for logout requests to make the behavior flexible for the different type of API clients.

  • AUTHORIZED - Authorize logout with configured authorizes. This would deny logout when an active transaction exists. This is the expected behavior in a classic POS client.
  • DISCARD_TRANSACTION_FIRST - Discard (system cancel) any active transaction before logging out. This setting first performs a proper discard transaction command and then applies the normal authorized logout command. For proper receipt sequences, this is the recommended setting.
systemLocale
string

The system locale as an RFC 5646 language tag. This locale can be used at the client for i10n when formatting must be consistent with receipt formatting performed by the service.

This value can never be controlled by the connecting client and is only available once the session has been created.

useReceiptDelta
boolean

Flag to control if receipt deltas should be used. If set, modifications to the receipt are returned as deltas instead of full receipts.

Responses

Request samples

Content type
application/json
{
  • "applicationType": "DEFAULT"
}

Response samples

Content type
application/json
{
  • "properties": [
    ],
  • "sessionId": "4A62362A-00CA-43B2-B242-46FCE9335EDE",
  • "settings": {
    }
}

Sign out and remove the session

Sign out and remove the session. When a session has been removed it can no longer be accessed.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Responses

Transactions

Resources to create and manage transactions

Create a transaction

Create a transaction and optionally register the first item. If no input body is provided, an empty transaction will be created.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Request Body schema: application/json

The entity input. If omitted an empty transaction is created

required
object (Input)

Representation of input sent to the system.

Array of objects (PosParameter)

The input parameters

Responses

Request samples

Content type
application/json
{
  • "originalPOSIdentity": {
    }
}

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Get a transaction

Get a specific transaction from the session. The returned receipt will be the format and content used by the client as the receipt model is allowed to be cached for performance. To obtain a receipt formatted for another external party, generate a receipt image instead.

To view the receipt from an external client it is recommended to request a ReceiptImage instead.

Authorizations:
BearerAuth
path Parameters
receiptId
required
integer <int64>
Example: 1

The receipt ID

sessionId
required
string

The session ID

header Parameters
Cache-Control
string

Set to no-cache to reload the receipt

Responses

Response samples

Content type
application/json
{
  • "delta": false,
  • "endTime": "2019-08-24T14:15:22Z",
  • "entities": [
    ],
  • "exitGate": {
    },
  • "id": 100,
  • "itemCount": 3,
  • "rescanData": {
    },
  • "selectedEntity": 11,
  • "startTime": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "totals": {
    },
  • "transactionId": "string"
}

Cancel transaction

Cancel or discard the transcation. Use the discard parameter to control whether to cancel or discard the transaction. A cancelled transaction may require each entity to be voided before the transaction is cancelled. A request to cancel the transaction MAY be rejected due to the state of the transaction or due to items sold.

When a transaction is discarded, no validations are performed and the transaction is always, unconditionally cancelled.

Authorizations:
BearerAuth
path Parameters
receiptId
required
integer <int64>
Example: 1

The receipt ID

sessionId
required
string

The session ID

query Parameters
discard
boolean
Default: false

Flag to discard receipt

Responses

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Generate a receipt image

Generate a receipt image representation. The returned receipt image will be formatted according to the format query parameter. If the transaction is finalized, the receipt image contains all receipt slips that would have been printed on a physical printer. If the transaction is still active, the receipt image contains the cashier's active receipt.

The receipt image is suitable to use when a receipt representation should be obtain to print a finalized transaction or to obtain a representation suitable for other devices, e.g. a monitoring attendant.

Authorizations:
BearerAuth
path Parameters
receiptId
required
integer <int64>
Example: 1

The receipt ID

sessionId
required
string

The session ID

query Parameters
format
string
Default: "TEXT"
Enum: "HTML" "HTML5" "JAVAPOS" "TEXT"

The receipt image format

widthBudget
integer <int32>
Default: -1
Example: widthBudget=48

The printer width budget

Responses

Response samples

Content type
application/json
{
  • "format": "TEXT",
  • "id": 123,
  • "personalData": {
    },
  • "receipts": [
    ],
  • "status": "ACTIVE"
}

Suspend the transaction

Authorizations:
BearerAuth
path Parameters
receiptId
required
integer <int64>
Example: 1

The receipt ID

sessionId
required
string

The session ID

Request Body schema: application/json

Empty request body

Schema not provided

Responses

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Validate the transaction

This operation validates all postponed item validations in the transaction.

Authorizations:
BearerAuth
path Parameters
receiptId
required
integer <int64>
Example: 1

The receipt ID

sessionId
required
string

The session ID

Request Body schema: application/json

Optional input parameters

Array of objects (PosParameter)

The input parameters list

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Sales management

Resources to perform sales of products and services

Register an entity

Register an entity in the transaction.

Authorizations:
BearerAuth
path Parameters
receiptId
required
integer <int64>
Example: 1

The receipt ID

sessionId
required
string

The session ID

Request Body schema: application/json

The entity input.

One of
required
object (Input)

Representation of input sent to the system.

Array of objects (PosParameter)

The input parameters

Responses

Request samples

Content type
application/json
Example
EntityInput
EntityInput
TenderInput
{
  • "originalPOSIdentity": {
    }
}

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Modify an existing entity

Modify an existing entity.

Authorizations:
BearerAuth
path Parameters
entityId
required
integer <int64>
Example: 11

The ID of the entity to void

receiptId
required
integer <int64>
Example: 1

The receipt ID

sessionId
required
string

The session ID

Request Body schema: application/json

The modifier to apply

boolean
boolean

A boolean property value

date
string <date-time>

A date property value

decimal
number

A decimal parameter value

integer
integer <int32>

An integer property value

long
integer <int64>

A numeric long property value

name
string

A custom parameter name.

source
string (InputSource)
Default: "AUTO"
Enum: "AUTO" "MANUAL" "PROVIDED" "SELECTED"

Enumeration of potential input sources.

  • AUTO - Denotes input that has been automatically entered by the system in response to a user action. The input value has not been produced by the user.
  • MANUAL - Denotes manual user input.
  • SELECTED - Denotes input that has been selected from a list of options presented by the system.
  • PROVIDED - Denotes input provided by peripheral hardware. For example a connected scanner or scale.
text
string

A text property value

type
string
Enum: "QUANTITY" "WEIGHT" "VOLUME" "AREA" "LENGTH" "PRICE" "AMOUNT" "CUSTOMER_AGE" "KNOWN_CUSTOMER_AGE" "TARE_ID" "ENTITY_ID" "INPUT"

A pre-defined parameter type.

  • QUANTITY - Set with decimal property. Unit of measure is each.
  • WEIGHT - Set with decimal property. Default unit is kilograms.
  • VOLUME - Set with decimal property. Default unit is liters.
  • AREA - Set with decimal property. Default unit is square meters.
  • LENGTH - Set with decimal property. Default unit is meters.
  • PRICE - Set with decimal property. A monetary value.
  • AMOUNT - Set with decimal property. A monetary value.
  • CUSTOMER_AGE - Set with integer property. Age in years.
  • KNOWN_CUSTOMER_AGE - Set with boolean property. Indicates if the customer's age is known and satifies any rqeuired age restriction level.
  • TARE_ID - Set with text property. The tare ID.
  • ENTITY_ID - Set with long property. This is an Entity.id.
  • INPUT - Set with text property. If set, this is considered the user input.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Void an existing entity

Void an existing entity. If quantity isn't specified and the entity has a quantity different from one unit, the Transaction Engine will most likely prompt for the quantity to void.

Authorizations:
BearerAuth
path Parameters
entityId
required
integer <int64>
Example: 11

The ID of the entity to void

receiptId
required
integer <int64>
Example: 1

The receipt ID

sessionId
required
string

The session ID

query Parameters
quantity
number
Example: quantity=1

The optional quantity

Responses

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Operations

Resources to perform general-purpose operations, both with and without a transaction.

Execute a command

Execute a named command with optional input parameters. The recommended way to determine the command name to execute is to select a command from the MenuTree.

Authorizations:
BearerAuth
path Parameters
commandName
required
string

The name of the command to execute

sessionId
required
string

The session ID

Request Body schema: application/json

Optional command parameters

Array of objects (PosParameter)

The input parameters list

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Execute a command on a transaction

Execute a named command on an existing transaction with optional input parameters. The recommended way to determine the command name to execute is to select a command from the MenuTree.

Authorizations:
BearerAuth
path Parameters
commandName
required
string

The name of the command to execute

receiptId
required
integer <int64>
Example: 1

The receipt ID

sessionId
required
string

The session ID

Request Body schema: application/json

Optional Command parameters

Array of objects (PosParameter)

The input parameters list

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Poll for background changes

Use to poll for any changes that has occured in the background. If the client subscribes to its session event stream it should invoke this operation when a pollRequest event is received

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Request Body schema: application/json

Empty request body

Schema not provided

Responses

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Print a receipt text

Print a receipt text on a printer connected to the Transaction Engine. If no printer exists, this method may still have modified the session state, for example by creating a control transaction or by adding elements to the ongoing transaction.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Request Body schema: application/json

The text to print

source
required
string
Enum: "EFT" "UNKNOWN"

The print text source

text
string

The text to print, use new line separators to produce multi-line output

Responses

Request samples

Content type
application/json
{
  • "source": "EFT"
}

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Produce a receipt image

This is the recommended method to produce a printable receipt when the client controls the printer.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

query Parameters
format
string
Default: "TEXT"
Enum: "HTML" "HTML5" "JAVAPOS" "TEXT"

The receipt image format

widthBudget
integer <int32>
Default: -1
Example: widthBudget=-1

The printer width budget

Request Body schema: application/json

The text to print

source
required
string
Enum: "EFT" "UNKNOWN"

The print text source

text
string

The text to print, use new line separators to produce multi-line output

Responses

Request samples

Content type
application/json
{
  • "source": "EFT"
}

Response samples

Content type
application/json
{
  • "format": "TEXT",
  • "id": 123,
  • "personalData": {
    },
  • "receipts": [
    ],
  • "status": "ACTIVE"
}

Calculate rescan results

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Request Body schema: application/json

The rescan entity input

partialRescan
required
boolean

Flag denoting if this is a partial rescan

Array of objects (RescanItem)

List of rescanned items (scanned by the cashier)

Array of objects (RescanItem)

List of self-scanned items (scanned by the customer)

Responses

Request samples

Content type
application/json
{
  • "partialRescan": false
}

Response samples

Content type
application/json
{
  • "differences": [
    ],
  • "success": true
}

Resume a transaction

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Request Body schema: application/json

The resume request

transactionId
string

The ID of the transaction to resume

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Prompt handling

Prompt handling

Get the prompt request

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Responses

Response samples

Content type
application/json
{
  • "attendable": false,
  • "cancelAllowed": true,
  • "code": "item.control.flag.message",
  • "choices": [
    ],
  • "defaultValue": "",
  • "inputAllowed": false,
  • "message": "Microwave oven (998): Please check inside the owen for hidden items.",
  • "severity": "INFO",
  • "title": "Control Item",
  • "type": "MESSAGE"
}

Submit a prompt response

Submit a prompt response to a pending prompt request. The response must match the prompt code of the pending prompt.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Request Body schema: application/json

The prompt response

object (AttendantResponseEvent)
cancelled
boolean

Flag to cancel the prompt. If set, the prompt should be cancelled. This means that the operator backed out of the use case.

closedFromServer
boolean

Flag to be used when the prompt was closed from a PromptCloseEvent

code
required
string

The code of the prompt request

object (Input)

Representation of input sent to the system.

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "empty": true,
  • "prompt": {
    },
  • "receipt": {
    }
}

Status events

Resources to subscribe to asynchronous push events that updates the status.

Subscribe to status events

Open a SSE stream to receive status events. The event stream can be consumed using an EventSource. For bearer token support, consider using a Polyfill such as event-source-polyfill.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

header Parameters
Last-Event-ID
integer <int32>
Default: -1
Example: 3

The last event ID received by the client

Responses

Poll for status events

Long-poll for status events. The long-polling API can be used instead of SSE for clients that can't support SSE for some reason.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

query Parameters
timeout
integer <int32>
Default: 30
Example: timeout=30

The poll timeout in seconds

header Parameters
Last-Event-ID
integer <int32>
Default: -1
Example: 3

The last event ID received by the client

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "lastEventId": 21
}

Reference data

Resources to access store reference data.

Get input information

Get input information for any arbitrary input. Use to to determine if a barcode represents an item and to extract the weight or price embedded in the barcode. If the barcode doesn't represent an item, isn't a proper barcode or a barcode with illegal contents, it will be returned as an UNDEFINED input type.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

query Parameters
input
string

Input possibly representing an item, typically a scanned barcode

header Parameters
If-None-Match
string

Allows a 304 Not Modified to be returned if content is unchanged, see ETag

Responses

Response samples

Content type
application/json
{
  • "card": {
    },
  • "data": {
    },
  • "item": {
    },
  • "type": "ITEM"
}

Get the available tender types

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

header Parameters
If-None-Match
string

Allows a 304 Not Modified to be returned if content is unchanged, see ETag

Responses

Response samples

Content type
application/json
{
  • "types": [
    ]
}

User interface

Resources for user interface menu structures etc.

Get the default menu tree

Get the default menu tree. The tree contains an ordered list of nodes that clients can access as tree structure. The leaf-nodes represents commands that can be executed on the POS. The menu is authorized for the active user and should be reloaded on every sign-on.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

Responses

Response samples

Content type
application/json
{
  • "choices": [
    ],
  • "name": "string"
}

Get a named menu tree

Get a named menu tree. The tree contains an ordered list of nodes that clients can access as tree structure. The leaf-nodes represents commands that can be executed on the POS. The menu is authorized for the active user and should be reloaded on every sign-on.

Authorizations:
BearerAuth
path Parameters
name
required
string

The name of the resource

sessionId
required
string

The session ID

header Parameters
If-None-Match
string

Allows a 304 Not Modified to be returned if content is unchanged, see ETag

Responses

Response samples

Content type
application/json
{
  • "choices": [
    ],
  • "name": "string"
}

Get the price lookup tree

Get the price lookup (PLU) tree for the client. The returned root node contains a tree hierarchy with categories of items. The leaf nodes are items that which can be registered in transaction. Clients should reload the PLU tree between each receipt to find updates. Use cache headers to avoid loading the tree when nothing has changed.

Authorizations:
BearerAuth
path Parameters
sessionId
required
string

The session ID

query Parameters
useFirstBestMatch
boolean
Default: false
Example: useFirstBestMatch=false

If multiple identities exists, only use the first one

header Parameters
If-None-Match
string

Allows a 304 Not Modified to be returned if content is unchanged, see ETag

Responses

Response samples

Content type
application/json
{
  • "choices": [
    ]
}

Image resources

Resources to access images referenced from reference data.

Load a PLU icon

Load a PLU icon. Use the If-Modified-Since request header to avoid fetching images already cached at the client.

path Parameters
imageId
required
string

The PLU icon name, excluding file ending

header Parameters
If-Modified-Since
string

Allows a 304 Not Modified to be returned if content is unchanged

Responses

Load a skin image

Load a skin image. Use the If-Modified-Since request header to avoid fetching images already cached at the client.

header Parameters
If-Modified-Since
string

Allows a 304 Not Modified to be returned if content is unchanged

Responses