OPENAPI V3
登录控制台
首次登录赠送 10000 Token，可直接调试接口
充值、回调配置、调用日志、接口调试均在控制台完成

商品接口文档

本页专门展示商品接口，便于单独交付与维护；通用规则仍复用总览页内容。Long 型标识字段、分页游标等通用约定，请先参考总览页《对接说明》。

商品接口

本页按“商品资料”“商品分类”“商品标签”“商品单位”“商品品牌”“商品供应商”“商品口味”“商品库存”和“商品报损”等场景拆开展示，方便客户先理解主数据接口，再查看字典同步、库存查询与库存写入接口。

商品资料接口

用于商品查询、新增、修改。通常适合做资料初始化、资料比对、商品档案维护；分类、标签、单位、品牌、供应商、口味等字典能力按资源单独分组展示。

查询商品

POST
/openapi/v3/product/increment-page

支持按 uid、barcode、分类、名称等条件查询商品，也可按 lastId 游标分页拉取；默认只返回 product 表基础信息，扩展信息需通过布尔参数显式开启。

Token 消耗 基础 100 token/次 每开启一个扩展开关，额外 +20 token

请求参数

参数 类型 必填 说明
account string 是 业务门店账号，表示本次查询对应哪家门店。
lastId long 否 翻页游标。首次传 0 或不传；后续传上一次响应中的 nextLastId。
order string 否 排序方向，仅支持 asc、desc，默认 asc。
limit int 否 分页大小，默认 100，最大 100，超过按 100 处理。
uidlong否按单个商品 UID 精确查询。
uidSetarray<long>否按多个商品 UID 查询，最多 100 个。
barcodestring否按单个条码精确查询。
barcodeSetarray<string>否按多个条码查询，最多 100 个。
categoryUidlong否按分类 UID 查询。
categoryNamestring否按分类名称查询，系统会先换算为分类 UID 再查询。
namestring否按商品名称精确查询。
needCommonAttributeboolean否传 true 时返回商品通用属性，额外消耗 +20 token。
needImagesboolean否传 true 时返回商品图片列表，额外消耗 +20 token。
needExtBarcodesboolean否传 true 时返回扩展条码，额外消耗 +20 token。
needTagsboolean否传 true 时返回商品标签，额外消耗 +20 token。
needTastesboolean否传 true 时返回商品口味信息，额外消耗 +20 token。
needSuppliersboolean否传 true 时返回商品供应商列表，额外消耗 +20 token。
needMainUnitboolean否传 true 时返回商品主单位，额外消耗 +20 token。
needCategoryboolean否传 true 时返回分类对象，额外消耗 +20 token。

业务说明

  • 只查询 未删除(enable != -1) 的商品。
  • 扩展返回字段按布尔参数显式开启；不需要的扩展建议不要传 true。

请求示例

{
  "account": "store001",
  "lastId": 0,
  "order": "asc",
  "limit": 100,
  "needCommonAttribute": true,
  "needImages": true,
  "needExtBarcodes": false,
  "needTags": false,
  "needTastes": true,
  "needSuppliers": true,
  "needMainUnit": true,
  "needCategory": true
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "101",
        "uid": "1002003001",
        "categoryUid": "9001",
        "supplierUid": "3001",
        "stock": 128.0000,
        "userId": 5592187,
        "name": "可乐500ml",
        "barcode": "6901234567890",
        "buyPrice": 2.20,
        "sellPrice": 3.50,
        "maxStock": 500.00,
        "minStock": 20.00,
        "pinyin": "kele",
        "sellPrice2": 3.20,
        "customerPrice": 3.20,
        "productionDate": "2026-03-20",
        "shelfLife": 365,
        "isPoint": 1,
        "isCustomerDiscount": 1,
        "enable": 1,
        "description": "新品测试",
        "createdDatetime": "2026-03-20 08:00:00",
        "updatedDatetime": "2026-04-01 09:30:00",
        "isGift": 0,
        "isCaseProduct": 2,
        "noStock": 0,
        "attribute1": "常温",
        "attribute2": "500ml",
        "attribute3": "塑料瓶",
        "attribute4": "SP-001",
        "attribute5": "COLA-500",
        "attribute6": "500ml*24",
        "attribute7": "是",
        "attribute8": "否",
        "attribute9": "自定义9",
        "attribute10": "自定义10",
        "sysUpdateTime": "2026-04-01 09:30:00",
        "commonAttribute": {
          "canAppointed": 0,
          "isTiming": 0,
          "atLeastMinutes": 30,
          "atLeastAmount": 100.00,
          "enableBatch": 1,
          "stockDeductionType": 0,
          "pluCode": "2800000001234",
          "brandUid": "8001",
          "brandName": "可口可乐",
          "stockPosition": "A-01-02",
          "preparationTime": 15,
          "preparationTimeUnit": 0,
          "volume": 0.500,
          "weight": 0.550,
          "weightUnit": 1,
          "minSellQuantity": 1.000,
          "stepSellQuantity": 1.000,
          "maxSellQuantity": 10.000,
          "enableSN": 0,
          "isPacking": 0,
          "isBarcodeScale": 0,
          "isNewly": 1,
          "limitMinSellPrice": 3.00,
          "depositValidDays": 7,
          "enableTraceabilityCode": 1,
          "ifNeedMake": 0,
          "referGrossRate": 35.50,
          "mnemonicCode": "KL"
        },
        "images": [
          {
            "path": "https://cdn.example.com/product/1002003001/main.jpg",
            "isCover": 1,
            "orderIndex": 1
          }
        ],
        "extBarcodes": [
          "16901234567890"
        ],
        "tags": [
          "饮料",
          "常温"
        ],
        "tastes": [
          {
            "uid": "1622707645696449590",
            "attributeName": "椰果",
            "attributeValue": "2",
            "isDefault": 0,
            "suggest": 1,
            "packageUid": "1622707645694362262",
            "packageName": "加料",
            "packageType": 1
          },
          {
            "uid": "1622707645706257418",
            "attributeName": "奶盖",
            "attributeValue": "5",
            "isDefault": 0,
            "suggest": 0,
            "packageUid": "1622707645694362262",
            "packageName": "加料",
            "packageType": 1
          }
        ],
        "suppliers": [
          {
            "uid": "3001",
            "number": "SUP-001",
            "name": "鲜果原料供应商",
            "lastBuyPrice": 8.50000000,
            "buyPrice": 9.00000000,
            "isDefault": 1,
            "deliveryDay": 1
          },
          {
            "uid": "3002",
            "number": "SUP-002",
            "name": "奶制品供应商",
            "lastBuyPrice": 11.20000000,
            "buyPrice": 11.50000000,
            "isDefault": 0,
            "deliveryDay": 2
          }
        ],
        "mainUnit": {
          "uid": "7001",
          "name": "瓶"
        },
        "category": {
          "uid": "9001",
          "parentUid": "9000",
          "name": "饮料",
          "enable": 1,
          "categoryOrder": 10
        }
      }
    ],
    "hasMore": true,
    "nextLastId": "101"
  }
}

返回字段说明

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

字段 类型 说明
idstring商品主键 ID。
uidstring商品业务 UID。
categoryUidstring商品所属分类 UID。
supplierUidstring供应商 UID。
stockdecimal当前库存数量。
userIdint门店 ID。
namestring商品名称。
barcodestring主条码。
buyPricedecimal进价。
sellPricedecimal售价。
maxStockdecimal库存上限。
minStockdecimal库存下限。
pinyinstring商品拼音。
sellPrice2decimal批发价。
customerPricedecimal会员价。
productionDatestring生产日期。
shelfLifeint保质期。
isPointint是否参与积分。
isCustomerDiscountint是否开启会员折扣 1-开启 0/null-不开启。
enableint状态，文档中仅返回 enable != -1 的商品。1-可用，0-禁用，-1-删除。
descriptionstring商品描述。
createdDatetimestring创建时间。
updatedDatetimestring业务更新时间。
isGiftint是否赠品。
isCaseProductint是否原材料配方商品。
noStockint是否不记库存，0/null-记库存，1-不记库存。
attribute1stringattribute1。
attribute2stringattribute2。
attribute3stringattribute3。
attribute4stringattribute4 货号(零售行业)。
attribute5stringSPU/主编码（服装多颜色尺码）多规格商品，该字段一样。
attribute6string规格。
attribute7string是否主商品。
attribute8string是否多颜色尺码。
attribute9stringattribute9。
attribute10stringattribute10。
sysUpdateTimestring系统更新时间。
commonAttributeobject商品通用属性，需传 needCommonAttribute=true。
imagesarray<object>商品图片列表，需传 needImages=true。
extBarcodesarray<string>扩展条码列表，需传 needExtBarcodes=true。
tagsarray<string>商品标签列表，需传 needTags=true。
tastesarray<object>商品口味列表，需传 needTastes=true。
suppliersarray<object>商品供应商列表，需传 needSuppliers=true，按供应商 UID 去重后返回。
mainUnitobject商品主单位，需传 needMainUnit=true。
categoryobject分类对象，需传 needCategory=true。

扩展对象字段

对象 字段 类型 说明
commonAttributecanAppointedint是否可预约,0/null-否，1-是。
commonAttributeisTimingint是否计时商品,0/null-否，1-是。
commonAttributeatLeastMinutesint最低消费分钟数。
commonAttributeatLeastAmountdecimal最低消费金额。
commonAttributeenableBatchint是否开启批次管理，0/null-关闭，1-开启。
commonAttributestockDeductionTypeint库存扣减方式，仅开启批次管理时有效，0-先进先出，1-手动选择批次。
commonAttributepluCodestring称编码。
commonAttributebrandUidstring品牌 UID。
commonAttributebrandNamestring品牌名称。
commonAttributestockPositionstring库位。
commonAttributepreparationTimeint准备时长，单位分钟。
commonAttributepreparationTimeUnitint准备时长单位，0-分钟，1-天。
commonAttributevolumedecimal体积。
commonAttributeweightdecimal重量。
commonAttributeweightUnitint重量单位，NULL/1-kg，2-斤。
commonAttributeminSellQuantitydecimal起售量。
commonAttributestepSellQuantitydecimal增量售卖数。
commonAttributemaxSellQuantitydecimal最大售卖数。
commonAttributeenableSNint是否开启序列号管理，0/null-关闭，1-开启。
commonAttributeisPackingint是否包装商品，0/null-否，1-是。
commonAttributeisBarcodeScaleint是否条码秤商品，0/null-否，1-是。
commonAttributeisNewlyint是否新品，0/null-否，1-是。
commonAttributelimitMinSellPricedecimal最低售价限制。
commonAttributedepositValidDaysint寄存有效期，单位天。
commonAttributeenableTraceabilityCodeint是否开启溯源码，0/null-关闭，1-开启。
commonAttributeifNeedMakeint是否需要制作，0/null-关闭，1-开启。
commonAttributereferGrossRatedecimal参考毛利率。
commonAttributemnemonicCodestring商品助记码。
images[]pathstring图片地址。
images[]isCoverint是否封面图，1 表示是。
images[]orderIndexint图片排序值。
tastes[]uidstring口味 UID。
tastes[]attributeNamestring口味名称。
tastes[]attributeValuestring口味值。
tastes[]isDefaultint是否默认口味，1 表示默认。
tastes[]suggestint是否推荐口味，1 表示推荐。
tastes[]packageUidstring口味组 UID。
tastes[]packageNamestring口味组名称。
tastes[]packageTypeint口味组类型 1:多选 + 非必选 2:单选 + 非必选 3:多选 + 必选 4:单选 + 必选。
suppliers[]uidstring供应商 UID。
suppliers[]numberstring供应商编号。
suppliers[]namestring供应商名称。
suppliers[]lastBuyPricedecimal最后进货价。
suppliers[]buyPricedecimal进货价。
suppliers[]isDefaultint是否默认供应商，1 表示默认。
suppliers[]deliveryDayint交货周期，单位天。
mainUnituidstring主单位 UID。
mainUnitnamestring主单位名称。
categoryuidstring分类 UID。
categoryparentUidstring父级分类 UID。
categorynamestring分类名称。
categoryenableint分类启用状态。
categorycategoryOrderint分类排序值。

新增商品

POST
/openapi/v3/product/create

新增商品采用扁平写模型。基础字段尽量与查询商品同名；分类、供应商、主单位、标签、品牌、口味等引用字段，先通过字典接口取到 UID，再在本接口中回传。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明 UID 来源接口
accountstring是业务门店账号。-
categoryUidlong否商品分类 UID。/openapi/v3/product/category-page
supplierUidlong否默认供应商 UID。/openapi/v3/product/supplier-page
stockdecimal否初始库存；不传默认 0。-
namestring是商品名称。-
barcodestring否商品条码；如传入则服务端基于该条码生成商品 UID。若不传，服务端会自动生成条码并据此生成商品 UID；同门店内最终落库条码必须唯一。-
buyPricedecimal是进价，必须大于等于 0。-
sellPricedecimal是售价，必须大于等于 0。-
maxStockdecimal否最大库存。-
minStockdecimal否最小库存。-
pinyinstring否商品拼音,如果为空按银豹默认规则生成。-
sellPrice2decimal否批发价。-
customerPricedecimal否会员价；不传时默认等于 sellPrice。-
productionDatestring否生产日期；建议格式 yyyy-MM-dd。-
shelfLifeint否保质期天数；如传值需大于 0。-
attribute1string否attribute1。-
attribute2string否attribute2。-
attribute3string否attribute3。-
attribute4string否attribute4 货号(零售行业)。-
attribute5string否SPU/主编码（服装多颜色尺码）多规格商品，该字段一样。-
attribute6string否规格；按现有表结构原值落库。-
attribute7string否是否主商品。-
attribute8string否是否多颜色尺码。-
attribute9string否attribute9。-
attribute10string否attribute10。-
isCustomerDiscountint否是否参与会员折扣，取值 0 / 1，默认 0。-
enableint否启用状态，取值 0 / 1，默认 1。-
descriptionstring否商品描述。-
noStockint否是否不记库存，0/null-记库存，1-不记库存。-
commonAttributeobject否商品通用扩展属性对象；支持传入品牌、批次管理、准备时长、称编码、重量、起售量等字段，详见下方 commonAttribute 子字段说明。-
extBarcodesarray<string>否扩展条码列表；每项长度不能超过 32。-
tagUidsarray<long>否商品标签 UID 列表。/openapi/v3/product/tag-page
tastesarray<object>否商品口味列表。/openapi/v3/product/attribute-page
tastes[].uidlong是（有 tastes 时）口味 UID。/openapi/v3/product/attribute-page
tastes[].suggestint否是否推荐，取值 0 / 1，默认 0。-
mainUnitUidlong否商品主单位 UID；当前仅支持写入一个主单位。/openapi/v3/product/unit-page

commonAttribute 子字段说明

以下仅列出新增商品接口当前支持写入的 commonAttribute 子字段；如 commonAttribute.brandName 等查询返回字段，不支持在本接口直接传入。

参数 类型 必填 说明 默认值/校验 UID 来源接口
commonAttribute.canAppointedint否是否可预约。0/null=否，1=是。-
commonAttribute.isTimingint否是否计时商品。0/null=否，1=是。-
commonAttribute.atLeastMinutesint否最低消费分钟数。如传值需大于 0。-
commonAttribute.atLeastAmountdecimal否最低消费金额。按数值落库。-
commonAttribute.enableBatchint否是否开启批次管理。0/null=关闭，1=开启。-
commonAttribute.stockDeductionTypeint否库存扣减方式，仅开启批次管理时有效。0=先进先出，1=手动选择批次。-
commonAttribute.pluCodestring否称编码。按原值落库。-
commonAttribute.brandUidlong否品牌 UID。服务端会校验是否存在。/openapi/v3/product/brand-page
commonAttribute.stockPositionstring否库位。按原值落库。-
commonAttribute.preparationTimeint否准备时长。如传值需大于 0。-
commonAttribute.preparationTimeUnitint否准备时长单位。不传默认 0；0=分钟，1=天。-
commonAttribute.volumedecimal否体积。按数值落库。-
commonAttribute.weightdecimal否重量。按数值落库。-
commonAttribute.weightUnitint否重量单位。1=kg，2=斤。-
commonAttribute.minSellQuantitydecimal否起售量。按数值落库。-
commonAttribute.stepSellQuantitydecimal否增量售卖数。按数值落库。-
commonAttribute.maxSellQuantitydecimal否最大售卖数。按数值落库。-
commonAttribute.enableSNint否是否开启序列号管理。0/null=关闭，1=开启。-
commonAttribute.isPackingint否是否包装商品。0/null=否，1=是。-
commonAttribute.isBarcodeScaleint否是否条码秤商品。0/null=否，1=是。-
commonAttribute.isNewlyint否是否新品。0/null=否，1=是。-
commonAttribute.limitMinSellPricedecimal否最低售价限制。按数值落库。-
commonAttribute.depositValidDaysint否寄存有效期，单位天。如传值需大于 0。-
commonAttribute.enableTraceabilityCodeint否是否开启溯源码。0/null=关闭，1=开启。-
commonAttribute.ifNeedMakeint否是否需要制作。0/null=关闭，1=开启。-
commonAttribute.referGrossRatedecimal否参考毛利率。按数值落库。-
commonAttribute.mnemonicCodestring否商品助记码。按原值落库。-

业务说明

  • 商品 UID 由服务端按 NumberUtil.generateUid(barcode) 生成；若未传 barcode，服务端会先自动生成条码，再据此生成商品 UID。
  • 仅当不同门店传入相同 barcode 时，生成的商品 UID 才保持一致。
  • 若同一门店下最终使用的 barcode 已存在，接口会返回 4006。
  • attribute1 ~ attribute10 会按原值写入现有表结构；如门店已约定具体业务语义，请保持与既有系统一致。
  • commonAttribute 仅支持本页列出的可写子字段；如 commonAttribute.brandName 等查询返回字段，不支持在创建接口传入。
  • 如传入 categoryUid、supplierUid、mainUnitUid、tagUids、tastes[].uid、commonAttribute.brandUid，服务端会先校验 UID 是否存在；不存在时返回 4004。
  • 当前暂不支持多单位批量写入，仅支持通过 mainUnitUid 写主单位。

请求示例

{
  "account": "store001",
  "categoryUid": 9001,
  "supplierUid": 3001,
  "stock": 128,
  "name": "可乐500ml",
  "barcode": "6901234567890",
  "buyPrice": 2.2,
  "sellPrice": 3.5,
  "maxStock": 500,
  "minStock": 20,
  "pinyin": "kele",
  "sellPrice2": 3.2,
  "customerPrice": 3.2,
  "productionDate": "2026-03-20",
  "shelfLife": 365,
  "attribute1": "常温",
  "attribute2": "500ml",
  "attribute3": "塑料瓶",
  "attribute4": "SP-001",
  "attribute5": "COLA-500",
  "attribute6": "500ml*24",
  "attribute7": "是",
  "attribute8": "否",
  "attribute9": "自定义9",
  "attribute10": "自定义10",
  "isCustomerDiscount": 1,
  "enable": 1,
  "description": "新品测试",
  "noStock": 0,
  "commonAttribute": {
    "canAppointed": 0,
    "isTiming": 0,
    "atLeastMinutes": 30,
    "atLeastAmount": 100,
    "enableBatch": 1,
    "stockDeductionType": 0,
    "pluCode": "2800000001234",
    "brandUid": 8001,
    "stockPosition": "A-01-02",
    "preparationTime": 15,
    "preparationTimeUnit": 0,
    "volume": 0.5,
    "weight": 0.55,
    "weightUnit": 1,
    "minSellQuantity": 1,
    "stepSellQuantity": 1,
    "maxSellQuantity": 10,
    "enableSN": 0,
    "isPacking": 0,
    "isBarcodeScale": 0,
    "isNewly": 1,
    "limitMinSellPrice": 3,
    "depositValidDays": 7,
    "enableTraceabilityCode": 1,
    "ifNeedMake": 0,
    "referGrossRate": 35.5,
    "mnemonicCode": "KL"
  },
  "extBarcodes": [
    "16901234567890"
  ],
  "tagUids": [
    11001,
    11002
  ],
  "tastes": [
    {
      "uid": 1622707645696449590,
      "suggest": 1
    },
    {
      "uid": 1622707645706257418,
      "suggest": 0
    }
  ],
  "mainUnitUid": 7001
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "id": "101",
    "uid": "506901234567890",
    "name": "可乐500ml",
    "barcode": "6901234567890",
    "sysUpdateTime": "2026-04-25 14:30:00"
  }
}

返回字段说明

status、errorCode 及公共响应字段请参考“公共响应格式”，此处仅补充 result。

字段 类型 说明
idlong商品主键 ID。
uidlong商品 UID，由服务端根据 barcode 生成。
namestring商品名称。
barcodestring商品条码。
sysUpdateTimestring系统更新时间。

修改商品

POST
/openapi/v3/product/update

按 uid 或 barcode 二选一定位商品，采用 updateMask + clearFields 协议更新商品资料，并支持在修改资料时一起直接设置库存。

说明：为避免客户误以为只支持少数字段，本节下面直接列出完整可修改字段清单、可清空规则以及 commonAttribute 子字段清单。

Token 消耗 固定 100 token/次

协议控制字段

参数 类型 必填 说明 UID 来源接口
accountstring是业务门店账号。-
uidlong二选一商品 UID；与 barcode 二选一传入。-
barcodestring二选一商品条码；与 uid 二选一传入，仅作定位条件，不支持修改。-
updateMaskarray<string>否声明本次要修改哪些字段；不在其中的字段不修改。-
clearFieldsarray<string>否声明本次要清空哪些字段；与 updateMask 不能同时都为空。-

完整可修改字段清单

字段 类型 要求 说明 是否支持清空 UID 来源接口
namestring按需商品名称；仅当 updateMask 包含 name 时生效。否-
categoryUidlong按需商品分类 UID。否/openapi/v3/product/category-page
supplierUidlong按需默认供应商 UID。是/openapi/v3/product/supplier-page
stockdecimal按需库存值；仅当 updateMask 包含 stock 时生效，语义为直接设置库存。否-
buyPricedecimal按需进价。否-
sellPricedecimal按需售价。否-
maxStockdecimal按需最大库存。是-
minStockdecimal按需最小库存。是-
pinyinstring按需商品拼音。是-
sellPrice2decimal按需批发价。是-
customerPricedecimal按需会员价。是-
productionDatestring按需生产日期，建议格式 yyyy-MM-dd。是-
shelfLifeint按需保质期天数。是-
attribute1string按需attribute1。是-
attribute2string按需attribute2。是-
attribute3string按需attribute3。是-
attribute4string按需attribute4。货号(零售行业)是-
attribute5string按需SPU/主编码（服装多颜色尺码）多规格商品，该字段一样。是-
attribute6string按需规格。是-
attribute7string按需是否主商品。是-
attribute8string按需是否多颜色尺码。是-
attribute9string按需attribute9。是-
attribute10string按需attribute10。是-
isCustomerDiscountint按需是否参与会员折扣，只支持 0 / 1。否-
enableint按需启用状态，只支持 0 / 1。否-
descriptionstring按需商品描述。是-
noStockint按需是否不记库存。是-
extBarcodesarray<string>按需扩展条码列表；更新时按整体替换。是-
tagUidsarray<long>按需商品标签 UID 列表；更新时按整体替换。是/openapi/v3/product/tag-page
tastesarray<object>按需商品口味列表；更新时按整体替换。如只想修改其中一个口味的 suggest，也需传最终完整口味列表。是/openapi/v3/product/attribute-page
mainUnitUidlong按需商品主单位 UID。是/openapi/v3/product/unit-page

commonAttribute 可修改子字段

字段 类型 说明 是否支持清空 UID 来源接口
commonAttribute.canAppointedint是否可预约。否-
commonAttribute.isTimingint是否计时商品。否-
commonAttribute.atLeastMinutesint最低消费分钟数。是-
commonAttribute.atLeastAmountdecimal最低消费金额。是-
commonAttribute.enableBatchint是否开启批次管理。否-
commonAttribute.stockDeductionTypeint库存扣减方式。否-
commonAttribute.pluCodestring称编码。是-
commonAttribute.brandUidlong品牌 UID。是/openapi/v3/product/brand-page
commonAttribute.stockPositionstring库位。是-
commonAttribute.preparationTimeint准备时长。是-
commonAttribute.preparationTimeUnitint准备时长单位。否-
commonAttribute.volumedecimal体积。是-
commonAttribute.weightdecimal重量。是-
commonAttribute.weightUnitint重量单位。否-
commonAttribute.minSellQuantitydecimal起售量。是-
commonAttribute.stepSellQuantitydecimal增量售卖数。是-
commonAttribute.maxSellQuantitydecimal最大售卖数。是-
commonAttribute.enableSNint是否开启序列号管理。否-
commonAttribute.isPackingint是否包装商品。否-
commonAttribute.isBarcodeScaleint是否条码秤商品。否-
commonAttribute.isNewlyint是否新品。否-
commonAttribute.limitMinSellPricedecimal最低售价限制。是-
commonAttribute.depositValidDaysint尤存有效天数。是-
commonAttribute.enableTraceabilityCodeint是否开启溯源码。否-
commonAttribute.ifNeedMakeint是否需要制作。否-
commonAttribute.referGrossRatedecimal参考毛利率。是-
commonAttribute.mnemonicCodestring助记码。是-

业务说明

  • uid 与 barcode 必须且只能传一个；推荐优先传 barcode。
  • updateMask 负责“改值”，clearFields 负责“清空”；同一个字段不能同时出现在两边。
  • clearFields 可清空的基础字段主要包括：supplierUid、maxStock、minStock、pinyin、sellPrice2、customerPrice、productionDate、shelfLife、description、noStock、attribute1~10、extBarcodes、tagUids、tastes、mainUnitUid。
  • stock 支持随商品资料一起修改，但不支持清空；如需批量设置 / 批量增减库存，仍建议使用库存专用接口。
  • tagUids、tastes、extBarcodes 在更新时按“整体替换”处理；放入 clearFields 时表示全部清空。
  • tastes 不支持只传局部变更项。比如原来有 3 种口味想改成 2 种，请直接传最终的 2 种口味列表；如原来有 5 种口味只想修改某个口味的 suggest，也请传最终完整的 5 种口味列表。
  • commonAttribute 不支持整对象更新；如需清空整个 commonAttribute，请传 clearFields: ["commonAttribute"]。
  • 如请求涉及 categoryUid、supplierUid、mainUnitUid、tagUids、tastes[].uid、commonAttribute.brandUid，服务端会先校验 UID 是否存在。

请求示例

{
  "account": "store001",
  "barcode": "6901234567890",
  "updateMask": [
    "name",
    "stock",
    "sellPrice",
    "attribute5",
    "tagUids",
    "commonAttribute.brandUid"
  ],
  "clearFields": ["description"],
  "name": "可乐600ml",
  "stock": 128,
  "sellPrice": 3.8,
  "attribute5": "COLA-600",
  "tagUids": [11001, 11002],
  "commonAttribute": {
    "brandUid": 8001
  }
}

口味修改示例

当 updateMask 包含 tastes 时，服务端会把传入的口味列表视为“最终状态”，不支持只传局部变更项。

{
  "account": "store001",
  "barcode": "6901234567890",
  "updateMask": ["tastes"],
  "tastes": [
    {
      "uid": 1622707645696449590,
      "suggest": 1
    },
    {
      "uid": 1622707645706257418,
      "suggest": 0
    }
  ]
}
  • 原来有 3 种口味，想改成 2 种：直接传最终的 2 条 tastes。
  • 原来有 5 种口味，只想改某一条的 suggest：也要把最终完整的 5 条 tastes 一起传上来。

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "id": "101",
    "uid": "1002003001",
    "name": "可乐600ml",
    "barcode": "6901234567890",
    "sysUpdateTime": "2026-04-26 15:30:12"
  }
}

常见错误

  • 请传 uid 或 barcode 其中一个
  • uid 与 barcode 只能传一个
  • updateMask 与 clearFields 不能同时为空
  • barcode 仅支持作为定位条件，不支持修改
  • stock 不支持清空
  • commonAttribute 不支持整对象更新，请使用 commonAttribute.xxx

商品分类

用于查询、新增、修改商品分类。分类新增和修改成功后会生成同步任务并通知收银端。

查询商品分类

POST
/openapi/v3/product/category-page

分页拉取商品分类字典，供新增商品接口传入 categoryUid；返回 id、uid、parentUid、name 等字段。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
lastIdlong否分页游标。首次传 0；后续传上次响应中的 nextLastId。
limitint否单次返回条数；默认 100，最大 100。
namestring否分类名称，按精确匹配过滤。

业务说明

  • 服务端固定按 id asc 顺序分页返回。
  • 仅返回未删除分类，即 enable != -1 的记录。
  • 新增商品时请使用返回的 uid 作为 categoryUid。

请求示例

{
  "account": "store001",
  "lastId": 0,
  "limit": 100,
  "name": "饮料"
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "301",
        "uid": "9001",
        "parentUid": "9000",
        "name": "饮料",
        "enable": 1,
        "categoryOrder": 10
      }
    ],
    "hasMore": false,
    "nextLastId": "301"
  }
}

返回字段说明

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

字段 类型 说明
idlong分类表主键 ID，用于分页游标。
uidlong分类 UID，新增商品时传入 categoryUid。
parentUidlong父级分类 UID。
namestring分类名称。
enableint分类启用状态。
categoryOrderint分类排序值。

新增商品分类

POST
/openapi/v3/product/category-create

新增商品分类。name 必填，parentUid 不传或传 0 表示顶级分类；新增成功后会同步到收银端。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
namestring是分类名称，服务端会自动去除首尾空格，长度不能超过 50。
parentUidlong否父级分类 UID。不传或传 0 表示顶级分类；非 0 时父级分类必须存在。

业务说明

  • 同一父级分类下不允许存在相同名称的未删除分类。
  • 新增分类默认 enable = 1、categoryOrder = 0、categoryType = 0。
  • 接口成功后会异步保存同步任务并通知收银端，行为与新增商品订单同步保持一致。

请求示例

{
  "account": "store001",
  "parentUid": 0,
  "name": "饮料"
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "id": "302",
    "uid": "9002",
    "parentUid": "0",
    "name": "饮料",
    "enable": 1,
    "categoryOrder": 0
  }
}

返回字段说明

字段 类型 说明
idlong分类表主键 ID。
uidlong分类 UID，新增或修改商品时传入 categoryUid。
parentUidlong父级分类 UID；0 表示顶级分类。
namestring分类名称。
enableint分类启用状态。
categoryOrderint分类排序值。

修改商品分类

POST
/openapi/v3/product/category-update

修改商品分类名称或父级分类。uid 必填，name 和 parentUid 按需传入；修改成功后会同步到收银端。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
uidlong是要修改的分类 UID。
namestring否新的分类名称。传入时服务端会自动去除首尾空格，长度不能超过 50。
parentUidlong否新的父级分类 UID。传 0 表示改为顶级分类；传 -1 或不传表示不修改父级。

业务说明

  • 目标分类不存在或已删除时返回错误。
  • 非 0 的父级分类必须存在。
  • 同一父级分类下不允许存在相同名称的未删除分类。
  • 不允许把分类移动到自己或自己的子分类下。
  • 接口成功后会异步保存同步任务并通知收银端，行为与新增商品订单同步保持一致。

请求示例

{
  "account": "store001",
  "uid": 9002,
  "parentUid": -1,
  "name": "瓶装饮料"
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "id": "302",
    "uid": "9002",
    "parentUid": "0",
    "name": "瓶装饮料",
    "enable": 1,
    "categoryOrder": 0
  }
}

返回字段说明

字段 类型 说明
idlong分类表主键 ID。
uidlong分类 UID，新增或修改商品时传入 categoryUid。
parentUidlong父级分类 UID；0 表示顶级分类。
namestring分类名称。
enableint分类启用状态。
categoryOrderint分类排序值。

商品标签

用于查询商品标签字典，返回新增或修改商品时所需的 tagUids。

查询商品标签

POST
/openapi/v3/product/tag-page

分页拉取商品标签字典，返回 uid + name，供新增商品接口传入 tagUids。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
lastIdlong否分页游标。首次传 0；后续传上次响应中的 nextLastId。
limitint否单次返回条数；默认 100，最大 100。
namestring否标签名称，按精确匹配过滤。

业务说明

  • 服务端固定按 id asc 顺序分页返回。
  • name 为精确匹配，适合按标签名称定位对应 UID。
  • 返回字段覆盖新增商品所需的核心信息：id、uid、name。

请求示例

{
  "account": "store001",
  "lastId": 0,
  "limit": 100,
  "name": "饮料"
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "201",
        "uid": "11001",
        "name": "饮料"
      }
    ],
    "hasMore": false,
    "nextLastId": "201"
  }
}

返回字段说明

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

字段 类型 说明
idlong标签表主键 ID，用于分页游标。
uidlong标签 UID，新增商品时传入 tagUids。
namestring标签名称。

商品单位

用于查询商品单位字典，返回新增或修改商品时所需的 mainUnitUid。

查询商品单位

POST
/openapi/v3/product/unit-page

分页拉取商品单位字典，供新增商品接口传入 mainUnitUid。当前新增商品只支持写一个主单位。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
lastIdlong否分页游标。首次传 0；后续传上次响应中的 nextLastId。
limitint否单次返回条数；默认 100，最大 100。
namestring否单位名称，按精确匹配过滤。

业务说明

  • 服务端固定按 id asc 顺序分页返回。
  • 仅返回启用中的单位，即 enable = 1 的记录。
  • 新增商品时请使用返回的 uid 作为 mainUnitUid。

请求示例

{
  "account": "store001",
  "lastId": 0,
  "limit": 100,
  "name": "瓶"
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "401",
        "uid": "7001",
        "name": "瓶"
      }
    ],
    "hasMore": false,
    "nextLastId": "401"
  }
}

返回字段说明

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

字段 类型 说明
idlong单位表主键 ID，用于分页游标。
uidlong单位 UID，新增商品时传入 mainUnitUid。
namestring单位名称。

商品品牌

用于查询商品品牌字典，返回新增或修改商品时所需的 commonAttribute.brandUid。

查询商品品牌

POST
/openapi/v3/product/brand-page

分页拉取商品品牌字典，供新增商品接口传入 commonAttribute.brandUid。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
lastIdlong否游标 ID；默认从 0 开始。
limitint否分页大小；默认 100，最大 100。
namestring否品牌名称；按名称精确匹配。

请求示例

{
  "account": "store001",
  "lastId": 0,
  "limit": 100,
  "name": "可口可乐"
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": 1,
        "uid": 8001,
        "name": "可口可乐"
      }
    ],
    "hasMore": false,
    "nextLastId": 1
  }
}

返回字段说明

status、errorCode 及公共响应字段请参考“公共响应格式”，此处仅补充 result。

字段 类型 说明
list[].idlong品牌记录主键 ID。
list[].uidlong品牌 UID；新增商品时传入 commonAttribute.brandUid。
list[].namestring品牌名称。
hasMoreboolean是否还有下一页。
nextLastIdlong下一次请求应传入的 lastId；没有更多数据时返回当前页最后一条的 id 或 null。

商品供应商

用于查询供应商字典，返回新增或修改商品时所需的 supplierUid。

查询供应商

POST
/openapi/v3/product/supplier-page

分页拉取供应商字典，供新增商品接口传入 supplierUid。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
lastIdlong否分页游标。首次传 0；后续传上次响应中的 nextLastId。
limitint否单次返回条数；默认 100，最大 100。
namestring否供应商名称，按精确匹配过滤。

业务说明

  • 服务端固定按 id asc 顺序分页返回。
  • 仅返回未删除供应商，即 enable != -1 的记录。
  • 新增商品时请使用返回的 uid 作为 supplierUid。

请求示例

{
  "account": "store001",
  "lastId": 0,
  "limit": 100,
  "name": "鲜果原料供应商"
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "501",
        "uid": "3001",
        "number": "SUP-001",
        "name": "鲜果原料供应商"
      }
    ],
    "hasMore": false,
    "nextLastId": "501"
  }
}

返回字段说明

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

字段 类型 说明
idlong供应商表主键 ID，用于分页游标。
uidlong供应商 UID，新增商品时传入 supplierUid。
numberstring供应商编号。
namestring供应商名称。

商品口味

用于查询商品口味字典，返回新增或修改商品时所需的 tastes[].uid。

查询商品口味

POST
/openapi/v3/product/attribute-page

分页拉取商品口味字典，主要用于新增商品时传入 tastes[].uid；返回口味名称、口味值及所属口味组信息。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
lastIdlong否分页游标。首次传 0；后续传上次响应中的 nextLastId。
limitint否单次返回条数；默认 100，最大 100。
namestring否口味名称，按 attributeName 精确匹配过滤。

业务说明

  • 服务端固定按 id asc 顺序分页返回。
  • 新增商品时请使用返回的 uid 作为 tastes[].uid。
  • 响应同时返回口味所属口味组信息：packageUid、packageName、packageType。

请求示例

{
  "account": "store001",
  "lastId": 0,
  "limit": 100,
  "name": "椰果"
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "601",
        "uid": "1622707645696449590",
        "attributeName": "椰果",
        "attributeValue": "2",
        "isDefault": 0,
        "packageUid": "1622707645694362262",
        "packageName": "加料",
        "packageType": 1
      }
    ],
    "hasMore": false,
    "nextLastId": "601"
  }
}

返回字段说明

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

字段 类型 说明
idlong口味表主键 ID，用于分页游标。
uidlong口味 UID，新增商品时传入 tastes[].uid。
attributeNamestring口味名称。
attributeValuestring口味值。
isDefaultint是否默认项。
packageUidlong所属口味组 UID。
packageNamestring所属口味组名称。
packageTypeint所属口味组类型 1:多选 + 非必选 2:单选 + 非必选 3:多选 + 必选 4:单选 + 必选。
INVENTORY

商品库存接口

用于库存查询和批量库存写入，适合库存轮询、库存对账、盘点回写、出入库同步等场景。

  • 库存写接口单次最多 100 条。
  • 幂等继续使用请求头 X-Request-Id。
  • 批量设置商品库存 写入最终库存值；批量调整商品库存 写入库存变动值。

查询商品库存

POST
/openapi/v3/product/stock-page

按商品主键 id 顺序分页拉取库存，仅返回 barcode、stock，适合客户轮询库存。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号，表示本次查询对应哪家门店。
lastIdlong否翻页游标。首次传 0 或不传；后续传上一次响应中的 nextLastId。

业务说明

  • 服务端固定按 id asc 顺序分页查询。
  • 单次最多返回 1000 条库存记录。
  • 服务端按 1001 条查询，多出一条则判定 hasMore = true。
  • 仅返回库存轮询所需的最小字段，不替代完整商品查询接口。

请求示例

{
  "account": "store001",
  "lastId": 0
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "barcode": "6901234567890",
        "stock": 128.0000
      },
      {
        "barcode": "6901234567891",
        "stock": 16.0000
      }
    ],
    "hasMore": true,
    "nextLastId": "1000"
  }
}

返回字段说明

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

字段 类型 说明
barcodestring商品主条码
stockdecimal当前库存数量

批量设置商品库存

POST
/openapi/v3/product/stock-batch-set

按商品 barcode 批量把库存直接写成目标值，适合把外部系统的最新账面库存一次性回写到门店。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
itemsarray<object>是库存明细，单次最多 100 条。
items[].barcodestring是商品条码。
items[].stockdecimal是要设置成的最终库存值。

业务说明

  • 单次最多处理 100 条，超过会直接报参数错误。
  • 同一请求内不允许重复传同一个 barcode。
  • 幂等继续复用请求头 X-Request-Id；若请求号重复，会在业务执行前被拦截。
  • 接口返回逐条处理结果；即使部分明细失败，已成功的明细仍会保留。

请求示例

{
  "account": "store001",
  "items": [
    {
      "barcode": "6901234567890",
      "stock": 120
    },
    {
      "barcode": "6901234567891",
      "stock": 35.5
    }
  ]
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "successCount": 1,
    "failCount": 1,
    "results": [
      {
        "barcode": "6901234567890",
        "success": true,
        "message": "success",
        "stock": 120
      },
      {
        "barcode": "NOT-EXIST-001",
        "success": false,
        "message": "商品不存在，请检查 barcode",
        "stock": null
      }
    ]
  }
}

返回字段说明

字段 类型 说明
successCountint本次成功写入的商品数量。
failCountint本次写入失败的商品数量。
results[].barcodestring商品条码。
results[].successboolean当前明细是否成功。
results[].messagestring当前明细处理结果说明。
results[].stockdecimal处理成功后的最新库存；失败时返回 null。

批量调整商品库存

POST
/openapi/v3/product/stock-batch-adjust

按商品 barcode 批量增减库存，适合做出入库、盘点差异回写等增量场景。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
itemsarray<object>是库存明细，单次最多 100 条。
items[].barcodestring是商品条码。
items[].changeStockdecimal是库存变动值；正数表示增加，负数表示扣减。

业务说明

  • 单次最多处理 100 条，超过会直接报参数错误。
  • 同一请求内不允许重复传同一个 barcode。
  • 幂等继续复用请求头 X-Request-Id；若请求号重复，会在业务执行前被拦截。
  • 接口按明细逐条处理，并返回每个商品处理后的最新库存。

请求示例

{
  "account": "store001",
  "items": [
    {
      "barcode": "6901234567890",
      "changeStock": 10
    },
    {
      "barcode": "6901234567891",
      "changeStock": -2.5
    }
  ]
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "successCount": 2,
    "failCount": 0,
    "results": [
      {
        "barcode": "6901234567890",
        "success": true,
        "message": "success",
        "stock": 138
      },
      {
        "barcode": "6901234567891",
        "success": true,
        "message": "success",
        "stock": 33
      }
    ]
  }
}

返回字段说明

返回结构与“批量设置商品库存”一致。

DISCARD

商品报损接口

用于查询门店已有收银系统产生的商品报损原因和报损记录。报损查询固定返回主单与商品明细，不提供报损写入能力。

  • 报损原因按门店查询，不分页。
  • 报损记录按报损单主表 id 游标分页，固定返回明细。
  • 报损状态仅开放 100-已完成、1-待审核、-1-已拒绝。

查询报损原因

POST
/openapi/v3/product/discard-reason/list

查询当前门店的商品报损原因字典，返回 discardreason 中的原因 UID、名称、启用状态和报损类型。

Token 消耗 固定 100 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
uidlong否报损原因 UID discardreason.uid，精确查询。
enableint否状态，1-启用，-1-已删除；不传返回全部。

请求示例

{
  "account": "store001",
  "uid": 1800000000001,
  "enable": 1
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": [
    {
      "id": 1001,
      "uid": 1800000000001,
      "detail": "临期报损",
      "enable": 1,
      "discardType": 1
    }
  ]
}

返回字段说明

字段 类型 说明
idlong报损原因表主键。
uidlong报损原因 UID，对应报损明细中的 reasonUid。
detailstring报损原因名称。
enableint状态，1-启用，-1-已删除。
discardTypeint报损类型：null/0-默认，1-门店报损，2-仓库报损，3-工厂报损，4-后厨报损。

查询商品报损

POST
/openapi/v3/product/discard-page

分页查询当前门店的商品报损记录，固定返回报损主单和报损商品明细。

Token 消耗 固定 500 token/次

请求参数

参数 类型 必填 说明
accountstring是业务门店账号。
lastIdlong否翻页游标。首次传 0 或不传；后续传上一次响应中的 nextLastId。
orderstring否排序方向，仅支持 asc、desc，默认 asc。
limitint否分页大小，默认 100，最大 100。
datetimeBeginstring否按 createdDateTime 开始时间筛选，格式 yyyy-MM-dd HH:mm:ss。
datetimeEndstring否按 createdDateTime 结束时间筛选，左闭右开。
updateTimeBeginstring否按 updateTime 开始时间筛选，格式 yyyy-MM-dd HH:mm:ss。
updateTimeEndstring否按 updateTime 结束时间筛选，左闭右开。
statusint否报损状态：100-已完成，1-待审核，-1-已拒绝；不传查询全部。

请求示例

{
  "account": "store001",
  "datetimeBegin": "2026-07-01 00:00:00",
  "datetimeEnd": "2026-07-08 00:00:00",
  "status": 100,
  "lastId": 0,
  "order": "asc",
  "limit": 100
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": 129937,
        "userId": 10001,
        "cashierUid": 100001,
        "createdDateTime": "2026-07-07 10:30:00",
        "remarks": "临期报损",
        "status": 100,
        "updateTime": "2026-07-07 10:35:00",
        "items": [
          {
            "id": 183271,
            "productUid": 180000000000100001,
            "productUnitUid": 7001,
            "quantity": 2,
            "buyPrice": 3.5,
            "sellPrice": 5.0,
            "reasonUid": 1800000000001
          }
        ]
      }
    ],
    "hasMore": true,
    "nextLastId": "129937"
  }
}

返回字段说明

字段 类型 说明
list[].idlong报损单主键。
list[].userIdint门店 ID。
list[].cashierUidlong收银员 / 操作员 UID。
list[].createdDateTimestring报损单创建时间。
list[].remarksstring备注。
list[].statusint报损状态：100-已完成，1-待审核，-1-已拒绝。
list[].updateTimestring审核更新时间。
list[].items[].idlong报损明细主键。
list[].items[].productUidlong报损商品 UID。
list[].items[].productUnitUidlong报损单位 UID。
list[].items[].quantitydecimal报损数量。
list[].items[].buyPricedecimal报损单位的进货价。
list[].items[].sellPricedecimal报损单位的销售价。
list[].items[].reasonUidlong报损原因 UID。0:未设置。大于0:可通过“查询报损原因”接口映射名称。
开放平台接口文档 - 随应用部署 - 最后更新：2026-04-25