得物（Poizon）V2 接口文档

基础地址：https://openapi.dajisaas.com
所有得物接口路径前缀均为 /poizonV2/。

1. 概述与接入说明

支持的能力
关键词搜索、商品详情、预售余额查询、下单与支付、订单查询、取消订单、物流轨迹查询。

注意事项

得物功能需单独开通。 调用任何 /poizonV2/* 接口前，请联系平台为你的 Access Key 开通得物权限。

所有订单均使用预售余额支付。 下单前请确保余额充足，可通过「余额查询」接口确认。若下单后采购失败，预售金额将原路退回。

收货地址必须位于中国大陆境内。

得物接口为拉取（pull）模式。 平台不会主动推送订单或物流状态，请通过「订单查询」和「物流轨迹查询」主动轮询。

商品搜索关键词： 中文关键词传 dwSpuTitle，英文关键词传 distSpuTitle。搜索结果同时返回中英文。

签名规则与其他平台一致 —— 参见「接口签名规则（Sign）」。若已有可用的签名实现，无需改动。

2. 响应格式与错误处理

2.1 标准响应结构（多数接口）

{
  "code": 200,
  "message": "success",
  "data": { },
  "timestamp": 1756012800000,
  "traceId": "a1b2c3d4e5f6",
  "cost": 235
}

字段	类型	说明
code	integer	`200` 表示成功
message	string	结果描述
data	object	业务数据
timestamp	integer	服务器时间戳，UTC 毫秒
traceId	string	链路 ID —— 反馈问题时请一并附上
cost	integer	服务器处理耗时，毫秒

2.2 简化响应结构（关键词搜索、商品详情）

这两个接口返回简化响应结构 —— 注意字段是 msg（非 message），且没有 traceId：

{ "code": 200, "msg": "success", "data": { }, "status": 200 }

每个接口页会标明其使用的响应结构。

2.3 错误响应

失败请求返回 HTTP 400，响应体为 problem-detail 格式 —— 不是上述的标准结构：

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "40002:order not exist",
  "instance": "/poizonV2/order/cancelOrder"
}

字段	说明
status	HTTP 状态码
detail	错误详情。参数错误格式为 `字段:提示`；得物业务错误为 `错误码:提示`，由得物透传
instance	被调用的接口路径

建议的客户端逻辑： 以 HTTP 2xx 且 code == 200 判定成功；收到 HTTP 400 时读取 detail。

2.4 常见错误

场景	`detail` 示例
缺少必填参数	`requestId:requestId cannot be empty`
Access Key 未开通得物	`site config not found`
签名失败	`sign verify fail`
得物业务错误	`40002:order not exist`
预售余额不足	由得物透传，见 `detail`

3. 接口参考

公共约定

每个请求都必须传 appKey。

生产环境请对请求签名并传 sign；appSecret 仅用于调试。

POST 接口中 appKey / appSecret / sign 放在 JSON body 中（与 1688、淘宝接口一致）。

所有时间戳均为 UTC 毫秒。

3.1 关键词搜索

GET /poizonV2/product/queryList
响应结构：简化（code / msg / data / status）。

支持中文或英文关键词，结果同时返回中英文。

Query 参数

名称	类型	必填	说明
appKey	string	Y	平台 appKey
appSecret	string	N	密钥，仅用于调试。生产环境用 `sign`
startId	integer	N	分页游标，从 0 开始
pageSize	integer	N	最大 50；推荐 20 以获得最佳结果
dwSpuTitle	string	N	中文关键词
distSpuTitle	string	N	英文关键词
dwDesignerId	string	N	款式 / 货号
distBrandName	array[string]	N	品牌名称，0–200 项
distCategoryl1Name	array[string]	N	一级类目，0–200 项
distCategoryl2Name	array[string]	N	二级类目，0–200 项
distCategoryl3Name	array[string]	N	三级类目，0–200 项
distFitPeopleName	array[string]	N	适用人群，0–200 项
season	string	N	季节
distStatus	string	N	`PRODUCT_ON` = 在售，`PRODUCT_OFF` = 已下架
modifyStartTime	integer	N	修改起始时间，UTC 毫秒
modifyEndTime	integer	N	修改结束时间，UTC 毫秒
querySku	boolean	N	是否返回 SKU 信息
language	string	N	商品内容的响应语言，默认 `en`

响应 data —— data.total、data.spuList[] 含 dwSpuTitle / distSpuTitle / dwSpuId / image / baseImage / authPrice / 类目 / season / distStatus / sizeChart / modifyTime / createTime …。

3.2 商品详情

GET /poizonV2/product/queryDetail
响应结构：简化（code / msg / data / status）。

Query 参数

名称	类型	必填	说明
appKey	string	Y	平台 appKey
appSecret	string	N	仅用于调试
dwSpuId	integer	Y	得物 SPU ID
distSpuId	string	N	分销商 SPU ID
dwDesignerId	string	N	款式 / 货号
language	string	N	商品内容的响应语言，默认 `en`

响应 data —— SPU 字段 + data.skuList[] 含 dwSkuId / minBidPrice / saleAttr[] / skuLink …。

minBidPrice 为当前最低报价，系统会自动回填 —— 无需额外调用报价接口。

3.3 创建订单与支付

POST /poizonV2/order/createOrder
响应结构：标准。

创建新订单并使用预售余额支付。支付成功后开始采购；若采购失败，预售金额原路退回。

requestId 为幂等键。订单创建后不可更改 —— 使用相同 requestId 重试不会重复创建订单。

收货地址必须位于中国大陆境内。

下单前请用「余额查询」接口确认余额；余额不足会导致下单失败。

Body 参数

名称	类型	必填	说明
appKey	string	Y	平台 AppKey
appSecret	string	N	仅用于调试
requestId	string	Y	唯一请求 ID，32–64 位。幂等键
shippingAddress	object	Y	收货地址（限中国大陆）
shippingAddress.name	string	Y	姓名
shippingAddress.phone	string	Y	手机号
shippingAddress.province	string	Y	省
shippingAddress.city	string	Y	市
shippingAddress.district	string	Y	区
shippingAddress.detailAddress	string	Y	详细地址
shippingAddress.email	string	N	邮箱
product	object	Y	商品对象
product.dwSpuId	integer	Y	得物 SPU ID
product.dwSkuId	integer	Y	得物 SKU ID
product.distSpuId	string	Y	分销商 SPU ID
product.distSkuId	string	Y	分销商 SKU ID
product.quantity	integer	Y	数量，1–5
product.price	integer	Y	单件价格，单位分，币种 CNY

响应 data

字段	类型	说明
requestId	string	你的唯一请求 ID
customerOrderNo	string	客户订单号 —— 取消 / 查询 / 物流时均使用此号
distOrderNo	string	主订单号
orderItems	array	子订单列表
orderItems[].distSubOrderNo	string	子订单号
orderItems[].orderStatus	string	订单状态
orderItems[].dwSkuId	string	得物 SKU ID
orderItems[].distSkuId	string	分销商 SKU ID
orderItems[].quantity	integer	数量
orderItems[].realPayAmount	string	实付金额
orderItems[].currency	string	支付币种
orderItems[].createTime	integer	创建时间，UTC 毫秒
orderItems[].modifyTime	integer	最后修改时间，UTC 毫秒
orderItems[].failMessage	string	失败原因（如有）

3.4 订单查询

POST /poizonV2/order/queryOrderInfo
响应结构：标准。

所有筛选参数均为可选，按需组合。

Body 参数

名称	类型	必填	说明
appKey	string	Y	平台 AppKey
appSecret	string	N	仅用于调试
pageNum	integer	N	页码
pageSize	integer	N	每页条数，1–200
customerOrderNo	array[string]	N	客户订单号，0–200 项
distOrderNo	array[string]	N	主订单号，0–200 项
distSubOrderNo	array[string]	N	子订单号，0–200 项
orderStatus	string	N	`PENDING_PAY` / `PAID` / `SELLER_PENDING_SHIP` / `SELLER_SHIPPED` / `PLATFORM_SHIP` / `COMPLETED` / `FAILED` / `RETURN_GOOD`
dwSkuId	array[string]	N	得物 SKU ID，0–200 项
distSkuId	array[string]	N	分销商 SKU ID，0–200 项
trackingNo	array[string]	N	运单号，0–200 项
createStartTime	integer	N	创建起始，UTC 毫秒
createEndTime	integer	N	创建结束，UTC 毫秒
modifyStartTime	integer	N	修改起始，UTC 毫秒
modifyEndTime	integer	N	修改结束，UTC 毫秒

响应 data

字段	类型	说明
total	integer	订单总数
orderList	array	订单列表
orderList[].id	integer	记录 ID
orderList[].customerOrderNo	string	客户订单号
orderList[].distOrderNo	string	主订单号
orderList[].distSubOrderNo	string	子订单号
orderList[].orderStatus	string	订单状态
orderList[].dwSpuId	string	得物 SPU ID
orderList[].dwSkuId	string	得物 SKU ID
orderList[].distSkuId	string	分销商 SKU ID
orderList[].distSpuTitle	string	商品标题
orderList[].distBrandName	string	品牌名
orderList[].designerId	string	款式 / 货号
orderList[].distCategoryl1Name	string	一级类目
orderList[].distCategoryl2Name	string	二级类目
orderList[].distCategoryl3Name	string	三级类目
orderList[].image	string	商品图片
orderList[].size	string	尺码
orderList[].maxQuantity	integer	数量
orderList[].realPayAmount	string	实付金额
orderList[].currency	string	币种
orderList[].userName	string	收货人姓名
orderList[].userId	string	用户 ID
orderList[].carrier	string	承运商（得物 → 买家）
orderList[].trackingNo	string	运单号（得物 → 买家）
orderList[].headCarrier	string	头程承运商
orderList[].headTrackingNo	string	头程运单号
orderList[].fulfillmentMode	string	履约方式
orderList[].fulfillmentModeDesc	string	履约方式描述
orderList[].returnStatus	integer	退货状态
orderList[].returnStatusDesc	string	退货状态描述
orderList[].reverseItemNo	string	退货商品编号
orderList[].createTime	integer	创建时间，UTC 毫秒
orderList[].modifyTime	integer	最后修改时间，UTC 毫秒

3.5 取消订单

POST /poizonV2/order/cancelOrder
响应结构：标准。

提交订单取消申请。能否取消成功取决于当前订单状态 —— 请查看响应中的 failDetailList。

Body 参数

名称	类型	必填	说明
appKey	string	Y	平台 AppKey
appSecret	string	N	仅用于调试
customerOrderNo	string	Y	创建订单返回的客户订单号

响应 data

字段	类型	说明
successTotal	integer	成功取消的子订单数
failTotal	integer	未能取消的子订单数
failDetailList	array	失败明细
failDetailList[].id	integer	子订单记录 ID
failDetailList[].failReason	string	失败原因

3.6 物流轨迹查询

POST /poizonV2/order/queryLogisticsTrace
响应结构：标准。

每个子订单可能返回两段轨迹：头程（卖家 → 得物仓）与尾程（得物 → 买家）。

Body 参数

名称	类型	必填	说明
appKey	string	Y	平台 AppKey
appSecret	string	N	仅用于调试
customerOrderNo	string	Y	创建订单返回的客户订单号

响应 data

字段	类型	说明
customerOrderNo	string	客户订单号
distOrderNo	string	主订单号
userName	string	收货人姓名
userId	string	用户 ID
subOrderTraceInfo	array	各子订单轨迹信息
subOrderTraceInfo[].distSubOrderNo	string	子订单号
subOrderTraceInfo[].dwSkuId	string	得物 SKU ID
subOrderTraceInfo[].distSkuId	string	分销商 SKU ID
subOrderTraceInfo[].heardLogisticTraceInfo	object	头程轨迹（源系统字段名拼写为 `heard`，请按原样解析）
subOrderTraceInfo[].tailLogisticTraceInfo	object	尾程轨迹

两种轨迹对象结构相同：

字段	类型	说明
waybillNo	string	运单号
courierName	string	快递员姓名
courierPhone	string	快递员电话
arrivalTime	string	到达时间
trackNodeInfos	array	轨迹节点
trackNodeInfos[].node	string	节点编码
trackNodeInfos[].opeTitle	string	节点标题
trackNodeInfos[].desc	string	节点描述
trackNodeInfos[].time	string	节点时间
trackNodeInfos[].deliveryDate	string	送达日期
trackNodeInfos[].location	object	节点位置：`province`、`city`、`district`、`siteName`、`longitude`、`latitude`

3.7 余额查询

GET /poizonV2/prepayment/queryPrepaymentBalance
响应结构：标准。

返回你得物账户的预售余额。下单前请先确认余额。

Query 参数

名称	类型	必填	说明
appKey	string	Y	平台 appKey
appSecret	string	N	仅用于调试

响应 data

字段	类型	说明
imoneyDTO	object	余额对象
imoneyDTO.amount	string	预售余额，字符串格式
imoneyDTO.minUnitVal	integer	以最小单位（分）计的余额
imoneyDTO.currency	string	币种

Poizon API 说明

得物（Poizon）V2 接口文档#

1. 概述与接入说明#

2. 响应格式与错误处理#

2.1 标准响应结构（多数接口）#

2.2 简化响应结构（关键词搜索、商品详情）#

2.3 错误响应#

2.4 常见错误#

3. 接口参考#

3.1 关键词搜索#

3.2 商品详情#

3.3 创建订单与支付#

3.4 订单查询#

3.5 取消订单#

3.6 物流轨迹查询#

3.7 余额查询#

得物（Poizon）V2 接口文档

1. 概述与接入说明

2. 响应格式与错误处理

2.1 标准响应结构（多数接口）

2.2 简化响应结构（关键词搜索、商品详情）

2.3 错误响应

2.4 常见错误

3. 接口参考

3.1 关键词搜索

3.2 商品详情

3.3 创建订单与支付

3.4 订单查询

3.5 取消订单

3.6 物流轨迹查询

3.7 余额查询