销售单据接口文档

销售单据接口

银豹销售单据会覆盖线下收银、线上订单转收银、退货和反结账等多种场景。先理解下面 4 个核心规则，再对接。

01 线下收银

门店直接完成收银后，会生成一笔标准销售单据，这是最基础、也是最常见的对接场景。

02 线上订单

美团、饿了么、抖音、小程序等线上订单在门店完成收银后，同样会生成销售单据；其中 webOrderNo 表示线上订单号(网单号)。

03 退货单据

发生退货时，系统会新增一笔退货单据，可以通过 refund=1 快速识别这类数据。

退货：比如买了5瓶水，每瓶2元，支付10元（原单据），觉得买多了，退了3瓶，退回6元（退货单据）。

04 反结账(作废)

反结账不会生成新的单据，而是直接把原单据的 reversed 更新为 1，表示该单据已被反结账处理。

反结账：比如买了5瓶水，每瓶2元，支付10元,顾客突然5瓶都不想要了，店员执行反结账，反结账后会把10元原路退给客户。

查询销售单据

POST

/openapi/v3/ticket/increment-page

用于按主键游标分页查询销售单据，可按需返回明细行、支付记录、明细属性。

请求参数

参数	类型	必填	说明
`account`	string	是	业务门店账号，表示本次查询对应哪家门店。
`uid`	long	否	按销售单据 UID 精确查询。
`customerUid`	long	否	按会员 UID 查询某个会员的销售单据。
`sn`	string	否	按销售单据流水号精确查询。
`webOrderNo`	string	否	按网单号精确查询。
`reversed`	int	否	按是否反结账（作废）查询，`0` 非反结账单据，`1` 反结账单据。
`refund`	int	否	按是否退货单据查询，`0` 非退货单据，`1` 退货单据。
`datetimeBegin`	string	否	销售时间开始，格式 `yyyy-MM-dd HH:mm:ss`，包含该时间。
`datetimeEnd`	string	否	销售时间结束，格式 `yyyy-MM-dd HH:mm:ss`，不包含该时间，必须大于 `datetimeBegin`。
`lastId`	long	否	翻页游标。首次传 `0` 或不传；后续传上一次响应中的 `nextLastId`。
`order`	string	否	排序方向，仅支持 `asc`、`desc`，默认 `asc`。
`limit`	int	否	分页大小，默认 `100`，最大 `100`，超过按 `100` 处理。
`needCustomerInfo`	boolean	否	传 `true` 时返回会员基础信息。
`needTicketPayments`	boolean	否	传 `true` 时返回支付记录。
`needPrepaidCard`	boolean	否	传 `true` 且 `needTicketPayments=true` 时，预付卡支付记录返回预付卡列表。
`needTicketItems`	boolean	否	传 `true` 时返回销售单商品明细。
`needTicketItemAttributes`	boolean	否	传 `true` 时返回明细属性。
`needProductMainImage`	boolean	否	传 `true` 时返回销售单商品封面；仅商品有设置封面时返回。
`needProductBarcode`	boolean	否	传 `true` 时返回销售单商品条码；仅商品表存在对应商品时返回。
`needTicketRelations`	boolean	否	传 `true` 时返回退货/原单关系。
`needTableInfo`	boolean	否	传 `true` 时返回桌台信息。
`needCustomerBalanceUsedLog`	boolean	否	传 `true` 时返回会员余额使用流水。

业务说明

传 uid、customerUid、sn、webOrderNo 中任一字段时，按精准查询计费，基础消耗 100 token，每开启一个扩展返回开关 need* 额外消耗 20 token。
未传以上定位字段时，按范围查询计费，基础消耗 800 token，每开启一个扩展返回开关 need* 额外消耗 50 token。
传 needTicketRelations=true 时，退货单据（refund=1）返回 originalTicketUid，销售单据返回 refundTicketUids。

请求示例

{
  "account": "store001",
  "uid": 202604010001,
  "customerUid": 3002001001,
  "sn": "XS202604010001",
  "webOrderNo": "WEB202604010001",
  "reversed": 0,
  "refund": 0,
  "datetimeBegin": "2026-04-01 00:00:00",
  "datetimeEnd": "2026-04-02 00:00:00",
  "lastId": 0,
  "order": "asc",
  "limit": 100,
  "needCustomerInfo": true,
  "needTicketItems": true,
  "needTicketPayments": true,
  "needPrepaidCard": true,
  "needTicketItemAttributes": false,
  "needTicketRelations": true,
  "needProductMainImage": true,
  "needProductBarcode": true,
  "needTableInfo": true,
  "needCustomerBalanceUsedLog": true
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "301",
        "uid": "202604010001",
        "cashierUid": "90001",
        "customerUid": "3002001001",
        "customerInfo": {
          "uid": "3002001001",
          "number": "VIP0001",
          "name": "张三",
          "tel": "13800138000",
          "money": "98.50",
          "point": "2560"
        },
        "sn": "XS202604010001",
        "datetime": "2026-04-01 11:00:00",
        "totalAmount": 58.00,
        "totalProfit": 16.30,
        "discount": 9.50,
        "reversed": 0,
        "refund": 0,
        "rounding": 0.00,
        "webOrderNo": "WEB202604010001",
        "tableInfo": {
          "tableNumber": "A01",
          "tableName": "大厅1号桌",
          "tableCardNo": "088"
        },
        "customerBalanceUsedLogs": [
          {
            "operateType": 1,
            "usedMoney": 58.00,
            "usedGiftMoney": 8.00,
            "principal": 50.00
          }
        ],
        "ticketItems": [
          {
            "id": "401",
            "name": "可乐500ml",
            "buyPrice": 2.20,
            "sellPrice": 3.50,
            "customerPrice": 3.20,
            "quantity": 2,
            "discount": 10.00,
            "customerDiscount": 9.50,
            "isCustomerDiscount": 1,
            "datetime": "2026-04-01 11:00:00",
            "sellAmount": 7.00,
            "totalAmount": 6.65,
            "totalProfit": 2.25,
            "ticketUid": "202604010001",
            "productUid": "1002003001",
            "productMainImage": "https://img.pospal.cn/product/1002003001.jpg",
            "productBarcode": "690000000001",
            "guiderUid": "80001",
            "promotionRuleUid": "70001",
            "productAttribute1": "常温",
            "productAttribute2": "500ml",
            "ticketItemAttributes": [
              {
                "productAttributeUid": "50001",
                "attributeGroup": "规格",
                "attributeName": "容量",
                "attributeValue": "500ml",
                "quantity": 2
              }
            ]
          }
        ],
        "ticketPayments": [
          {
            "payMethod": 1,
            "payMethodName": "现金支付",
            "amount": 30.00
          },
          {
            "payMethod": 48,
            "payMethodName": "预付卡支付",
            "amount": 28.00,
            "prepaidCards": [
              {
                "cardUid": "60010001",
                "cardNumber": "PC0001",
                "usedBalance": 18.00
              },
              {
                "cardUid": "60010002",
                "cardNumber": "PC0002",
                "usedBalance": 10.00
              }
            ]
          }
        ]
      }
    ],
    "hasMore": false,
    "nextLastId": "301"
  }
}

返回字段说明

status、errorCode 及分页公共字段请参考“公共响应格式”，此处仅补充 result.list[] 及扩展对象。

字段	类型	说明
`id`	string	销售单主键 ID，可作为下一页游标来源。
`uid`	string	销售单业务 UID。
`cashierUid`	string	收银员 UID。
`customerUid`	string	会员 UID；散客单据时可能为空。
`customerInfo`	object	会员基础信息，需传 `needCustomerInfo=true`。
`sn`	string	销售单号。
`datetime`	string	销售时间。
`totalAmount`	decimal	销售总金额。
`totalProfit`	decimal	销售总利润。
`discount`	decimal	整单折扣。
`payMethod`	string	主支付方式描述。
`reversed`	int	是否反结账`1` 是 `0` 否。
`refund`	int	是否退货单据`1` 是 `0` 否。
`originalTicketUid`	string	退货单据对应的原销售单据 UID；需传 `needTicketRelations=true`。
`refundTicketUids`	array<string>	销售单据对应的退货单据 UID 列表；需传 `needTicketRelations=true`。
`rounding`	decimal	抹零金额。
`webOrderNo`	string	网单号。
`sysUpdateTime`	string	系统更新时间。
`tableInfo`	object	桌台信息，需传 `needTableInfo=true`。
`customerBalanceUsedLogs`	array<object>	会员余额使用流水，需传 `needCustomerBalanceUsedLog=true`。
`ticketItems`	array<object>	销售明细列表，需传 `needTicketItems=true`；若只开启 `needTicketItemAttributes`、`needProductMainImage` 或 `needProductBarcode` 也会一并返回。
`ticketPayments`	array<object>	支付记录列表，需传 `needTicketPayments=true`。

明细对象字段

对象	字段	类型	说明
`ticketItems[]`	`id`	string	销售明细主键 ID。
`ticketItems[]`	`name`	string	商品名称。
`ticketItems[]`	`buyPrice`	decimal	进价。
`ticketItems[]`	`sellPrice`	decimal	零售价。
`ticketItems[]`	`customerPrice`	decimal	会员价。
`ticketItems[]`	`quantity`	decimal	数量。
`ticketItems[]`	`discount`	decimal	明细折扣。
`ticketItems[]`	`customerDiscount`	decimal	会员折扣。
`ticketItems[]`	`isCustomerDiscount`	int	是否应用会员折扣。
`ticketItems[]`	`datetime`	string	明细销售时间。
`ticketItems[]`	`sellAmount`	decimal	挂牌金额。
`ticketItems[]`	`totalAmount`	decimal	实收金额。
`ticketItems[]`	`totalProfit`	decimal	明细利润。
`ticketItems[]`	`ticketUid`	string	所属销售单 UID。
`ticketItems[]`	`productUid`	string	商品 UID。
`ticketItems[]`	`productMainImage`	string	商品主图地址，需传 `needProductMainImage=true`；仅商品存在 `isCover=1` 的图片时返回。
`ticketItems[]`	`productBarcode`	string	商品条码，需传 `needProductBarcode=true`；仅商品表存在对应商品时返回。
`ticketItems[]`	`guiderUid`	string	导购 UID。
`ticketItems[]`	`promotionRuleUid`	string	促销规则 UID。
`ticketItems[]`	`productAttribute1`	string	商品属性 1。
`ticketItems[]`	`productAttribute2`	string	商品属性 2。
`ticketItems[]`	`ticketItemAttributes`	array<object>	明细属性列表，需传 `needTicketItemAttributes=true`。
`ticketItemAttributes[]`	`productAttributeUid`	string	商品属性 UID。
`ticketItemAttributes[]`	`attributeGroup`	string	属性分组。
`ticketItemAttributes[]`	`attributeName`	string	属性名称。
`ticketItemAttributes[]`	`attributeValue`	string	属性值。
`ticketItemAttributes[]`	`quantity`	decimal	属性对应数量。
`customerInfo`	`uid`	string	会员 UID。
`customerInfo`	`number`	string	会员卡号。
`customerInfo`	`name`	string	会员名称。
`customerInfo`	`tel`	string	会员手机号。
`customerInfo`	`money`	string	会员储值余额。
`customerInfo`	`point`	string	会员积分。
`ticketPayments[]`	`payMethod`	int	支付方式编码。
`ticketPayments[]`	`payMethodName`	string	支付方式名称。
`ticketPayments[]`	`amount`	decimal	支付金额。
`ticketPayments[]`	`prepaidCards`	array<object>	预付卡列表，仅 `needPrepaidCard=true` 且 `支付方式是预付卡支付` 时返回。
`prepaidCards[]`	`cardUid`	string	预付卡 UID。
`prepaidCards[]`	`cardNumber`	string	预付卡卡号。
`prepaidCards[]`	`usedBalance`	decimal	本张预付卡使用金额。
`tableInfo`	`tableNumber`	string	桌号。
`tableInfo`	`tableName`	string	桌名。
`tableInfo`	`tableCardNo`	string	牌号。
`customerBalanceUsedLogs[]`	`operateType`	int	操作类型：`1` 销售，`2` 退货，`3` 销售单据反结账，`4` 退货单据反结账，`5` 未收银网单作废（批发），`10` 网单支付，`11` 网单取消，`20` 自助单支付，`21` 自助单取消，`30` 挂单支付，`31` 挂单取消。
`customerBalanceUsedLogs[]`	`usedMoney`	decimal	会员余额使用总金额。销售返回正数，退货返回负数。
`customerBalanceUsedLogs[]`	`usedGiftMoney`	decimal	会员余额使用赠金。销售返回正数，退货返回负数。
`customerBalanceUsedLogs[]`	`principal`	decimal	会员余额使用本金，等于 `usedMoney - usedGiftMoney`。销售返回正数，退货返回负数。