格物 开放 API平台收银台

REST API · 接口参考

REST API 参考 · 消费者购物

平台收银台

下单与付款：用户在浏览器里用支付宝付款，平台收到支付通知后自动下单，下单失败自动退款，你不用处理退款补偿。手上有完整收货地址就直接要支付链接；没有就给用户托管结账页，让他自己填。退款、退货也在这一组。

#下单并返回支付短链 payUrl 与它的二维码 qrImageUrl

POST/v1/lm/pay/web-prepare

下单并返回支付短链 payUrl 与它的二维码 qrImageUrl（需带收货地址；idempotencyKey 同键重放返回同一张收款单）

鉴权用户态

出现在消费者 · 下单与支付

平台收款方式（手上有完整收货地址时）：返回支付短链 payUrl 与它的二维码 qrImageUrl——在电脑上或对话里优先展示二维码，用户用手机支付宝扫码付款（手机上已登录），否则把 payUrl 交给用户打开付款；付款成功后平台自动下单，失败自动退款。同一 idempotencyKey 重放返回同一张收款单（outTradeNo 不变），内容不同则 409。链接自首次生成起约 23 小时内可付。付款结果以收款单查询为准。

请求体application/json

字段类型必填说明
itemsobject[]是
items[].productIdstring是商品接口返回的 id
items[].skuIdstring是商品详情 skus[].skuId，必填
items[].qtyinteger否默认 1。≥ 1
receiverobject否收货人。地区用行政区划码，先用 GET /v1/divisions 级联查出
receiver.receiverstring是收货人姓名
receiver.receiverPhonestring是
receiver.divisionCodestring是区县级（四级）区划码，必填。例：330106
receiver.townDivisionCodestring否乡镇级（五级）区划码，强烈建议带上，缺了上游可能拒单。例：330106001
receiver.addressDetailstring是
addressIdstring否与 receiver 二选一，必须给其一
idempotencyKeystring是你方订单唯一号（同一用户内唯一）。最长 128
devicestring否收银台类型。payUrl 为短链时打开它的设备会自动选择（手机 / 电脑），此参数可不传；未启用短链时决定网关地址的类型（缺省 pc）。可选值：pc / mobile。默认 "pc"
returnUrlstring否https，域名须为登记的 callback_url 域名或其子域；不传则停在支付宝成功页
remarkstring否

返回字段

字段类型说明
okboolean
outTradeNostring
moneystring
payUrlstring支付短链（约 60 字符）。打开时按设备生成支付宝收银台（手机 / 电脑），付完回跳 returnUrl；已付 / 已关 / 超时会给出提示页。手机上直接打开即可付款
qrImageUrlstringpayUrl 的二维码图片（PNG，几百字节），可直接放进对话或网页让用户用手机支付宝扫码；未配置公网地址时不返回，payUrl 也回落为支付宝网关地址

错误

  • 400 EMPTY / SKU_REQUIRED / PRODUCT_NOT_FOUND / SKU_UNAVAILABLE / BAD_RECEIVER / ADDRESS_NOT_FOUND / BAD_IDEMPOTENCY_KEY / BAD_DEVICE / BAD_RETURN_URL / PAY_EXPIRED
  • 409 IDEMPOTENCY_CONFLICT / ALREADY_PAID / PAY_CLOSED / IN_PROGRESS
  • 503 PAY_NOT_CONFIGURED

调用示例

1curl -X POST "https://api.gowu.net/v1/lm/pay/web-prepare" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001" \8  -H "content-type: application/json" \9  -d '{"items":[{"productId":"…","skuId":"…","quantity":1}],"receiver":{"receiver":"张三","receiverPhone":"138…","divisionCode":"330106","townDivisionCode":"330106001","addressDetail":"…"},"idempotencyKey":"your-order-20261015-0001","device":"pc","returnUrl":"https://your-domain.example.com/pay/done"}'

返回示例

1{2  "ok": true,3  "outTradeNo": "string",4  "money": "string",5  "payUrl": "string",6  "qrImageUrl": "string"7}

#托管结账页：返回 checkoutUrl，用户在页面上核对、填地址后用支付宝付款

POST/v1/lm/checkout/sessions

托管结账页：返回 checkoutUrl，用户在页面上核对、填地址后用支付宝付款（地址可不传；带 idempotencyKey 时同键重试返回同一个结账页）

鉴权用户态

出现在消费者 · 下单与支付

平台收款方式（手上没有完整收货地址时）：建结账会话，把 checkoutUrl 交给用户，用户在平台结账页核对商品、补地址，跳浏览器支付宝付款。付款成功后平台自动下单，失败自动退款。checkoutUrl 即付款凭据，只发给对应用户。地址可不传，由用户在页面填写。

请求体application/json

字段类型必填说明
itemsobject[]是
items[].productIdstring是商品接口返回的 id
items[].skuIdstring是商品详情 skus[].skuId，必填
items[].qtyinteger否默认 1。≥ 1
receiverobject否收货人。地区用行政区划码，先用 GET /v1/divisions 级联查出
receiver.receiverstring是收货人姓名
receiver.receiverPhonestring是
receiver.divisionCodestring是区县级（四级）区划码，必填。例：330106
receiver.townDivisionCodestring否乡镇级（五级）区划码，强烈建议带上，缺了上游可能拒单。例：330106001
receiver.addressDetailstring是
idempotencyKeystring否幂等键（建议必传，用你的订单号）。同键重试返回同一个结账页（新的 checkoutUrl，旧链接失效），不会出现两个都能付的页面；同键不同内容返回 409 IDEMPOTENCY_CONFLICT，已过期且未付返回 409 SESSION_EXPIRED。最长 128
addressIdstring否
returnUrlstring否付完「返回应用」的地址；https，域名须为登记的 callback_url 域名或其子域
remarkstring否

返回字段

字段类型说明
okboolean
sessionIdstring
checkoutUrlstring
expiresAtstring(date-time)
moneystring

错误

  • 400 EMPTY / SKU_REQUIRED / PRODUCT_NOT_FOUND / SKU_UNAVAILABLE / BAD_RECEIVER / ADDRESS_NOT_FOUND / BAD_RETURN_URL
  • 503 NOT_CONFIGURED

调用示例

1curl -X POST "https://api.gowu.net/v1/lm/checkout/sessions" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001" \8  -H "content-type: application/json" \9  -d '{"items":[{"productId":"…","skuId":"…","quantity":1}],"idempotencyKey":"your-order-20261015-0001","returnUrl":"https://your-domain.example.com/pay/done"}'

返回示例

1{2  "ok": true,3  "sessionId": "string",4  "checkoutUrl": "string",5  "expiresAt": "2026-11-02T10:00:00+08:00",6  "money": "string"7}

#结账会话进度

GET/v1/lm/checkout/sessions/{sessionId}

结账会话进度（待支付 / 已过期 / 已发起支付 + 收款单状态）

鉴权用户态

state：open 待支付 / expired 未支付已过期 / paying 已发起支付（再看 payStatus，fulfilled 即已下单）。

路径参数

字段类型必填说明
sessionIdstring是

返回字段

字段类型说明
okboolean
sessionIdstring
statestring可选值：open / expired / paying
outTradeNostring
payStatusstring
purchaseOrderIdstring
moneystring

错误

  • 404 资源不存在，或不归属你的 appKey / 当前用户

调用示例

1curl -X GET "https://api.gowu.net/v1/lm/checkout/sessions/{sessionId}" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "ok": true,3  "sessionId": "string",4  "state": "open",5  "outTradeNo": "string",6  "payStatus": "string",7  "purchaseOrderId": "string",8  "money": "string"9}

#收款单列表

GET/v1/lm/pay/orders

鉴权用户态

查询参数

字段类型必填说明
limitinteger否默认 50。≥ 1，≤ 200
返回字段28 个，点击展开
字段类型说明
itemsobject[]
items[].outTradeNostring收款单号
items[].statusstring可选值：pending_payment / paid / fulfilling / fulfilled / refund_requested / awaiting_return / returning / refund_pending / manual_review / refunded / partially_refunded / refund_failed / closed
items[].gatewaystring可选值：alipay / wxpay
items[].tradeNostring
items[].moneystring金额（元）
items[].namestring
items[].itemsobject[]
items[].receiverobject
items[].upstreamOrderIdstring付款后平台自动下单得到的采购单号
items[].createdAtstring
items[].paidAtstring可能为 null
items[].fulfilledAtstring可能为 null
items[].refundedAtstring可能为 null
items[].refundItemsobject[]详情接口返回：按订单行的退款进度
items[].refundItems[].subOrderIdstring
items[].refundItems[].amountnumber
items[].refundItems[].statusstring
items[].refundItems[].createdAtstring
items[].returnInfoobject需要退货时返回：寄回地址与可选快递公司
items[].returnInfo.subOrderIdstring
items[].returnInfo.refunderNamestring
items[].returnInfo.refunderTelstring
items[].returnInfo.refunderAddressstring
items[].returnInfo.carriersobject[]
items[].returnInfo.carriers[].codestring
items[].returnInfo.carriers[].namestring
items[].returnInfo.readyboolean

调用示例

1curl -X GET "https://api.gowu.net/v1/lm/pay/orders" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "items": [3    {4      "outTradeNo": "string",5      "status": "pending_payment",6      "gateway": "alipay",7      "tradeNo": "string",8      "money": "string",9      "name": "string",10      "items": [11        null12      ],13      "receiver": null,14      "upstreamOrderId": "string",15      "createdAt": "string",16      "paidAt": "string",17      "fulfilledAt": "string",18      "refundedAt": "string",19      "refundItems": [20        {}21      ],22      "returnInfo": {23        "subOrderId": "string",24        "refunderName": "string",25        "refunderTel": "string",26        "refunderAddress": "string",27        "carriers": [],28        "ready": true29      }30    }31  ]32}

#收款单详情

GET/v1/lm/pay/orders/{outTradeNo}

收款单详情（付款后查它：status = fulfilled 即已下单，带订单号与退款进度）

鉴权用户态

出现在消费者 · 下单与支付

付款后轮询它：status 变为 fulfilled 且有 upstreamOrderId 即已下单。也用来看退款进度（refundItems）和退货信息（returnInfo）。

路径参数

字段类型必填说明
outTradeNostring是

查询参数

字段类型必填说明
subOrderIdstring否退货阶段指定订单行
返回字段27 个，点击展开 · 平台收款单
字段类型说明
outTradeNostring收款单号
statusstring可选值：pending_payment / paid / fulfilling / fulfilled / refund_requested / awaiting_return / returning / refund_pending / manual_review / refunded / partially_refunded / refund_failed / closed
gatewaystring可选值：alipay / wxpay
tradeNostring
moneystring金额（元）
namestring
itemsobject[]
receiverobject
upstreamOrderIdstring付款后平台自动下单得到的采购单号
createdAtstring
paidAtstring可能为 null
fulfilledAtstring可能为 null
refundedAtstring可能为 null
refundItemsobject[]详情接口返回：按订单行的退款进度
refundItems[].subOrderIdstring
refundItems[].amountnumber
refundItems[].statusstring
refundItems[].createdAtstring
returnInfoobject需要退货时返回：寄回地址与可选快递公司
returnInfo.subOrderIdstring
returnInfo.refunderNamestring
returnInfo.refunderTelstring
returnInfo.refunderAddressstring
returnInfo.carriersobject[]
returnInfo.carriers[].codestring
returnInfo.carriers[].namestring
returnInfo.readyboolean

错误

  • 404 资源不存在，或不归属你的 appKey / 当前用户

调用示例

1curl -X GET "https://api.gowu.net/v1/lm/pay/orders/{outTradeNo}" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "outTradeNo": "string",3  "status": "pending_payment",4  "gateway": "alipay",5  "tradeNo": "string",6  "money": "string",7  "name": "string",8  "items": [9    null10  ],11  "receiver": null,12  "upstreamOrderId": "string",13  "createdAt": "string",14  "paidAt": "string",15  "fulfilledAt": "string",16  "refundedAt": "string",17  "refundItems": [18    {19      "subOrderId": "string",20      "amount": 0,21      "status": "string",22      "createdAt": "string"23    }24  ],25  "returnInfo": {26    "subOrderId": "string",27    "refunderName": "string",28    "refunderTel": "string",29    "refunderAddress": "string",30    "carriers": [31      {32        "code": "string",33        "name": "string"34      }35    ],36    "ready": true37  }38}

#退款申请

POST/v1/lm/pay/refund

退款申请（未发货整单退；多件需指定订单行）

鉴权用户态

按订单行退款，一单多行时 subOrderId 必填。未发货原路退款；已发货需要退货的，状态会变为 awaiting_return，寄回后回传运单。

请求体application/json

字段类型必填说明
outTradeNostring是
subOrderIdstring否订单行 id（orderLineId）
reasonIdstring否可选原因 id；不传取第一个可选原因
reasonstring否

返回字段

字段类型说明
okboolean
statusstring可选值：refund_requested / awaiting_return / refund_pending
messagestring

错误

  • 400 NOT_PAID / CLOSED / FULFILLING / SUB_ORDER_REQUIRED / SUB_ORDER_INVALID / ALREADY_SHIPPED / NO_REMAINING / SUBMIT_FAILED 等
  • 404 资源不存在，或不归属你的 appKey / 当前用户

调用示例

1curl -X POST "https://api.gowu.net/v1/lm/pay/refund" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001" \8  -H "content-type: application/json" \9  -d '{"outTradeNo":"…","subOrderId":"…","reason":"不想要了"}'

返回示例

1{2  "ok": true,3  "status": "refund_requested",4  "message": "string"5}

#售后列表

GET/v1/lm/refunds

售后列表；render=1 取可退金额与可选原因（选中的原因 id 作为 reasonId 传给退款申请）

鉴权用户态

出现在消费者 · 售后

带 render=1&orderId=&orderLineId=：返回这一行的可退金额和可选原因，把选中的 reasonTextId 作为 reasonId 传给 POST /v1/lm/pay/refund（原因随订单状态变化，不要写死；不传时平台取第一条）。不带 render 时返回这个用户的上游售后单列表（可用 orderId 筛选）。上游失败时 200 且 success: false。

查询参数

字段类型必填说明
renderstring否可选值：1
orderIdstring否子订单号
orderLineIdstring否订单行 id，render 时必填
返回字段22 个，点击展开 · 列表时返回 items；render 时返回 success / maxRefundFee / reasons
字段类型说明
itemsobject[]
items[].disputeIdstring售后单号
items[].orderIdstring
items[].orderLineIdstring
items[].statusinteger1 退货待处理 / 2 待买家退货 / 3 待商家收货 / 4 退款关闭 / 5 退款成功 / 6 已拒绝 / 17 取消中
items[].displayStatusstring
items[].bizClaimTypeinteger1 仅退款 / 3 退货退款
items[].amountnumber
items[].reasonstring
items[].refunderNamestring
items[].refunderTelstring
items[].refunderAddressstring
items[].canSubmitReturnboolean
items[].createdAtstring
successboolean
messagestring
maxRefundFeenumber最多可退（元）
reasonsobject[]
reasons[].reasonTextIdstring
reasons[].reasonTipsstring
reasons[].proofRequiredboolean
reasons[].refundDescRequiredboolean

错误

  • 400 render 缺少 orderId / orderLineId
  • 404 资源不存在，或不归属你的 appKey / 当前用户

调用示例

1curl -X GET "https://api.gowu.net/v1/lm/refunds?render=1&orderId=…&orderLineId=…" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "items": [3    {4      "disputeId": "string",5      "orderId": "string",6      "orderLineId": "string",7      "status": 0,8      "displayStatus": "string",9      "bizClaimType": 0,10      "amount": 0,11      "reason": "string",12      "refunderName": "string",13      "refunderTel": "string",14      "refunderAddress": "string",15      "canSubmitReturn": true,16      "createdAt": "string"17    }18  ],19  "success": true,20  "message": "string",21  "maxRefundFee": 0,22  "reasons": [23    {24      "reasonTextId": "string",25      "reasonTips": "string",26      "proofRequired": true,27      "refundDescRequired": true28    }29  ]30}

#售后详情 / 撤销售后

GETPOST/v1/lm/refunds/{disputeId}

售后详情 / 撤销售后（action=cancel）

鉴权用户态

出现在消费者 · 售后

GET

售后详情

读取时会同步一次上游状态。钱是否已退到用户手里以收款单 status / refundItems 为准。

路径参数

字段类型必填说明
disputeIdstring是

返回字段

字段类型说明
disputeIdstring售后单号
orderIdstring
orderLineIdstring
statusinteger1 退货待处理 / 2 待买家退货 / 3 待商家收货 / 4 退款关闭 / 5 退款成功 / 6 已拒绝 / 17 取消中
displayStatusstring
bizClaimTypeinteger1 仅退款 / 3 退货退款
amountnumber
reasonstring
refunderNamestring
refunderTelstring
refunderAddressstring
canSubmitReturnboolean
createdAtstring

错误

  • 404 资源不存在，或不归属你的 appKey / 当前用户

POST

撤销售后

用户不想退了时撤销；撤销后收款单回到原状态，钱不退。

路径参数

字段类型必填说明
disputeIdstring是

查询参数

字段类型必填说明
actionstring否可选值：cancel。默认 "cancel"

返回字段

字段类型说明
okboolean
messagestring

错误

  • 400 见 message

调用示例

1curl -X GET "https://api.gowu.net/v1/lm/refunds/{disputeId}" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "disputeId": "string",3  "orderId": "string",4  "orderLineId": "string",5  "status": 0,6  "displayStatus": "string",7  "bizClaimType": 0,8  "amount": 0,9  "reason": "string",10  "refunderName": "string",11  "refunderTel": "string",12  "refunderAddress": "string",13  "canSubmitReturn": true,14  "createdAt": "string"15}

#退货退款：回传退货运单号

POST/v1/lm/pay/refund/return

鉴权用户态

寄回商品后调用。快递公司编码取自收款单详情的 returnInfo.carriers。

请求体application/json

字段类型必填说明
outTradeNostring是
logisticsCompanystring是returnInfo.carriers[].code
invoiceNostring是退货运单号
subOrderIdstring否

返回字段

字段类型说明
okboolean
statusstring例：returning
messagestring

错误

  • 400 NOT_AWAITING_RETURN / BAD_CARRIER / RETURN_SUBMIT_FAILED 等
  • 404 资源不存在，或不归属你的 appKey / 当前用户

调用示例

1curl -X POST "https://api.gowu.net/v1/lm/pay/refund/return" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001" \8  -H "content-type: application/json" \9  -d '{"outTradeNo":"string","logisticsCompany":"string","invoiceNo":"string"}'

返回示例

1{2  "ok": true,3  "status": "returning",4  "message": "string"5}