Description
The KORONA.pos Client API is intended to extend the functionality of the POS. It allows external applications to interact with the cashier and even modify the current transaction. Common applications are:
- CRM Systems
- Loyalty System
- Order Management Systems
- Payment System
All External applications are contacted via HTTP call. A system call can be configured for as POST or GET to transfer current transaction data to the external system. If a system requires presenting a UI to the cashier the response has to be a valid HTML page.
The POS can be configured for external system calls using the following triggers:
- Button
- On Total (before payment)
- After Receipt Booking
- On Receipt Void
- On Receipt Rejection
Setup
1) Configure External System Call
Configure your external system call in the back office under Settings > External System Calls
Display URL are being displayed at the POS and require an HTML response. The System URL is called in the background and will always submit data via POST. Display applications can receive data via POST or via JavaScript and can submit their response via JavaScript whereas System URL applications need to submit responses as JSON. Depending on whether the external system requires UI you configure either a system URL or a display URL. All other parameters are optional.
2) Setup Button or Trigger
Assign the external system call to a button or trigger in the POS profile.
3) Update POS
Retrieve Master Data at the POS and restart the POS.
How to Retrieve Receipt Data via Javascript (Display URLs without POST only)
The POS has the ability to inject the receipt data via Javascript. This is the preferred method for all display call. Display calls are external systems that provide an HTML user interface to the cashier. Injecting the data via Javascript has the advantage that the page can be fully cached and therefore will improve load times for the cashier. Note: If the external system call has POST enabled the request data will be sent via as JSON POST and will not get injected via Javascript.
1) Add Javascript Library to Your HTML Header
Download the korona-plugin.js and include it in your HTML header (between and ) section:
<script type="text/javascript" src="korona-plugin-api.js"></script>2) Add A Load Function Which is Triggered After the Data is Injected
window.onload = function myOnLoadFunc() {
korona_plugin_api.ready(function myReadyFunc() {
// request data object:
var request = korona_plugin_api.request;
// receipt data object:
var receipt = korona_plugin_api.request.receipt;
});
};How to Trigger POS Functions via Javascript (Display URLs only)
Regardless of whether a display URL has POST enabled the response has to be submitted via Javascript. It is recommended to use the Javascript library for that. Please ensure you have added the korona–plugin-api.js added to your header section (see instructions above). For a full list of available functions please review the demo app.
korona_plugin_api.response.setReceiptCustomer({
firstName: "John",
lastName: "Doe",
phone: "555-123-4567",
number: "0123456",
email: "customer@koronapos.com"
});Once you have submitted all required actions you can close the app which will return the cashier back to the regular POS screen and execute the submitted actions.
korona_plugin_api.backToKorona();Note: Submitting actions does not deliver a result. If you need confirmation or an updated receipt you can submit a callback request at the end to get an updated request after the POS performed the actions.
korona_plugin_api.response.callExternalSystemByNumber({
externalSystemNumber: data.FollowUpExternalSystemCall
});How to Use System URLs
System URLs get called in the background and do not allow cashier interaction. For system URLs the POS will call the configured URL via POST. The POST body will consist of the request data in JSON format. If there is a response required the response need to also be in JSON format. Please ensure that the response header provides the content type JSON.
Content-Type: application/jsonSample Request Data
{
"application": {
"key": "Demo",
"version": "1.0"
},
"cashier": {
"name": "Jon Doe",
"number": "1"
},
"inputLine": "",
"organizationalUnit": {
"name": "Store 1",
"number": "1"
},
"pos": {
"name": "PoS 3",
"number": "03"
},
"receipt": {
"accountTransactions": [],
"cashier": {
"name": "Jon Doe",
"number": "1"
},
"counter": 0,
"creationTime": "2014-12-12T19:45:08.000+01:00",
"currency": {
"isoCode": "EUR",
"name": "Euro",
"number": "1"
},
"customerGroup": {
"name": "Demo sector",
"number": "1"
},
"modificationTime": "2014-12-16T19:12:11.144+01:00",
"number": "100563",
"organizationalUnit": {
"name": "Demo store 1",
"number": "1"
},
"pos": {
"name": "Kasse 3",
"number": "03"
},
"sales": [
{
"bookingTime": "2014-12-12T19:45:14.000+01:00",
"cashier": {
"name": "Jon Doe",
"number": "1"
},
"modifier": 1,
"description": "Coca Cola",
"sortingOrder": 0,
"hierarchicalOutline": "1",
"price": 2.95,
"product": {
"name": "Coca Cola",
"number": "1001"
},
"quantity": 5,
"recognitionCode": "1001",
"sector": {
"name": "Demo sector",
"number": "1"
},
"taxPayments": [
{
"amount": 2.35,
"taxRate": 19,
"vat": true
}
],
"total": {
"gross": 14.75,
"net": 12.4,
"value": 14.75
}
},
{
"bookingTime": "2014-12-12T19:45:20.000+01:00",
"cashier": {
"name": "Jon Doe",
"number": "1"
},
"modifier": 2,
"description": "Fanta",
"sortingOrder": 1,
"hierarchicalOutline": "2",
"price": 3,
"product": {
"name": "Fanta",
"number": "1002"
},
"quantity": 1,
"recognitionCode": "1002",
"sector": {
"name": "Demo sector",
"number": "1"
},
"taxPayments": [
{
"amount": 0.48,
"taxRate": 19,
"vat": true
}
],
"total": {
"gross": 3,
"net": 2.52,
"value": 3
}
},
{
"bookingTime": "2014-12-12T19:45:34.000+01:00",
"cashier": {
"name": "Jon Doe",
"number": "1"
},
"description": "Sprite",
"sortingOrder": 2,
"hierarchicalOutline": "3",
"price": 3.95,
"product": {
"name": "Sprite",
"number": "1003"
},
"quantity": 1,
"recognitionCode": "1003",
"sector": {
"name": "Demo sector",
"number": "1"
},
"taxPayments": [
{
"amount": 0.63,
"taxRate": 19,
"vat": true
}
],
"total": {
"gross": 3.95,
"net": 3.32,
"value": 3.95
}
},
{
"bookingTime": "2014-12-15T21:10:09.000+01:00",
"cashier": {
"name": "Jon Doe",
"number": "1"
},
"description": "Fanta",
"modifier": 4,
"sortingOrder": 3,
"hierarchicalOutline": "4",
"price": 3,
"product": {
"name": "Fanta",
"number": "1002"
},
"quantity": 1,
"recognitionCode": "1002",
"sector": {
"name": "Demo sector",
"number": "1"
},
"taxPayments": [
{
"amount": 0.48,
"taxRate": 19,
"vat": true
}
],
"total": {
"gross": 3,
"net": 2.52,
"value": 3
}
}
],
"total": {
"gross": 24.7,
"net": 20.76,
"value": 24.7
},
"voided": false
},
"systemCurrency": {
"isoCode": "EUR",
"name": "Euro",
"number": "1"
},
"zcounter": 24
}Sample Response Data
{
"actions": [
{
"type": "addPaymentAction",
"inputAmount": "12.56",
"paymentMethodNumber": "2",
"balanceInfo": "35.12",
"paymentCardInformation": {
"number": "******234",
"holderName": "John Doe"
}
},
{
"type": "displayMessageAction",
"level": "INFO",
"text": "Payment was approved!"
}
],
"application": {
"key": "Demo App",
"version": "1.0"
}
}
