扩展 APIs

介绍 SHOPLINE POS 应用页面如何使用 SHOPLINE POS 提供的 JavaScript API，来实现 Web 扩展。

当扩展开发者需要与 SHOPLINE POS 原生进行交互，可以使用此 API。

API使用指南​

要求​

• 你已经创建了一个 开发商店。
• 你已在 SHOPLINE 合作伙伴后台 中创建了应用程序。
• 你已经为你的应用 创建了 Web 扩展
• 使用 v2.15.0 及以上版本的 SHOPLINE POS

API调用步骤​

a.引包​

当前API版本需指定 js-sdk 的版本号

<!-- 指定版本号 -->
<script src="https://cdn.myshopline.com/sl/sdk/sl-jssdk-1.0.35.mini.js"></script>

b.API调用​

调用说明​

此 API 集成在 SDK 的 SHOPLINE POS APP 模块里面，开发者需要通过 SDK 的全局变量 shoplineAppBridge 来调用 posapp 模块的API，以下是调用示例和截图：

<!-- window.shoplineAppBridge 全局变量-->
<!-- posapp: 模块名-->
<!-- 'openWebWindow': 功能-->
<!-- { url : localurl, }: 入参-->
<!-- then((res): 异步callback；res返回参数-->
<!-- {'code': Int, 'msg': string, 'timeStamp': Number, 'data': Obj\} -->
shoplineAppBridge.posapp('openWebWindow', { url : localurl, }).then((res) => {
}

返回的通用格式说明​

API 调用会返回以下固定的格式：

• code：API 调用返回的错误码，可参考 错误码 部分说明
• msg：API 调用返回的错误信息，code 非 0 时返回
• timeStamp：API 调用返回时刻的时间戳，13 位毫秒级时间戳
• data：API 调用返回的结果，具体可参考 API参考文档

{
  code: 0, // 字段类型 number
  msg: "", // 字段类型 string
  timeStamp: 1729822782000, // 字段类型 number
  data: {} // 字段类型 object
}

API调用样例​

调用示例​

如下代码样例展示了[openWebWindow]的调用:

<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) => {
        // 示例 res = { "code":0, "timeStamp":1730276377000}
        var jsonRes = JSON.stringify(res);
        if (jsonRes['code'] == 0) {
          // 处理结果
        }
    });
  }
</script>

事件回调示例​

<script type="text/javascript">
  function POSEvent_deviceNetworkStatus(res) {
    // 示例 res = { "code":0,"data":{"connectionStatus":"wifi"} }
    var jsonRes = JSON.stringify(res);
    if (jsonRes['code'] == 0) {
      if (jsonRes['data']['connectionStatus'] == "wifi") {
        // 处理结果
      }
    }
  }
</script>

API参考文档​

UI操作​

以下是关于 UI 操作相关的 API。

openWebWindow​

在当前页面弹出 Web 窗口，可以自定义窗口位置和大小。需要传入需要打开的 Web 页面链接。

• 入参

• 出参

示例：

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) => {
        var jsonRes = JSON.stringify(res);
    });;
}

function openWebWindow() {
    var url = "https://xxxxxxxx";
    window.shoplineAppBridge.posapp('openWebWindow', {"url":url,"style":0}).then((res) => {
        var jsonRes = JSON.stringify(res);
    });;
}

closeWebWindow​

关闭当前 Web 窗口。

• 入参：无
• 出参

showToast​

在当前 Web 窗口中间以固定的 Toast 形式显示需要提示的文本信息。

• 入参

• 出参

enablePullRefresh​

设置当前 Web 窗口是否支持下拉刷新功能，不设置默认为不支持下拉刷新功能。

• 入参

• 出参

setBackMode​

如果当前 Web 窗口包含导航栏，且导航栏有返回按钮，可以通过这个 API 设置当前 Web 窗口导航栏返回按钮行为模式。当前支持两种模式，一种是点击返回按钮直接关闭 Web 窗口，另一种是点击返回按钮返回 Web 窗口的上一级页面。不设置的话返回按钮默认为直接关闭 Web 视图页。

• 入参

• 出参

设备信息​

getDeviceNetworkStatus​

用于主动请求获取当前移动设备的网络状态。

• 入参：无
• 出参：

POSEvent_deviceNetworkStatus​

用于监听设备的网络状态。当应用网络状态改变时，将会通过这个 API 通知给 Web 窗口页面。

• 入参：无
• 出参：

getDeviceInfo​

用于获取当前设备的基本信息。

• 入参：无
• 出参：

getDeviceLanguage​

用于获取当前 SHOPLINE POS 的语言信息。

• 入参：无
• 出参：

POSEvent_deviceLanguage​

用于监听语言信息变动。当 SHOPLINE POS 应用的语言信息改变时，将会通过这个 API 通知给 Web 窗口页面。你可以监听此通知获取语言信息来跟 SHOPLINE POS 应用的语言保持同步。

• 入参：无
• 出参：

POS信息​

getPOSInfo​

用于获取当前登录的 POS 账号、店铺、门店、员工的基础信息。

• 入参：无
• 出参：

POSEvent_POSInfo​

用于监听当前登录的 POS 账号、店铺、门店、员工的基础信息。当 SHOPLINE POS 切换门店或者切换员工时，将会通过这个 API 通知给 Web 窗口页面。

• 入参：无
• 出参：

getUDBInfo​

用于获取登录 POS 账号的基础信息。

• 入参：无
• 出参：

getCustomHeader​

用于获取 POS 服务端网络请求的 Header 信息。如果后续需要请求 POS 服务端接口，则 HTTP 请求中需要带上以下 Header 信息。

• 入参：无
• 出参：

商品​

getProducts​

用于查询当前登录的门店下的商品 id 列表数据。

• 入参：

• 出参：

getProductsInfo​

用于批量查询当前登录的门店下的商品详情数据。

• 入参：

• 出参：

购物车​

getCartInfo​

用于获取 SHOPLINE POS 购物车的数据。

• 入参：无
• 出参：

此接口下，涉及到金额的数据字符串格式统一说明：为不带货币符号的价格字符串。

POSEvent_CartInfo​

用于监听当前的购物车数据变动。当购物车的在线计价结果更新时，将会通过这个 API 通知给 Web 窗口页面。

• 触发条件：在线计价更新
• 入参：无
• 出参：

operateCartDiscountCode​

用于给购物车添加或删除折扣码。

• 入参：

• 出参：

operateCartDiscount​

用于给购物车添加或删除订单或商品维度的折扣。支持百分比折扣和金额折扣。

• 入参：

• 出参

operateCartProduct​

用于给购物车添加或删除商品信息。

• 入参：

• 出参

operateCartCustomer​

用于给购物车添加或删除客户信息。

• 入参：

• 出参

addCustomSales​

用于给购物车添加自定义商品信息。

• 入参：

• 出参

订单​

getCurrentOrderId​

场景1: 购物车完成支付，在结帐完成页，会获该完成支付的 orderId。

场景2: 浏览历史订单详情，会获取到正常浏览订单的 orderId。

• 入参：无
• 出参

POSEvent_orderCompleted​

用于监听创建订单成功后返回的订单 id。当创建订单成功时，将会通过这个 API 通知给 Web 窗口页面。

• 入参：无
• 出参：

硬件管理​

getCurrentHardwareInfo​

用于获取 SHOPLINE POS 应用已连接的第三方的硬件设备信息。

• 入参：无
• 出参：

POSEvent_currentHardware​

用于监听当前已连接的硬件设备信息。当连接的硬件设备有增删时，将会通过这个 API 通知给 Web 窗口页面。

• 入参：无
• 出参：

openAddHardwareView​

用于跳转设备连接的界面，此API会在当前窗口新推出一个连接第三方打印机硬件设备的界面，用于后续连接操作。例如：收据打印机的连接界面。

入参：

出参：

sendPrinterCommand​

用于发送打印信息，支持打印 base64 编码格式图片信息。

入参：

出参：

openCameraScan​

用于打开移动设备摄像头扫描条码功能，支持线性条码和二维码扫描。当扫描成功会异步回调扫到的条码字符串信息。

• 入参：无
• 出参：

openSharePanel​

用于打开分享面板功能。

入参：

出参：

API响应码​

接口调用后返回的错误码 code 不为0，都为接口调用失败。开发者可以根据具体返回的错误码在以下表中查看错误原因。

成功码​

通用错误码​

商品相关错误码​

购物车相关错误码​

硬件相关错误码​