Extension APIs​

This article introduces how to use the JavaScript APIs provided by SHOPLINE POS to implement Web extensions on the POS app page, allowing you to interact with the native features of SHOPLINE POS.

API usage guide​

Requirements​

Before you begin, make sure you meet the following requirements:

• You have created a development store.
• You have created an app in the SHOPLINE Partner Portal.
• You have created a Web extension for your public app.
• Use SHOPLINE POS version 2.15.0 or above.

Integration procedure​

Step1: Import the SDK​

Include the JavaScript SDK in your project by specifying the version number in the script tag as shown below:

<!-- Specify the version -->
<script src="https://cdn.myshopline.com/sl/sdk/sl-jssdk-1.0.35.mini.js"></script>

Step 2: Call APIs​

API call example​

Use the posapp module in the SDK to integrate APIs. You can access the APIs under the posapp module through the global variable shoplineAppBridge.

The following code and accompanying screenshot show how to use the [openWebWindow](https://shopline.yuque.com/xple8g/mcb268/usk76th9ywoztk7w#Extpl) API to open your app in half screen.

<!-- window.shoplineAppBridge: global variable -->
<!-- posapp: module name -->
<!-- 'openWebWindow': feature -->
<!-- { url : localurl, }: input parameter -->
<!-- then((res): a synchronous callback; res response parameters -->
<!-- {'code': Int, 'msg': string, 'timestamp': Number, 'data': Obj\} -->
shoplineAppBridge.posapp('openWebWindow', { url : localurl, }).then((res) => {
  
}                                                                    

API response example​

A response example of an API call is as follows:

{
  code: 0, 
  msg: "", 
  timeStamp: 1729822782000,
  data: {} 
}

Examples​

API call example​

<script type="text/javascript">
  function openWebWindow() {
    var url = "https://xxxxxxxx";
    window.shoplineAppBridge.posapp('openWebWindow', {"url":url,"style":1,"position":{"x":0.1,"y":0.05,"width":0.8,"height":0.9}}).then((res) => {
    
        // Example res = { "code":0, "timeStamp":1730276377000}
        var jsonRes = JSON.stringify(res);
        if (jsonRes['code'] == 0) {
          // Your processing logic
        }
    });
  }
</script>

Event callback example​

<script type="text/javascript">
  function POSEvent_deviceNetworkStatus(res) {
    
    // Example res = { "code":0,"data":{"connectionStatus":"wifi"} }
    var jsonRes = JSON.stringify(res);
    if (jsonRes['code'] == 0) {
      
      if (jsonRes['data']['connectionStatus'] == "wifi") {
        // Your processing logic
      }
    }
  }
</script>

API references​

UI operations​

The following are APIs related to UI operations.

openWebWindow​

Use this API to pop up a web window, with customizable window position and size. You need to pass in the URL of the web page that you wish to open.

• Request parameters

• Response parameters

closeWebWindow​

Use this API to close the Web window.

• Request parameters: none
• Response parameters

showToast​

Use this API to display essential text information as a fixed toast notification at the center of the Web window.

• Request parameters

• Response parameters

enablePullRefresh​

Use this API to enable or disable the pull-to-refresh functionality for the window. The functionality is disabled by default.

• Request parameters

• Response parameters

setBackMode​

If the Web window includes a navigation bar with a back button, use this API to define the behavior of the back button. There are two supported actions upon clicking the back button:

• It closes the Web window directly.
• It navigates to the previous page of the Web window.

If not set, the default behavior is to close the Web window directly.

• Request parameters

• Response parameters

Device information​

getDeviceNetworkStatus​

Use this API to get the network status of the mobile device.

• Request parameters: none
• Response parameters

POSEvent_deviceNetworkStatus​

Use this API to listen for the network status of the mobile device. When the network status changes, this API will notify the Web window page.

• Request parameters: none
• Response parameters

getDeviceInfo​

Use this API to get the basic information about the mobile device.

• Request parameters: none
• Response parameters

getDeviceLanguage​

Use this API to get the language setting from SHOPLINE POS. If you detect any changes in the language settings, you can update the language settings in the POS app accordingly.

• Request parameters: none
• Response parameters

POSEvent_deviceLanguage​

Use this API to listen for language setting changes in SHOPLINE POS. Upon detecting a change, this API will notify the Web window page. You can monitor this notification to retrieve language information, ensuring your app stays in synchronization with the language settings of the SHOPLINE POS.

• Request parameters: none
• Response parameters

POS information​

getPOSInfo​

Use this API to get the basic information about the merchant's POS system, such as the information about the account, store, branch store, and staff.

• Request parameters: none
• Response parameters

POSEvent_POSInfo​

Use this API to listen for the basic information changes about the merchant's POS system, such as the information about the account, store, branch store, and staff. When there is a switch in stores or staff within the POS, this API will notify the Web window page.

• Request parameters: none
• Response parameters

getUDBInfo​

Use this API to get the basic information of the currently logged-in POS account.

• Request parameters: none
• Response parameters

getCustomHeader​

Use this API to obtain the header information of the POS server request. If you make subsequent requests to POS server APIs, include the following header information in HTTP requests.

• Request parameters: none
• Response parameters

Products​

getProducts​

Use this API to get the list of product IDs of the currently logged-in branch store.

• Request parameters

• Response parameters

getProductsInfo​

Use this API to get product details in bulk for the currently logged-in branch store.

• Request parameters

• Response parameters

Shopping cart​

getCartInfo​

Use this API to get the shopping cart information in the SHOPLINE POS.

• Request parameters: none
• Response parameters

POSEvent_CartInfo​

Use this API to listen for the data changes in the current shopping cart. When the pricing information in the cart changes, this API will notify the Web window page.

• Request parameters: none
• Response parameters

operateCartDiscountCode​

Use this API to add or delete a specified discount code from the shopping cart.

• Request parameters

• Response parameters

operateCartDiscount​

Use this API to add or delete a shopping cart discount for orders or products. It supports percentage-based and fixed-amount discounts.

• Request parameters

• Response parameters

operateCartProduct​

Use this API to add or delete products from the shopping cart.

• Request parameters

• Response parameters

operateCartCustomer​

Use this API to add or delete a customer from the shopping cart.

• Request parameters

• Response parameters

addCustomSales​

Use this API to add custom product information to the shopping cart.

• Request parameters

• Response parameters

Order​

getCurrentOrderId​

Use this API to get the ID of the last completed order, or a specific historical order ID when viewing order history.

• Request parameters: none
• Response parameters

POSEvent_orderCompleted​

Use this API to listen for the ID of the last completed order. When an order is successfully created, this API will notify the Web window page.

• Request parameters: none
• Response parameters

Hardware management​

getCurrentHardwareInfo​

Use this API to get information about the third-party hardware device connected by the SHOPLINE POS app.

• Request parameters: none
• Response parameters

POSEvent_currentHardware​

Use this API to listen for hardware device connections, detecting additions and removals. When there are changes, this API will notify the Web window page.

• Request parameters: none
• Response parameters

openAddHardwareView​

Use this API to access the device connection interface, which opens a new window for connecting third-party printer hardware, such as a receipt printer, simplifying the connection process.

• Request parameters

• Response parameters

sendPrinterCommand​

Use this API to send print information. It supports printing images encoded in the base64 format.

• Request parameters

• Response parameters

openCameraScan​

Use this API to open the camera on a mobile device for scanning barcodes. It supports both linear and QR code scanning. Upon successful scanning, an asynchronous callback will be triggered to return the scanned barcode string information.

• Request parameters: none
• Response parameters

openSharePanel​

Use this API to open the share panel.

• Request parameters

• Response parameters

API error codes​

After calling the API, if the returned error code is not 0, it indicates a failure in the API call. You can refer to the following table to check the specific reasons for the error based on the returned error codes.

Success code​

Common error codes​

Product related error codes​

Shopping cart related error codes​

Hardware related error codes​