retail7 - Nach Oben

M E N Ü

retail7 - FAB Menu

r7 Connect

Integrating your external web app has never been easier.
Start your journey by exploring this quick introduction and api reference.

Quick Links:

Overview Architecture Functions Download Configuration Outlook

What is it all about?

The r7Connect App Enablement allows external web apps to be integrated directly into the cash register surface. These can communicate with the cash register via an API as well as access external web services. This allows functional extensions to be made very quickly without intervention in the core system. The web apps can provide the operator with additional functions or practical applications directly at the point of sale. Examples include customer and context-specific product recommendations, extended product information or the process-oriented integration of third-party systems.

The Architecture

A JavaScript application is hosted in a host application that serves as container. The r7Connect API provides functionality of the host application for the JavaScript application running in it. The JavaScript application contains the r7Connect SDK - which provides the connector and APIs to the core system. The connector establishes communication between APIs and the host, APIs provide the functionality bundled for different integration scenarios.

r7-connect Architecture 1
r7-connect Architecture 2

It differs how the JavaScript application is running in the host application. By default the JavaScript application is loaded in an iFrame. On desktop platforms there is also the possibility to run the application in a dedicated browser window if it's needed for technical reasons.

API Description & Functions

The r7Connect SDK file contains the R7Connector class which is needed to interact with the POS besides all needed internal functionality. A new instance can be created like in the following:

const r7Connector = new R7Connector();

Get Session Context

Method

await r7Connector.getSessionContext()

Parameters

/

Description

Returns the current session context of the underlying POS application. Includes information about store, user and till.

Example response object:

        {
            store: {
                id: "1001",
                name: "My store",
                street: "Friedrichstraße 204",
                postalCode: "10117",
                city: "Berlin",
                countryCode: "DE",
                locale: "de_DE",
                taxId: "123/456/789"
            },
            user: {
                id: "1001",
                name: "Cashier 1"
                },
            till: {
                id: "1001"
            }
        }
                

Get Item Info

Method

await r7Connector.getItemInfo(id);

Parameters

id - item ID

Description

Returns item information for the given item ID.

Example response object:

        {
            id: "1001",
            name: "Sample Item",
            unitPrice: 4.95,
            taxGroupId: "2"
        }
                

Register Item

Method

r7Connector.registerItem(id);

Parameters

id - item ID

Description

Registers the item with the given item ID.

Example (to come):

        {
            to: "come",
        }
                

Register External Item

Method

r7Connector.registerExternalItem(item);

Parameters

id, name, unitPrice, quantity, taxGroupId

Description

Registers an external item with the given information. The available tax groups and their respective IDs can be looked up in the management console under the following menu path "system-settings > taxes > tax groups".

Example item object to pass to the function:

        {
            id: "9001",
            name: "My Webshop Item",
            unitPrice: 2.4,
            quantity: 3,
            taxGroupId: "2"
        }
                

Register External Customer

Method

r7Connector.registerExternalCustomer(customer);

Parameters

id, externalId, name, street, postalCode, city, country, email, phone, taxId, vatId, comments

Description

Registers an external customer with the given information. Only id and name are mandatory fields.

Example customer object to pass to the function:

        {
            id: "991001",
            name: "John Doe",
            street: "Friedrichstraße 204",
            postalCode: "10117",
            city: "Berlin",
            country: "Germany",
            email: "[email protected]",
            phone: "+49 30 800 989 31 0",
            taxId: "123/456/789",
            vatId: "DE123456789",
            comments: "Contact by phone preferred."
        }
                

Get Current Transaction

Method

await r7Connector.getCurrentTransaction();

Parameters

/

Description

Returns the currently open retail transaction which complies to the ARTS Retail Transaction standard with custom extensions. Can be only called when an open retail transaction exists.

High level example response object:

        {
            Barcode: "0011001202206161001000005"
            BeginDateTime: "2022-06-16T05:19:39.000Z",
            BusinessDayDate: "2022-06-16T05:19:39.000Z",
            BusinessUnit: {UnitID: {…}, Address: {…}, …},
            CurrencyCode: "EUR",
            DataStructureVersion: 1,
            JournalTypeCode: "RetailTransaction",
            OperatorID: {WorkerID: "1001", …},
            OrgUnitID: "Nl525ju_4",
            OrganizationHierarchy: [],
            ReceiptDateTime: 2022-06-16T05:19:39.000Z,
            ReceiptDateTimeWithTimezone: "2022-06-16T07:19:39.717+02:00",
            ReceiptNumber: "5",
            RetailTransaction: {LineItem: […], …},
            StoreOrgUnitID: "Nl525ju_4",
            TillID: "1001",
            TrainingModeFlag: false,
            TransactionID: "1001202206161001000005",
            TypeCode: "SaleTransaction",
            VATRegistrationNumber: "123",
            WorkstationID: {value: "1001", …},
            meta: {…},
        }
                

Cancel Current Transaction

Method

r7Connector.cancelCurrentTransaction();

Parameters

/

Description

Cancels the currently open retail transaction. Can be only called when an open retail transaction exists.

Example (to come):

        {
            to: "come",
        }
                

Download and Example

I. Getting the SDK File

You can download the SDK file here :

Give me the SDK, Please

II. Quick Example

Just import the r7Connect SDK into your web page, instantiate the R7Connector class and you are ready to trigger functions on the retail7 POS. This sample can be found as well at http://content.retail7.io/appenablement/sdk/r7-connect-sample.html for your convenience for testing.

r7Connect Example

            <!DOCTYPE html>
            <html lang="en">
                <head>
                    <title>r7Connect</title>
                    <meta charset="utf-8" />
                    <meta name="viewport" content="width=device-width, initial-scale=1" />
                    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/clay/lib/css/atlas.css" />
                </head>
                <body>
                    <script src="r7-connect-sdk.min.js" type="text/javascript"></script>
                    <script type="text/javascript">
                        const r7Connector = new R7Connector();
                            
                        async function getSessionContext() {
                            const sessionContext = await r7Connector.getSessionContext();
                            logData("getSessionContext", sessionContext);
                        }
                
                        async function getItemInfo() {
                            const itemInfo = await r7Connector.getItemInfo("1001");
                            logData("getItemInfo", itemInfo);
                        }
                            
                        function registerItem() {
                            r7Connector.registerItem("1001");
                        }
                            
                        function registerExternalItem() {
                            r7Connector.registerExternalItem({
                                id: "12345",
                                name: "Sample Item",
                                unitPrice: 2.4,
                                quantity: 3
                            });
                        }
                
                        function registerExternalCustomer() {
                            r7Connector.registerExternalCustomer({
                                id: "991001",
                                externalId: "11111111",
                                name: "John Doe",
                                street: "Friedrichstraße 204",
                                postalCode: "10117",
                                city: "Berlin",
                                country: "DE",
                                email: "[email protected]",
                                phone: "+49 30 800 989 31 0",
                                taxId: "123/456/789",
                                vatId: "DE123456789",
                                comments: "Contact by phone preferred."
                            });
                        }
                
                        function logData(context, data) {
                            console.log(context, data);
                            const formattedJSON = JSON.stringify(data, "  ");
                            alert(`${context}:\n${formattedJSON}`);
                        }
                    </script>
                    <button class="btn btn-primary c-m-2" onclick="getSessionContext()">getSessionContext()</button>
                    <button class="btn btn-primary c-m-2" onclick="getItemInfo()">getItemInfo()</button>
                    <button class="btn btn-primary c-m-2" onclick="registerItem()">registerItem()</button>
                    <button class="btn btn-primary c-m-2" onclick="registerExternalItem()">registerExternalItem()</button>
                    <button class="btn btn-primary c-m-2" onclick="registerExternalCustomer()">registerExternalCustomer()</button>
                </body>
            </html>
                    

Configuration in your CLE

Configuration Step 1

To enhance an retail7 POS application with custom functionality using the r7Connect SDK, please navigate to the settings in your Management Console and open the App Enablement settings entry. You can find it in the settings section "POS".

r7-connect Configuration 1
r7-connect Configuration 2

Configuration Step 2

In the Settings list of the app enablement you can activate the functionality, define the Menu Title and one or more app enablement links which point to your web app(s). Additionally it can be assigned to dedicated organizational structure nodes, in order to control which app should be available on which POS. By default your settings will be available on every device.

Configuration Step 3

Once you saved the settings and restarted the POS, you should find your defined menu entry on the very bottom in the POS menu.

r7-connect Configuration 3
r7-connect Configuration 4

Configuration Step 4

Clicking on it leads to the overview of your defined menu entries.

Configuration Step 5

Selecting the menu entry of your choice shows the actual app enablement page you created. In this example we see the five buttons created in the code snippet example.

r7-connect Configuration 5

Outlook

Congratulations

You did it and your application should be running in your POS by now.

Soon it will be available to place a r7Connect app directly in the functional button groups and on the homescreen.

If you have any questions or suggestions please feel free to contact us.