---
title: "扩展APIs"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/point-of-sales/extension-ap-is'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/point-of-sales/extension-ap-is.md'
---
# 扩展 APIs

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

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

---

<a id="hQ0Sc"></a>
## API使用指南
<a id="rsbJ6"></a>
### 要求
+ 你已经创建了一个 [开发商店](https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/development-stores/overview.md)。
+ 你已在 [SHOPLINE 合作伙伴后台](https://developer.myshopline.com/home/index) 中创建了应用程序。
+ 你已经为你的应用 [创建了 Web 扩展](https://developer.shopline.com/zh-hans-cn/docs/apps/point-of-sales/create-a-web-extension.md)
+ 使用 v2.15.0 及以上版本的 SHOPLINE POS 

---

<a id="MqARX"></a>
### API调用步骤
<a id="sw2iv"></a>
#### a.引包
当前API版本需指定 js-sdk 的版本号

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

<a id="sTBsx"></a>
#### b.API调用
<a id="cRLGu"></a>
##### 调用说明
此 API 集成在 SDK 的 SHOPLINE POS APP 模块里面，开发者需要通过 SDK 的全局变量 shoplineAppBridge 来调用 posapp 模块的API，以下是调用示例和截图：

```javascript

<!-- 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) => {

}

```

<a id="Wc2wJ"></a>
##### 返回的通用格式说明
API 调用会返回以下固定的格式：

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

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

<a id="rtWzu"></a>
### API调用样例
<a id="WWlpn"></a>
#### 调用示例
如下代码样例展示了`[openWebWindow]`的调用:

```plain

<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>

```

<a id="jlh6G"></a>
#### 事件回调示例
```json
<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>
```

<a id="Z54OF"></a>
## API参考文档
<a id="HVfnY"></a>
### UI操作
以下是关于 UI 操作相关的 API。

<a id="Extpl"></a>
#### openWebWindow
在当前页面弹出 Web 窗口，可以自定义窗口位置和大小。需要传入需要打开的 Web 页面链接。

+ 入参

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| url |  | string | 是 | 需要打开的 web 页面链接 |
| style |  | number | 否 | 窗口样式枚举<br/><ul><li>`0`：全屏</li><li>`1`：自定义大小和位置的半窗，根据position来锚定位置和大小</li></ul> |
| position |  | object | 否 | 窗口位置，style为`1`时生效 |
|  | x | number | 否 | 横坐标，屏幕宽度比例<br/>取值范围：0-1，默认0 |
|  | y | number | 否 | 纵坐标，屏幕高度比例<br/>取值范围：0-1，默认0 |
|  | width | number | 否 | 窗口宽度，屏幕宽度比例<br/>取值范围：0-1，默认1，为1时跟屏幕宽度一致 |
|  | height | number | 否 | 窗口高度，屏幕高度比例<br/>取值范围：0-1，默认1，为1时跟屏幕高度一致 |


+ 出参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |




示例：

```json

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);
    });;
}
```



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

        var jsonRes = JSON.stringify(res);
    });;
}
```

<a id="yx552"></a>
#### closeWebWindow
关闭当前 Web 窗口。

+ 入参：无
+ 出参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |


<a id="K3vDS"></a>
#### showToast
在当前 Web 窗口中间以固定的 Toast 形式显示需要提示的文本信息。

+ 入参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| text | string | 是 | 提示的文本内容 |


+ 出参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |


<a id="Z4qpR"></a>
#### enablePullRefresh
设置当前 Web 窗口是否支持下拉刷新功能，不设置默认为不支持下拉刷新功能。

+ 入参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| enable | boolean | 是 |<ul><li>`true`：启用</li><li>`false`：禁用 </li></ul> |


+ 出参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |


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

+ 入参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| mode | number | 是 | 模式枚举<br/><ul><li>`0`：直接关闭 Web 视图页</li><li>`1`：返回上一级页面</li></ul> |


+ 出参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |


<a id="wtZgb"></a>
### 设备信息
<a id="mhi0m"></a>
#### getDeviceNetworkStatus
用于主动请求获取当前移动设备的网络状态。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 否 | code 为 0 的时候返回 |
|  | connectionStatus | string | 否 | 设备联网状态枚举<br/><ul><li>`wifi`：无线网</li><li>`wwan`：蜂窝网络</li><li>`unavailable`：无网络连接</li></ul> |


<a id="Aw8w1"></a>
#### POSEvent_deviceNetworkStatus
用于监听设备的网络状态。当应用网络状态改变时，将会通过这个 API 通知给 Web 窗口页面。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 是 | code 为 0 的时候返回 |
|  | connectionStatus | string | 是 | 设备联网状态枚举<br/><ul><li>`wifi`：无线网</li><li>`wwan`：蜂窝网络</li><li>`unavailable`：无网络连接</li></ul> |


<a id="Bfjbr"></a>
#### getDeviceInfo
用于获取当前设备的基本信息。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 否 | code 为 0 的时候返回 |
|  | deviceName | string | 否 | 设备名称<br/>例子：iPhone 14 Pro、Sunmi T2 |
|  | deviceId | string | 否 | 设备id<br/>例子：00:0C:29:01:98:27 |
|  | osVersion | string | 否 | 系统版本<br/>例子：17.2.1 |
|  | os | string | 否 | 系统类型枚举：<br/><ul><li>`Android`</li><li>`iOS`</li></ul> |
|  | appVersion | string | 否 | 当前设备安装的SHOPLINE POS 应用的版本号<br/>例子：2.15.0 |


<a id="YmjA6"></a>
#### getDeviceLanguage
用于获取当前 SHOPLINE POS 的语言信息。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 是 | code 为 0 的时候返回 |
|  | appLanguage | string | 是 | 应用当前显示语言枚举：<br/><ul><li>`en`：英语</li><li>`zh-Hans`：简体中文</li><li>`zh-Hant`：繁体中文</li><li>`ja`：日语</li></ul> |


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

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 是 | code 为 0 的时候返回 |
|  | appLanguage | string | 是 | SHOPLINE POS 应用当前显示语言枚举：<br/><ul><li>`en`：英语</li><li>`zh-Hans`：简体中文</li><li>`zh-Hant`：繁体中文</li><li>`ja`：日语</li></ul> |


<a id="F7X0p"></a>
### POS信息
<a id="CvKXv"></a>
#### getPOSInfo
用于获取当前登录的 POS 账号、店铺、门店、员工的基础信息。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 否 | code 为 0 的时候返回 |
|  | storeId | string | 否 | 店铺id |
|  | offlineStoreId | string | 否 | 门店id |
|  | posStaffId | string | 否 | 当前员工在 POS 中的专属 id |
|  | currencyCode | string | 否 | 店铺的货币代码，遵循 [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 为每种货币定义了由三个字母组成的代码 |
|  | currentStaffUid | string | 否 | 当前员工的用户id |
|  | loginStaffUid | string | 否 | 当前登录的 POS 账号 id |


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

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 否 | code 为 0 的时候返回 |
|  | storeId | string | 否 | 店铺 id |
|  | offlineStoreId | string | 否 | 门店 id |
|  | posStaffId | string | 否 | 当前员工在 POS 中的专属 id |
|  | uid | string | 否 | 当前登录的 POS 账号 id |


<a id="q0qCt"></a>
#### getUDBInfo
用于获取登录 POS 账号的基础信息。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 否 | code 为 0 的时候返回 |
|  | isLogin | boolean | 是 | 表示 SHOPLINE POS 是否登录。<br/><ul><li>`true`： 已登录</li><li>`false`：未登录</li></ul><br/>默认值：`false` |
|  | uid | string | 否 | 当前登录的账号id |
|  | otp | string | 否 | POS 服务端接口请求凭证，后续如果需要直接请求 POS 服务端的接口，可以用到，有效期为 1天，但该凭证只能使用 1 次用于校验。 |

<a id="VYjPm"></a>
#### getCustomHeader
用于获取 POS 服务端网络请求的 Header 信息。如果后续需要请求 POS 服务端接口，则 HTTP 请求中需要带上以下 Header 信息。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 否 | code 为 0 的时候返回 |
|  | deviceInfo | string | 否 | json 格式的字符串，包含一些设备相关的信息<br/>例如：```{"model":"iPad (9th generation)","brand":"Apple","os":"ios","deviceId":"xxxx","appVersion":"2.21.0","newDeviceId":"xxxx","osVersion":"15.4.1"} ```|
|  | uid | string | 否 | 当前登录的账号 id |
|  | otp | string | 否 | POS 服务端接口请求凭证，后续如果需要直接请求 POS 服务端的接口，可以用到。 |
|  | lang | string | 否 | app 当前显示语言枚举：<br/><ul><li>`en`：英语</li><li>`zh-hans-cn`：简体中文</li><li>`zh-hant-tw`：繁体中文</li><li>`ja`：日语</li></ul> |
|  | ticket | string | 否 | json 格式的字符串，包含一些店铺相关的信息<br/>例如：<br/>```{"posId":"xxxx","offlineStoreId":"xxxx","merchantId":"xxxx","posStaffId":"xxx","innerToken":"xxx","storeId":"xxx"}```|

<a id="urEkk"></a>
### 商品
<a id="kIuTt"></a>
#### getProducts
用于查询当前登录的门店下的商品 id 列表数据。

+ 入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| offlineStoreID | string | 是 | 请求查询的门店 id |
| queryString | string | 否 | 商品搜索关键词<br/>系统会一一匹配以下范围的内容：<br/><ul><li>商品名称</li><li>商品 SKU</li><li>商品条码</li><li>商品 SPU</li><li>商品厂商</li><li>商品摘要</li></ul>例子：`鞋子` |
| sortType | string | 否 | 结果列表排序方式枚举：<br/><ul><li>`RECENTLY_ADDED`：创建时间近-远。默认</li><li>`RECENTLY_ADDED_ASCENDING`：创建时间远-近</li><li>`ALPHABETICAL_A_TO_Z`：商品名称A-Z</li><li>`ALPHABETICAL_Z_TO_A`：商品名称Z-A</li></ul> |
| pageSize | number | 是 | 每页返回的商品数量<br/>取值范围：1 - 500 |
| pageNum | number | 是 | 请求的页码，从第 1 页开始<br/>取值范围：1 - 无限大 |


+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 0 - 成功 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 否 | code 为 0 的时候返回 |
|  | productIds | string[] | 否 | 商品 id 数组 |


<a id="pRihz"></a>
#### getProductsInfo
用于批量查询当前登录的门店下的商品详情数据。

+ 入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| productIds | string[] | 是 | 商品id数组，最大限制 500 个，建议搜索不超过 50 个。 |
| offlineStoreID | string | 是 | 查询的门店id |


+ 出参：

| 名称 | 二级 | 三级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- | --- |
| code |  |  | number | 是 | 错误码 |
| msg |  |  | string | 否 | 错误信息，code  非 0 时返回 |
| timeStamp |  |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  |  | object[] | 否 | 商品信息数组，code 为 0 的时候返回 |
|  | productId |  | string | 否 | 商品id |
|  | skus |  | object[] | 是 | 商品 SKU 信息数组 |
|  |  | skuId | string | 是 | SKU 的 id |
|  |  | locationPrice | Int | 是 | 门店价格 |
|  |  | serialNumber | string[] | 否 | 序列号数组 |

<a id="DvhlY"></a>
### 购物车
<a id="T3uwq"></a>
#### getCartInfo
用于获取 SHOPLINE POS 购物车的数据。

+ 入参：无
+ 出参：

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

> **备注**
>
> "100.00"在以人民币为货币单位的店铺表示人民币100块


| 名称 | 二级 | 三级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- | --- |
| code |  |  | number | 是 | 错误码 |
| msg |  |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  |  | object | 否 | code 为 0 的时候返回 |
|  | lineItems |  | object[] | 否 | 购物车商品行信息 |
|  |  | productId | string | 是 | 商品 id |
|  |  | skuId | string | 是 | SKU 的 id |
|  |  | finalPrice | string | 是 | 成交单价，不带货币符号的价格字符串。<br/>例如："100.00"在以人民币为货币单位的店铺表示人民币 100 块 |
|  |  | quantity | number | 是 | 加购数量 |
|  |  | finalLinePrice | string | 是 | 成交总价 |
|  | customer |  | object | 否 | 客户信息 |
|  |  | uid | string | 否 | 客户 id |
|  |  | email | string | 否 | 邮箱 |
|  |  | phone | string | 否 | 手机号 |
|  | valuation |  | object | 否 | 计价信息 |
|  |  | subtotal | string | 是 | 小计金额 |
|  |  | totalDiscounts | string | 否 | 优惠金额 |
|  |  | deductMemberPointAmount | string | 否 | 积分抵扣金额 |
|  |  | totalTax | string | 否 | 总消费税金额 |
|  |  | totalDuty | string | 否 | 关税金额 |
|  |  | taxesIncluded | bool | 否 | 商品价格是否包含税费（关税+消费税）<br/><ul><li>`true`：商品价格finalLinePrice包含税费</li><li>`false`：商品价格finalLinePrice不包含税费</li></ul> |
|  |  | totalTip | string | 否 | 小费金额 |
|  |  | adjustPrice | string | 否 | 被四舍五入掉的金额 |
|  |  | grandTotal | string | 是 | 总计金额 |
|  | note |  | string | 否 | 购物车的备注信息 |
|  | localDiscount |  | object | 否 | 本地折扣信息 |
|  |  | title | string | 否 | 折扣标题 |
|  |  | amount | string | 否 | 折扣金额 |
|  |  | percentage | string | 否 | 百分比折扣<br/>取值范围：0-1<br/>例子：0.25 |
|  | codeDiscounts |  | string[] | 否 | 购物车添加的折扣码数组 |

<a id="gmdAn"></a>
#### POSEvent_CartInfo
用于监听当前的购物车数据变动。当购物车的在线计价结果更新时，将会通过这个 API 通知给 Web 窗口页面。

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

| 名称 | 二级 | 三级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- | --- |
| code |  |  | number | 是 | 错误码 |
| msg |  |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  |  | number | 是 | 接口调用返回时间戳：13 位毫秒级时间戳 |
| data |  |  | object | 否 | code 为 0 的时候返回 |
|  | lineItems |  | object[] | 否 | 购物车商品行信息 |
|  |  | productId | string | 是 | 商品id |
|  |  | skuId | string | 是 | SKU的id |
|  |  | finalPrice | string | 是 | 成交单价，不带货币符号的价格字符串。<br/>例如："100.00"在以人民币为货币单位的店铺表示人民币 100 块 |
|  |  | quantity | number | 是 | 加购数量 |
|  |  | finalLinePrice | string | 是 | 成交总价 |
|  | customer |  | object | 否 | 客户信息 |
|  |  | uid | string | 否 | 客户 id |
|  |  | email | string | 否 | 邮箱 |
|  |  | phone | string | 否 | 手机号 |
|  | valuation |  | object | 否 | 计价信息 |
|  |  | subtotal | string | 是 | 小计金额 |
|  |  | totalDiscounts | string | 否 | 优惠金额 |
|  |  | deductMemberPointAmount | string | 否 | 积分抵扣金额 |
|  |  | totalTax | string | 否 | 总消费税金额 |
|  |  | totalDuty | string | 否 | 关税金额 |
|  |  | taxesIncluded | bool | 否 | 商品价格是否包含税费（关税+消费税）<br/><ul><li>`true`：商品价格finalLinePrice包含税费</li><li>`false`：商品价格finalLinePrice不包含税费</li></ul> |
|  |  | totalTip | string | 否 | 小费金额 |
|  |  | adjustPrice | string | 否 | 被四舍五入掉的金额 |
|  |  | grandTotal | string | 是 | 总计金额 |
|  | note |  | string | 否 | 购物车的备注信息 |
|  | localDiscount |  | object | 否 | 本地折扣信息 |
|  |  | title | string | 否 | 折扣标题 |
|  |  | amount | string | 否 | 折扣金额，和 `percentage` 两者只会返回一个。 |
|  |  | percentage | string | 否 | 百分比折扣，和 `amount` 两者只会返回一个。<br/>取值范围：0-1<br/>例子：0.25 |
|  | codeDiscounts |  | string[] | 否 | 购物车添加的折扣码数组 |


<a id="PgXH5"></a>
#### operateCartDiscountCode
用于给购物车添加或删除折扣码。

+ 入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| operateAction | string | 是 | 操作枚举：<br/><ul><li>`Add`：添加折扣码</li><li>`Clear`：删除折扣码</li></ul> |
| discountCode | string | 是 | 折扣码<br/>例子：ETIFRN8ODO8U |


+ 出参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 是 | 错误信息，code非0时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |


<a id="uZItv"></a>
#### operateCartDiscount
用于给购物车添加或删除订单或商品维度的折扣。支持百分比折扣和金额折扣。

+ 入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| operateAction | string | 是 | 操作枚举<br/><ul><li>`Add`：添加折扣</li><li>`Clear`：删除折扣</li></ul> |
| discountTitle | string | 否 | 折扣标题 |
| discountType | string | 否 | 折扣类型枚举：<br/><ul><li>`Percent`：百分比折扣</li><li>`Amount`：金额折扣</li></ul> |
| discountAmount | string | 否 | 折扣信息，货币单位为店铺设置的币种<br/>折扣类型为百分比折扣时传：0-1字符串<br/>折扣类型为金额折扣时传折扣金额："10.22" |
| discountDimension | string | 是 | 折扣维度枚举：<br/><ul><li>`Product`：商品维度折扣</li><li>`Order`：订单维度折扣</li></ul> |
| skuId | string | 否 | SKU的id<br/>当折扣维度为商品时，需要传此字段 |


+ 出参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 是 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |




<a id="o5Idy"></a>
#### operateCartProduct
用于给购物车添加或删除商品信息。

+ 入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| operateAction | string | 是 | 操作类型枚举<br/><ul><li>`Add`：添加商品</li><li>`Clear`：删除商品</li></ul> |
| skuId | string | 是 | SKU 的 id |
| serialCodes | string[] | 否 | SKU 的序列号数组 |
| quantity | number | 否 | 加购或删除数量<br/>取值范围：1-999 |


+ 出参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 是 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |


<a id="qkM5q"></a>
#### operateCartCustomer
用于给购物车添加或删除客户信息。

+ 入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| operateAction | string | 是 | 操作类型枚举<br/><ul><li>`Add`：添加客户</li><li>`Clear`：删除客户</li></ul> |
| customerId | string | 否 | 客户id<br/>当操作类型为`Add`的时候必传<br/>当操作类型为`Clear`的时候不用传，由于购物车只可能存在一个客户，会直接删除购物车已存在的客户信息， |


+ 出参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 是 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |


<a id="IIwgR"></a>
#### addCustomSales
用于给购物车添加自定义商品信息。

+ 入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| title | string | 否 | 自定义销售商品标题 |
| price | string | 是 | 加购金额，不带货币符号的价格字符串。<br/>例如："100.00"在以人民币为货币单位的店铺表示人民币100块 |


+ 出参

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 是 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |


<a id="Btjtc"></a>
### 订单
<a id="IOlrh"></a>
#### getCurrentOrderId
场景1: 购物车完成支付，在结帐完成页，会获该完成支付的 orderId。

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

+ 入参：无
+ 出参

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | code 描述 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 否 | code 为 0 的时候返回 |
|  | orderId | string | 否 | 订单 id |


<a id="VvNlF"></a>
#### POSEvent_orderCompleted
用于监听创建订单成功后返回的订单 id。当创建订单成功时，将会通过这个 API 通知给 Web 窗口页面。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | code 描述 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 是 | code 为 0 的时候返回 |
|  | orderId | string | 是 | 订单 id |


<a id="rv9qw"></a>
### 硬件管理
<a id="HMwLT"></a>
#### getCurrentHardwareInfo
用于获取 SHOPLINE POS 应用已连接的第三方的硬件设备信息。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object[] | 否 | code 为 0 的时候返回 |
|  | hardwareType | string | 否 | 硬件类型枚举：<br/><ul><li>`receiptPrinter`：收据打印机</li><li>`labelPrinter`：标签打印机</li></ul> |
|  | hardwareBrand | string | 否 | 硬件品牌枚举：<br/><ul><li>`star`</li><li>`sunmi`</li><li>`epson`</li><li>`feie`</li><li>`socket`</li><li>`brother`</li><li>`zebra`</li><li>`unknown`</li></ul>当不属于以上品牌的硬件设备，则统一返回`unknown` |
|  | name | string | 否 | 设备名称 |
|  | connectionType | string | 否 | 硬件使用的连接方式枚举：<br/><ul><li>`bluetooth`：蓝牙连接</li><li>`wifi`：WiFi连接</li><li>`LAN`：局域网连接</li><li>`usb`：usb连接</li></ul> |
|  | status | string | 否 | 硬件连接状态枚举：<br/><ul><li>`connected`：已连接</li><li>`unconnected`：未连接</li></ul> |

<a id="eV8Gd"></a>
#### POSEvent_currentHardware
用于监听当前已连接的硬件设备信息。当连接的硬件设备有增删时，将会通过这个 API 通知给 Web 窗口页面。

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object[] | 否 | code 为 0 的时候返回 |
|  | hardwareType | string | 否 | 硬件类型枚举：<br/><ul><li>`receiptPrinter`：收据打印机</li><li>`labelPrinter`：标签打印机</li></ul> |
|  | hardwareBrand | string | 否 | 硬件品牌枚举：<br/><ul><li>`star`</li><li>`sunmi`</li><li>`epson`</li><li>`feie`</li><li>`socket`</li><li>`brother`</li><li>`zebra`</li><li>`unknown`</li></ul>当不属于以上品牌的硬件设备，则统一返回`unknown` |
|  | name | string | 否 | 设备名称 |
|  | connectionType | string | 否 | 硬件使用的连接方式枚举：<br/><ul><li>`bluetooth`：蓝牙连接</li><li>`wifi`：WiFi连接</li><li>`LAN`：局域网连接</li><li>`usb`：usb连接</li></ul> |
|  | status | string | 否 | 硬件连接状态：<br/><ul><li>`connected`：已连接</li><li>`unconnected`：未连接</li></ul> |

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

入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| hardwareType | String | 是 | 硬件类型枚举：<br/><ul><li>`receiptPrinter`：收据打印机</li><li>`labelPrinter`：标签打印机</li></ul> |


出参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |


<a id="DCP5Z"></a>
#### sendPrinterCommand
用于发送打印信息，支持打印 base64 编码格式图片信息。

入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| printInfo | String | 是 | 只支持打印的图片数据：base64 编码格式数据 |
| printQuantity | number | 是 | 打印数量<br/>取值范围：1-999 |


出参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |

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

+ 入参：无
+ 出参：

| 名称 | 二级 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- | --- |
| code |  | number | 是 | 错误码 |
| msg |  | string | 否 | 错误信息，code 非 0 时返回 |
| timeStamp |  | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |
| data |  | object | 否 | code 为 0 的时候返回 |
|  | code | string | 否 | 扫到的条码数据 |


<a id="cALyp"></a>
#### openSharePanel
用于打开分享面板功能。

入参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| text | string | 否 | 分享文本 |
| imageUrl | string | 否 | 分享图片 url |
| imageFile | string | 否 | 分享图片文件，base64 |
| file | string | 否 | 分享文件，base64，仅支持 pdf |
| fileUrl | string | 否 | 分享文件 url，仅支持pdf |


出参：

| 名称 | 类型 | 是否必须 | 内容含义&备注 |
| --- | --- | --- | --- |
| code | number | 是 | 错误码 |
| msg | string | 否 | 错误信息，code 非0时返回 |
| timeStamp | number | 是 | 接口调用返回时间戳：13位毫秒级时间戳 |

<a id="NjCgm"></a>
## API响应码
接口调用后返回的错误码 code 不为0，都为接口调用失败。开发者可以根据具体返回的错误码在以下表中查看错误原因。

<a id="UViCI"></a>
### 成功码
| code | 备注 |
| --- | --- |
| 0 | 接口调用成功 |


<a id="DSyaY"></a>
### 通用错误码
| code | 备注 |
| --- | --- |
| 1 | 接口调用失败 |
| 1001 | URL 格式错误 |
| 1002 | 缺少参数 |
| 1003 | 参数类型错误 |
| 1004 | 当前用户没有权限调用 API，可检查当前登录的员工是否有权限操作该行为。 |


<a id="teqlL"></a>
### 商品相关错误码
| code | 备注 |
| --- | --- |
| 3001 | 根据 SkuId 找不到对应商品 |

<a id="w8EJs"></a>
### 购物车相关错误码
| code | 备注 |
| --- | --- |
| 6001 | 该折扣码不可使用 |
| 6002 | 该折扣码已被使用 |
| 6003 | 该商品不存在 |
| 6004 | 该客户不存在 |
| 6005 | 当前购物车为空 |
| 6006 | 购物车计价失败 |
| 6007 | 该折扣码使用失败 |
| 6008 | 购物车已使用离线计价，不可操作购物车 |
| 6009 | 购物车商品数量已达上限 |
| 6010 | 当前正在退款，不可操作购物车 |


<a id="Zyh6I"></a>
### 硬件相关错误码
| code | 备注 |
| --- | --- |
| 5001 | 硬件类型不支持 |
| 5002 | 未连接打印机 |
| 5003 | 图片解析失败 |
| 5004 | 图片下载失败 |
| 5005 | 文件解析失败 |
| 5006 | 文件下载失败 |
| 5007 | 获取摄像头权限失败 |