lm_search_products 搜索商品

搜索 LinkedMall 商品。返回 { items[{ id（即 productId）, title, price, marketPrice, imageUrl, category, brand, shopName, availability(in_stock/out_of_stock) }], page, pageSize, total }。需要终端用户身份（连接上的 x-open-user）才能用关键词、类目、品牌、价格、排序与翻页；没有身份时只返回不带条件的第一页（带条件会报 NEED_LOGIN）。下单前用 lm_get_product 取 skuId。

对应 POST /v1/lm/products/search只读

lm_get_product 商品详情

商品详情。返回商品信息与 skus[{ skuId, specs（规格，如 颜色/尺码）, price, stock, canSell, image }]。按用户想要的规格选出 skuId 用于下单；canSell=false 的 SKU 不可买；stock=-1 表示库存不公开（不是没货），0 才是没货。skus 为空的商品暂时不能下单。商品下架返回 NOT_FOUND。

对应 GET /v1/lm/products/{id}只读

lm_list_categories 商品类目

LinkedMall 商品类目。返回 items[{ category（类目名）, count }]；把 category 原文传给 lm_search_products 的 category。

对应 GET /v1/lm/categories只读

lm_list_divisions 行政区划

逐级查询行政区划码，返回 items[{ code, name, level }]。从 parent="1"（缺省）开始：level 2 省 → 3 市 → 4 区县（这一级的 code 就是下单要的 divisionCode）→ 5 乡镇街道（townDivisionCode）。每次把上一级选中的 code 作为 parent 传入。

对应 GET /v1/divisions只读

lm_checkout_preview 结算试算

按商品与件数试算应付金额（不会下单）。返回 { render: { lines[{ productId, skuId, itemName, skuText, itemPrice, quantity }], totalFee, payable } }，payable 为应付金额（元）。商品不可售返回 PRODUCT_NOT_FOUND / SKU_UNAVAILABLE。

对应 POST /v1/lm/checkout/render只读需要终端用户

lm_create_payment_link 下单并获取付款码

创建平台收款单，返回 { outTradeNo（收款单号）, money, payUrl（支付短链）, qrImageUrl（payUrl 的二维码图片）}，结果里还附带二维码图像。优先把二维码展示给用户，让他用手机支付宝扫码付款（手机上已登录支付宝）；不能展示图片时把 payUrl 发给用户点开（手机、电脑都能打开，自动选收银台）。用户付款后平台才向上游下单；之后用 lm_get_payment(outTradeNo) 轮询，status=fulfilled 即下单成功。付款期限约 23 小时，超时自动关单、不扣钱。idempotencyKey 必填，用你自己的订单号：同一个键重试拿到的是同一张收款单与同一张码，不会产生两张能付的单；同键但商品或地址不同 → IDEMPOTENCY_CONFLICT；已付 → ALREADY_PAID（带 outTradeNo，去查结果）；已关闭 → PAY_CLOSED、过期 → PAY_EXPIRED（换新键重下）。收货地址传 addressId 或 receiver 二选一。

对应 POST /v1/lm/pay/web-prepare需要终端用户

lm_create_checkout_session 创建托管结账页

创建平台托管的结账页，返回 { sessionId, checkoutUrl, expiresAt, money, items }；把 checkoutUrl 交给用户，他在页面上填/确认地址并用支付宝付款。适合你手上没有收货地址时。用户须在 expiresAt（约 30 分钟）内开始付款；之后用 lm_get_checkout_session(sessionId) 查进度。idempotencyKey 必填：同键重试返回同一个结账页的新链接（旧链接失效），不会出现两个能付的页面；同键不同内容 → IDEMPOTENCY_CONFLICT，已过期 → SESSION_EXPIRED。

对应 POST /v1/lm/checkout/sessions需要终端用户

lm_get_checkout_session 结账页进度

查询托管结账页进度，返回 { state, expiresAt, outTradeNo?, payStatus?, purchaseOrderId?, money? }。state：open 还没开始付款（可付）；expired 过期且未付款；paying 已生成收款单——此后看 payStatus（含义同 lm_get_payment 的 status，fulfilled 即下单成功）。purchaseOrderId 可直接传给 lm_get_order。

对应 GET /v1/lm/checkout/sessions/{sessionId}只读需要终端用户

lm_list_payments 收款单列表

当前用户的平台收款单（付款记录），返回 items[{ outTradeNo, status, money, name, items, upstreamOrderId, createdAt, paidAt, fulfilledAt, refundedAt }]。status：pending_payment 待付款 → paid 已付款 → fulfilling 下单中 → fulfilled 已下单（成功，upstreamOrderId 即订单号）；closed 超时未付已关闭（没扣钱）；refund_pending / refunded 下单失败或已退款（钱原路退回）；refund_requested 退款处理中；awaiting_return 待买家寄回退货；returning 退货运输中；partially_refunded 部分退款；refund_failed 退款失败待人工；manual_review 人工核查中。upstreamOrderId 传给 lm_get_order 看订单；退款明细看 lm_get_payment。

对应 GET /v1/lm/pay/orders只读需要终端用户

lm_get_payment 收款单详情

按收款单号查询付款、下单与退款结果（判断钱是否到账、是否已退回买家，以这里为准）。返回 { outTradeNo, status, money, upstreamOrderId, paidAt, fulfilledAt, refundItems[{ subOrderId（即 orderLineId）, amount, status }], returnInfo? }。status：pending_payment 待付款 → paid 已付款 → fulfilling 下单中 → fulfilled 已下单（成功，upstreamOrderId 即订单号）；closed 超时未付已关闭（没扣钱）；refund_pending / refunded 下单失败或已退款（钱原路退回）；refund_requested 退款处理中；awaiting_return 待买家寄回退货；returning 退货运输中；partially_refunded 部分退款；refund_failed 退款失败待人工；manual_review 人工核查中。退货阶段（awaiting_return）会带 returnInfo{ refunderName, refunderTel, refunderAddress（寄回地址）, carriers[{ code, name }], ready }：ready=true 后才能用 lm_submit_return_shipment 回传运单。

对应 GET /v1/lm/pay/orders/{outTradeNo}只读需要终端用户

lm_list_orders 订单列表

当前用户的 LinkedMall 采购订单列表，返回 items[{ id, purchaseOrderId, displayStatus, payable, items, receiver, createdAt }]。这里没有子订单与订单行；要看物流、确认收货、申请售后，用 lm_get_order(id) 取 orders[]。displayStatus 是采购单的创建状态（已创建 / 创建失败等）。

对应 GET /v1/lm/orders只读需要终端用户

lm_get_order 订单详情

订单详情。订单 id 有三层：采购订单（lm_get_order 的 id，等于收款单的 upstreamOrderId）→ 子订单（orders[].orderId，参数名 subOrderId）→ 订单行（orders[].lines[].orderLineId，参数名 orderLineId）。返回采购单信息与 orders[{ orderId（子订单 id）, displayStatus（待发货 / 待收货 / 已收货 / 交易成功 / 已关闭 / 已退款关闭）, logisticsStatus, lines[{ orderLineId, productTitle, skuId, quantity, payFee }] }]。付款下单成功后子订单可能稍晚才出现，空的话稍后再查。

对应 GET /v1/lm/orders/{id}只读需要终端用户

lm_confirm_receipt 确认收货

对一个子订单确认收货。不可撤销，且确认后不能再自助申请退款——请在用户明确确认已收到货后再调。返回 { ok, message }。

对应 POST /v1/lm/orders/{id}执行前须用户确认需要终端用户

lm_get_order_logistics 物流轨迹

查询一个子订单的物流，返回 { success, packages[{ mailNo（运单号）, companyName, traces[{ time, desc }] }] }。success=false 表示上游暂时查不到，稍后再试。

对应 GET /v1/lm/orders/{id}/logistics只读需要终端用户

lm_refund_options 可退金额与退款原因

申请退款前查询某一订单行可退的金额与可选原因，返回 { maxRefundFee, reasons[{ reasonTextId, reasonTips }], needReturn }。把用户选中的 reasonTextId 作为 lm_request_refund 的 reasonId；needReturn=true 表示货已发出，要走退货退款（用户需寄回）。已确认收货的订单行不能自助退款（NOT_REFUNDABLE）。

对应 GET /v1/lm/refunds只读需要终端用户

lm_list_refunds 售后单列表

当前用户的售后单，返回 items[{ disputeId（售后单号）, orderId（子订单）, orderLineId, status, displayStatus, amount, canSubmitReturn }]。status：1 退货待处理 / 2 待买家退货 / 3 待商家收货 / 4 退款关闭 / 5 上游已退款 / 6 商家拒绝 / 17 取消中。申请退款后用它（按子订单过滤）拿 disputeId；买家是否已收到钱以 lm_get_payment 的 refundItems 为准。

对应 GET /v1/lm/refunds只读需要终端用户

lm_request_refund 申请退款

对已下单的收款单申请退款，钱原路退回用户（平台先向上游退款，确认后再退给用户，有分钟级延迟）。按订单行退：收款单有多行时必须传 orderLineId。未发货 → 仅退款；已发货未签收 → 退货退款（返回 status=awaiting_return，接着看 lm_get_payment 的 returnInfo 并回传运单）；已确认收货 → 不可自助退款。收款单须已下单（status=fulfilled），否则返回 FULFILLING / NOT_PAID 等。reasonId 可省略（平台自动选一个有效原因）。返回 { ok, status, message }；重复申请返回当前进度，不会重复退。请在用户明确确认后调用。

对应 POST /v1/lm/pay/refund执行前须用户确认需要终端用户

lm_get_refund 售后单详情

按售后单号查询上游售后进度（字段同 lm_list_refunds 的 items[]）。买家是否已收到退款以 lm_get_payment 的 refundItems 为准。

对应 GET /v1/lm/refunds/{disputeId}只读需要终端用户

lm_cancel_refund 撤销售后

撤销一个进行中的售后单（用户不想退了）。返回 { ok, message }。请在用户明确确认后调用。

对应 POST /v1/lm/refunds/{disputeId}执行前须用户确认需要终端用户

lm_submit_return_shipment 回传退货运单

退货退款时，用户把货寄回后回传快递公司与运单号；不回传上游会超时关闭退款。前提：lm_get_payment 的 status=awaiting_return 且 returnInfo.ready=true（寄回地址在 returnInfo 里）。返回 { ok, status: "returning" }。

对应 POST /v1/lm/pay/refund/return需要终端用户

buyer_list_addresses 地址簿

当前用户的收货地址，返回 items[{ id（即 addressId）, receiver, receiverPhone, province, city, district, divisionCode, townDivisionCode, addressDetail, isDefault, complete, missingFields }]。下单时把 id 作为 addressId 传入；没有 divisionCode 的地址不能用于 LinkedMall 下单。

对应 GET /v1/buyer/addresses只读需要终端用户

无参数

buyer_add_address 新增地址

为当前用户新增收货地址，返回 { address }，新地址的 id 即 addressId。区划码先用 lm_list_divisions 逐级查出。

对应 POST /v1/buyer/addresses需要终端用户

buyer_update_address 修改地址

修改一条收货地址。整条覆盖：没传的字段会被清空（不传 isDefault 会取消默认）——先用 buyer_list_addresses 取出原值，改动后把全部字段一起传回。

对应 PUT /v1/buyer/addresses/{id}需要终端用户

buyer_set_default_address 设为默认地址

把一条地址设为默认收货地址（其他地址自动取消默认）。返回 { ok }。

对应 POST /v1/buyer/addresses/{id}需要终端用户

buyer_delete_address 删除地址

删除一条收货地址（已下的订单保留下单时的地址，不受影响）。返回 { ok }。请在用户确认后调用。

对应 DELETE /v1/buyer/addresses/{id}执行前须用户确认需要终端用户

account_whoami 当前接入信息

当前接入方的配置自查（不需要终端用户），返回 { appKey, callbackConfigured（false 时不能传 returnUrl）, catalogUnrestricted（true 时无用户身份也能搜索翻页）, allowedEndpoints }。

对应 GET /v1/access-clients/me只读

无参数