网单接口文档

新增网单

POST

客户有自己的商城或者小程序，将订单推送到开放平台，开放平台处理商品，会员，支付等数据后，将订单下发到银豹收银系统。客户在银豹收银系统完成 接单-厨打-配送-收银 等一系列操作。收银后，生成销售单据，并扣相应商品库存。

请求参数

参数	类型	必填	说明
account	string	是	业务门店账号；网单会写入该账号对应门店。
time	string	否	下单时间，格式 yyyy-MM-dd HH:mm:ss；不传默认当前时间。
orderNo	string	否	网单订单号，最大 32 位；建议不传，由银豹按默认规则生成。同一门店下不能重复。若客户传入自定义 orderNo，可在“网单/网络订单”界面搜索；但不符合银豹标准网单号格式时，不能在 POS “核销”界面通过网单号核销。
productOrderItems	array<object>	是	网单商品明细，至少 1 条，最多 200 条。
payments	array<object>	否	支付方式列表；建议别传,由接口按规则自动处理。
comment	string	否	订单备注。
contactAddress	string	否	订单联系地址；配送订单可传配送地址。
contactTel	string	否	订单联系人电话。
contactName	string	否	订单联系人姓名。
customerNumber	string	否	会员编号；传入时必须存在。
shippingFee	decimal	否	配送费，必须大于等于 0。
packageFee	decimal	否	打包费，必须大于等于 0。
serviceFee	decimal	否	服务费，必须大于等于 0。
activityFeeShopPart	decimal	否	商家承担活动优惠金额，必须大于等于 0。
activityFeePlatFormPart	decimal	否	平台承担活动优惠金额，必须大于等于 0。
latitude	double	否	配送地址纬度。
longitude	double	否	配送地址经度。
taxFee	decimal	否	税费，必须大于等于 0。
totalAmount	decimal	是	订单总金额，单位元；必须大于等于 0；以客户业务系统订单最终金额为准。
originalPrice	decimal	否	优惠前订单原价；不传默认等于订单总金额。
payType	int	否	支付类型：1 到店支付，2 在线支付；不传默认 2。
deliveryTime	string	否	预计送达时间，格式 yyyy-MM-dd HH:mm:ss。
daySeq	string	否	门店当日流水号或取餐序号。
deliveryType	int	否	配送类型，0：配送，1：自助点餐/自取；需要 POS 核销时请传 1。
guestNumber	int	否	就餐人数，必须大于等于 0。
restaurantAreaName	string	否	堂食区域名称。
restaurantTableName	string	否	堂食桌台名称。
reservationTime	string	否	预约到店/自提时间，格式 yyyy-MM-dd HH:mm:ss。

支付明细字段

说明：payments 本身非必填；只有传入支付明细数组时，数组内每个对象才必须包含 payMethodCode 和 payAmount。payType=2 且不传 payments 时，服务端会自动使用开放平台支付；payType=1 时不允许传 payments。

对象	字段	类型	必填	说明
payments[]	payMethodCode	int	条件必填	仅当传入 payments[] 时必填。支付方式编码：7 会员余额；19 购物卡；-1755 开放平台。
payments[]	payAmount	decimal	条件必填	仅当传入 payments[] 时必填。本支付方式支付金额必须大于 0，所有支付明细金额合计必须等于 totalAmount。
payments[]	shoppingCardUid	long	条件必填	仅当传入 payments[] 且 payMethodCode=19 时必填，表示本次扣款的购物卡 UID；其他支付方式不允许传。

商品明细字段

说明：子字段的“必填”仅针对其父对象已传入的场景。productOrderItemAttributes 本身非必填；只有传入商品口味数组时，数组内每个对象才必须包含 productAttributeUid。

对象	字段	类型	必填	说明
productOrderItems[]	productBarcode	string	是	商品条码或客户商品编码。服务端优先按条码匹配银豹商品资料，未匹配到时按未维护商品处理。
productOrderItems[]	productName	string	条件必填	商品名称。银豹已维护商品可不传；未维护商品必须传。
productOrderItems[]	comment	string	否	商品明细备注。也可以直接把口味等信息写在备注上。比如 去冰,3分甜,珍珠,椰果
productOrderItems[]	eShopSellPrice	decimal	条件必填	网店销售单价。银豹已维护商品可不传，默认取商品售价；未维护商品必须传。
productOrderItems[]	productQuantity	decimal	是	购买数量，必须大于 0。
productOrderItems[]	productBuyPrice	decimal	否	未维护商品的进货价或成本价；不传默认 0。银豹已维护商品自动取商品资料成本价。
productOrderItems[]	totalAmount	decimal	否	商品明细实收小计。仅在实收小计不等于 eShopSellPrice * productQuantity 时传；不传则服务端自动计算。
productOrderItems[]	productOrderItemAttributes	array<object>	否	商品口味，最多 200 条。
productOrderItemAttributes[]	productAttributeUid	long	条件必填	仅当传入 productOrderItemAttributes[] 时必填；不传商品口味时无需传。商品口味 UID 必须大于 0，且必须存在于商品口味资料中。
productOrderItemAttributes[]	attributeValue	decimal	否	商品口味值；如果没传，默认使用口味uid对应的值

业务规则

• 新增成功后网单状态固定为null（初始化）。
• orderNo 建议不传，统一由银豹默认规则生成。同一门店下，订单号不能重复。客户传入自定义 orderNo 时，可用于“网单/网络订单”界面搜索；若不符合银豹标准网单号格式，不能在 POS “核销”界面通过网单号核销。
• payType 如果钱已经支付了，不用传。如果想把订单推到银豹后，在银豹收钱，传 1。
• 商品明细对外统一使用 productBarcode。条码匹配到银豹商品资料时，商品 UID、名称、售价、成本价会自动补齐；未匹配到时，按客户未维护商品落单，商品 UID 固定写入 0。
• payType=2 且 payments 不传或为空时，服务端写入一条 payMethodCode=-1755、payMethodName=开放平台 的已完成支付明细。
• payments 非空,payMethodCode=7 时，服务端写入 payMethodName=CustomerBalance，并校验、扣减会员余额；余额不足时整单失败。
• payments 非空,payMethodCode=19 时，服务端写入 payMethodName=购物卡，并校验、扣减指定购物卡余额；购物卡不存在、不属于当前会员或余额不足时整单失败。
• 购物卡支付会校验 shoppingcard.expireDateTime，已过期购物卡不能使用；购物卡规则 shoppingcardrule.payLimit 非空时，会按订单总金额计算单笔最高可用金额，例如订单总额 200、payLimit=80 时，该规则购物卡最多支付 160。
• payments 非空,payMethodCode=-1755 时，服务端写入 payMethodName=开放平台，只写支付明细，不扣减会员余额或购物卡余额。
• 支付明细中包含会员余额或购物卡时，必须传 customerNumber 并能匹配到会员。

请求示例：银豹已维护商品

{
  "account": "store001",
  "time": "2026-05-18 12:30:00",
  "orderNo": "WEB202605180001",
  "contactAddress": "上海市浦东新区示例路 1 号",
  "contactTel": "13800138000",
  "contactName": "张三",
  "customerNumber": "VIP0001",
  "deliveryType": 0,
  "totalAmount": 88.50,
  "productOrderItems": [
    {
      "productBarcode": "690000000001",
      "productQuantity": 2,
      "productOrderItemAttributes": [
        {
          "productAttributeUid": 20000001,
          "attributeValue": 2.00
        }
      ]
    }
  ]
}

请求示例：银豹未维护商品

{
  "account": "store001",
  "contactTel": "13800138000",
  "contactName": "张三",
  "totalAmount": 44.00,
  "productOrderItems": [
    {
      "productBarcode": "CUSTOMER-SKU-001",
      "productName": "客户系统商品名称",
      "productQuantity": 2,
      "eShopSellPrice": 22.00,
      "productBuyPrice": 10.00
    }
  ]
}

请求示例：组合支付

{
  "account": "store001",
  "contactAddress": "上海市浦东新区示例路 1 号",
  "contactTel": "13800138000",
  "contactName": "张三",
  "customerNumber": "VIP0001",
  "deliveryType": 0,
  "totalAmount": 35.00,
  "productOrderItems": [
    {
      "productBarcode": "690000000001",
      "productQuantity": 1,
      "eShopSellPrice": 35.00
    }
  ],
  "payments": [
    {
      "payMethodCode": 7,
      "payAmount": 10.00
    },
    {
      "payMethodCode": -1755,
      "payAmount": 25.00
    }
  ]
}

请求示例：购物卡支付

{
  "account": "store001",
  "contactTel": "13800138000",
  "contactName": "张三",
  "customerNumber": "VIP0001",
  "totalAmount": 5.00,
  "productOrderItems": [
    {
      "productBarcode": "690000000001",
      "productQuantity": 1,
      "eShopSellPrice": 5.00
    }
  ],
  "payments": [
    {
      "payMethodCode": 19,
      "payAmount": 5.00,
      "shoppingCardUid": 100001
    }
  ]
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "id": 6036824,
    "orderNo": "WEB202605180001",
    "duplicate": false,
    "orderCreateDateTime": "2026-05-18 12:30:00"
  }
}

返回字段说明

字段	类型	说明
id	long	网单主键 ID。
orderNo	string	网单订单号；客户传入时返回客户传入值，未传时返回服务端生成值。
duplicate	boolean	是否命中已有网单；当前新建成功返回 false。
orderCreateDateTime	string	网单下单时间，格式 yyyy-MM-dd HH:mm:ss。

查询网单

POST

请求参数

参数	类型	必填	说明
account	string	是	业务门店账号；
id	long	否	网单主键 ID；传入时按精准查询计费。
orderNo	string	否	网单订单号；传入时按精准查询计费。
state	int	否	网单状态。
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。
needOrderItem	boolean	否	传 true 时返回 productorderitem，额外消耗 20 token。
needOrderItemAttribute	boolean	否	传 true 时返回 productorderitemattribute，额外消耗 20 token；服务端会自动加载商品明细作为属性挂载容器。

计费规则

• 传 id 或 orderNo 任一字段时，基础消耗 100 token。
• 未传 id 和 orderNo 时，按普通分页/范围查询计费，基础消耗 500 token。
• needOrderItem=true 额外消耗 20 token。
• needOrderItemAttribute=true 额外消耗 20 token。

请求示例

{
  "account": "store001",
  "id": 6036824,
  "orderNo": "WEB202605180001",
  "state": 1,
  "datetimeBegin": "2026-05-01 00:00:00",
  "datetimeEnd": "2026-05-19 00:00:00",
  "lastId": 0,
  "order": "asc",
  "limit": 100,
  "needOrderItem": true,
  "needOrderItemAttribute": true
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": 6036824,
        "time": "2026-05-18 12:30:00",
        "state": 1,
        "storeId": 10001,
        "customerAddress": "上海市浦东新区示例路 1 号",
        "customerTel": "13800138000",
        "customerName": "张三",
        "customerNumber": "VIP0001",
        "orderNo": "WEB202605180001",
        "deliveryType": 0,
        "totalAmount": 88.50,
        "orderSource": "MEITUAN_WAIMAI",
        "orderSourceSn": "MT202605180001",
        "updateTime": "2026-05-18 12:35:00",
        "sysUpdateTime": "2026-05-18 12:36:00",
        "productOrderItems": [
          {
            "id": 14749932,
            "productOrderId": 6036824,
            "productName": "拿铁",
            "productUid": 10000001,
            "productQuantity": 2,
            "productSellPrice": 22.00,
            "totalAmount": 44.00,
            "productOrderItemAttributes": [
              {
                "id": 944975,
                "productOrderItemId": 14749932,
                "productAttributeUid": 20000001,
                "attributeGroup": "taste",
                "attributeName": "甜度",
                "attributeValue": "少糖"
              }
            ]
          }
        ]
      }
    ],
    "hasMore": false,
    "nextLastId": 6036824
  }
}

返回字段说明

下表按当前接口 VO 完整列出网单主表返回字段。字段值为 null 时可能不出现在响应中。

字段	类型	说明
id	long	网单主键 ID，可作为下一页分页游标来源。
time	string	网单下单时间，格式为 yyyy-MM-dd HH:mm:ss。
state	int	网单状态： null 初始化 1 收到网单 2 已到店/已发货 3 已作废 4 已完成 5 已确认 8 待厨打/下发配送订单 20 客户确认订单 21 客户拒绝订单
storeId	int	门店 ID，用于标识该网单所属门店，关联门店用户 ID。
customerAddress	string	顾客收货地址或订单配送地址。
customerTel	string	顾客联系电话。
customerName	string	顾客姓名或收货人名称。
customerId	long	顾客/会员用户 ID，非会员或无法匹配会员时可能为空。
customerNumber	string	顾客会员编号。
orderNo	string	网单订单号，可用于精准查询单笔网单。
comment	string	顾客下单备注或订单备注。
paymentMethod	string	支付方式名称或来源平台返回的支付方式描述。
isOnlinePaymentCompleted	int	在线支付完成标记，用于判断线上支付是否已完成。1:已支付 null/0：未支付
deliveryType	int	履约方式： 0 或空为外卖 1 自助点餐 2 自提 3 预约 4 平台配送 11 批发当场出货 12 批发仓库出货
totalAmount	decimal	订单总金额，单位元。
reservationTime	string	预约到店/自提时间，仅自提单且带到店时间时返回。
taxFee	decimal	税费金额，单位元。
serviceFee	decimal	服务费金额，单位元。
shippingFee	decimal	配送费或运费金额，单位元。
orderSource	string	订单来源标识，例如第三方外卖平台、小程序等。 MEITUAN_WAIMAI 美团外卖 ELEME_WAIMAI 饿了么 ELEBE_WAIMAI 饿百 ZIYING_MINIAPP 银豹小程序 ZIYING_MIAOSHA 秒杀单 ZIYING_KANJIA 砍价
orderSourceKey	string	来源侧订单主键，用于和第三方或来源系统订单关联。
orderSourceSn	string	第三方外卖平台单号；批发场景下可能为配货仓库用户 ID。
originalPrice	decimal	订单优惠前原价金额，单位元。
deliveryTime	string	用户预计送达时间；“立即送达”场景可能返回 0 或为空。
payType	int	支付类型：1 到店支付/货到付款，2 在线支付。
updateTime	string	网单业务更新时间，格式为 yyyy-MM-dd HH:mm:ss。
packageFee	decimal	打包费金额，单位元。
totalProfit	decimal	订单总利润金额，单位元。
discount	decimal	订单优惠金额，单位元。
usedPoint	decimal	本次订单使用的积分数量。
pointAfterUsed	decimal	积分使用后剩余的积分数量。
pointToMoney	decimal	本次使用积分抵扣的金额，单位元。
guiderUid	long	导购员 UID，用于关联订单所属导购。
daySeq	string	门店当日订单流水号或取餐序号。
latitude	double	配送地址纬度。
longitude	double	配送地址经度。
restaurantAreaName	string	堂食餐厅区域名称。
restaurantTableName	string	堂食餐桌名称。
activityFeeShopPart	decimal	商家承担的活动优惠金额，单位元。
activityFeePlatFormPart	decimal	平台承担的活动优惠金额，单位元。
guestNumber	int	堂食或预约场景的就餐人数。
payMethodCode	int	支付方式编码，对应系统支付方式字典。
cancelReason	string	订单取消原因。
refundReason	string	订单退款原因。
platType	int	下单平台： 0 微信 1 微信小程序 2 支付宝 3 网页 4 字节/抖音小程序 5 支付宝小程序 6 茶饮自助 7 小红书小程序 8 淘宝闪购
businessComment	string	商家内部备注。
businessType	int	业务类型： 0 普通订单 1 预订单 10 拼团/团购 11 社区团购 13 砍价 14 秒杀 15 预售 20 预订餐 22 排队等位预点单 30 盲盒订单 33 微信视频号订单 40 周期购订单 60 企业订单 100 批发开单 200 代客下单 300 付款码单据
sourceType	int	订单来源类型： 0 本店 1 总部直接下单 2 总部选择门店下单 3 商圈 4 连锁小程序/派单中心 5 农贸 10 美团 11 饿了么 12 百度 20 聚合小程序 30 付款码
isReceived	int	收货/取货状态：0 未收货/未取货，1 已收货/已取货。
sysCreateTime	string	系统创建时间，格式为 yyyy-MM-dd HH:mm:ss。
sysUpdateTime	string	系统最后更新时间，格式为 yyyy-MM-dd HH:mm:ss。
productOrderItems	array<object>	网单商品明细列表，需传 needOrderItem=true 或 needOrderItemAttribute=true。

明细对象字段

下表完整列出 productOrderItems 和 productOrderItemAttributes 的返回字段。

对象	字段	类型	说明
productOrderItems[]	id	long	网单商品明细主键 ID。
productOrderItems[]	productOrderId	long	所属网单主键 ID，对应主表 id。
productOrderItems[]	productName	string	商品名称。
productOrderItems[]	productUid	long	商品 UID，用于关联商品资料。
productOrderItems[]	productBarcode	string	商品条码。
productOrderItems[]	eShopSellPrice	decimal	网店销售价，单位元。
productOrderItems[]	productQuantity	decimal	购买商品数量。
productOrderItems[]	productBuyPrice	decimal	商品进货价或成本价，单位元。
productOrderItems[]	productSellPrice	decimal	商品销售单价，单位元。
productOrderItems[]	isCustomerDiscount	int	是否参与会员折扣标记。
productOrderItems[]	customerDiscount	decimal	会员折扣值或折扣比例。
productOrderItems[]	customerPrice	decimal	会员价，单位元。
productOrderItems[]	isCustomerPoint	int	是否参与会员积分标记。
productOrderItems[]	comment	string	商品明细备注。
productOrderItems[]	boxNum	int	打包盒数量。
productOrderItems[]	boxPrice	decimal	打包盒单价，单位元。
productOrderItems[]	unit	string	商品销售单位。
productOrderItems[]	manualDiscount	decimal	人工优惠金额，单位元。
productOrderItems[]	productTotalProfit	decimal	该商品明细总利润，单位元。
productOrderItems[]	productTotalAmount	decimal	该商品明细商品金额小计，单位元。
productOrderItems[]	productDiscount	decimal	该商品明细优惠金额，单位元。
productOrderItems[]	kdsState	int	厨显/KDS 制作状态。
productOrderItems[]	packageNo	string	套餐编号。
productOrderItems[]	state	int	商品明细状态： 0 正常 1 退款中 2 退款成功 3 退款失败
productOrderItems[]	refundQuantity	decimal	该商品明细累计退款数量。
productOrderItems[]	refundState	int	退款处理状态： -2 初始化 -1 开始第三方支付退款 0 完成第三方支付退款 1 完成非第三方支付退款 2 上传销售单成功 3 上传销售单失败 4 完成非第三方支付退款并返回销售单请求体
productOrderItems[]	totalAmount	decimal	商品明细小计，包含商品金额和口味金额，单位元。
productOrderItems[]	productOrderItemAttributes	array<object>	商品明细属性，需传 needOrderItemAttribute=true。
productOrderItemAttributes[]	id	long	商品明细属性主键 ID。
productOrderItemAttributes[]	productOrderItemId	long	所属商品明细 ID，对应 productOrderItems[].id。
productOrderItemAttributes[]	productAttributeUid	long	商品属性 UID，用于关联口味、规格等属性资料。
productOrderItemAttributes[]	attributeGroup	string	属性分组编码，例如口味组或规格组。
productOrderItemAttributes[]	attributeName	string	属性名称，例如甜度、温度、规格名称。
productOrderItemAttributes[]	attributeValue	string	属性选择值，例如少糖、常温、大杯。
productOrderItemAttributes[]	attributeOriginalValue	string	属性原始值或口味原价。