# 格物知心 · 开放平台

> 格物知心（GoWu）开放 API：用开放接口搭各种购物与采购产品。按 3 个场景开放：员工福利购物（企业额度，可全额或混合支付）、企业采购（企业额度，可全额或混合支付）、消费者购物（用户在线支付）。场景就是开发者申请正式接入时选的「你的用户是谁」，审批通过后按场景开通接口权限。员工福利购物与企业采购用同一套企业额度与接口，区别只在福豆任务、签到、生日等福利玩法（企业采购不开放）和界面叫法（采购叫「企业额度」，接口字段仍是 points）。外部接入方一律自带账号体系：终端用户只通过 x-open-user 传给平台。

**先确认你的 appKey 属于哪个场景，只看对应的那一节，不要混用不同场景的接口。**

- 开放平台：https://gowu.net/open（首页）；文档：https://gowu.net/open/docs；开发者控制台：https://gowu.net/open/console
- 文档分页（按需读取，不必整站抓取）：概览 https://gowu.net/open/docs；通用约定 https://gowu.net/open/docs/conventions；商品 https://gowu.net/open/docs/catalog；Webhook 推送 https://gowu.net/open/docs/webhook；REST API · 快速开始 https://gowu.net/open/docs/rest；REST API · 鉴权与签名 https://gowu.net/open/docs/rest/auth；REST API · 福利 / 采购 · 企业与员工 https://gowu.net/open/docs/guides/enterprise；REST API · 福利 / 采购 · 额度与下单 https://gowu.net/open/docs/guides/enterprise-order；REST API · 福利 / 采购 · 售后、发票与账单 https://gowu.net/open/docs/guides/enterprise-after；REST API · 员工福利 · 福豆任务、签到与生日 https://gowu.net/open/docs/guides/welfare-extras；REST API · 消费者 · 用户与地址 https://gowu.net/open/docs/guides/retail；REST API · 消费者 · 下单与支付 https://gowu.net/open/docs/guides/retail-order；REST API · 消费者 · 售后 https://gowu.net/open/docs/guides/retail-after；接口参考 · 接入与账户 https://gowu.net/open/docs/api/access；接口参考 · 商品 https://gowu.net/open/docs/api/catalog；接口参考 · 企业与员工 https://gowu.net/open/docs/api/ent-partner；接口参考 · 企业管理 https://gowu.net/open/docs/api/ent-admin；接口参考 · 员工额度 https://gowu.net/open/docs/api/ent-points；接口参考 · 福豆任务 https://gowu.net/open/docs/api/ent-tasks；接口参考 · 结算与下单 https://gowu.net/open/docs/api/ent-trade；接口参考 · 售后与开票 https://gowu.net/open/docs/api/ent-aftersale；接口参考 · 用户与收货地址 https://gowu.net/open/docs/api/retail-user；接口参考 · 结算与订单 https://gowu.net/open/docs/api/retail-trade；接口参考 · 平台收银台 https://gowu.net/open/docs/api/retail-pay；MCP 与命令行 · 快速开始 https://gowu.net/open/docs/mcp；MCP 与命令行 · 格物购物 Skill https://gowu.net/open/docs/mcp/skill；MCP 与命令行 · 命令行 gowu https://gowu.net/open/docs/cli；MCP 与命令行 · 消费者购物 · 全流程 https://gowu.net/open/docs/mcp/flows；MCP 与命令行 · 工具参考 https://gowu.net/open/docs/mcp/tools；MCP 与命令行 · 常见问题 https://gowu.net/open/docs/mcp/faq
- API Base URL：`https://api.gowu.net`（与文档站不是同一个域）；接口路径以 `/v1` 开头
- MCP：`https://api.gowu.net/mcp`（Streamable HTTP；`Authorization: Bearer <MCP Token>` + 连接级 `x-open-user`，工具按 appKey 权限筛选，见 https://gowu.net/open/docs/mcp）
- 命令行 gowu（npm 包 @gowuai/cli，`npx -y @gowuai/cli login` 设备码登录，Agent 用 `gowu login --start` / `--finish` 两步）：能执行命令的 Agent 首选，覆盖消费者购物与员工福利 / 企业采购，见 https://gowu.net/open/docs/cli
- 格物购物 Skill（优先用命令行，也支持 MCP）：https://gowu.net/open/skills/gowu-shopping.zip，单文件 https://gowu.net/open/skills/gowu-shopping/SKILL.md；解压到 Agent 的 Skill 目录即可，按 SKILL.md 连接 MCP
- MCP 凭证：支持 OAuth 的客户端连接时不带凭证即可，会自动弹出浏览器让开发者手机号登录、选 appKey 授权（发现文档 `https://api.gowu.net/.well-known/oauth-protected-resource`）；也可用开发者控制台（https://gowu.net/open/console）签发的 MCP Token。Token 由接入方提供给你，不要编造
- 鉴权：请求头 `x-app-key`；配置 `app_secret` 后所有请求须 HMAC-SHA256 签名（v2：头 `x-sign-version: 2`，签名串 8 段：OCP-SIGN-V2 / 时间戳 / nonce / 方法 / 纯路径 / 规范化 query / sha256(body) / x-open-user）
- **怎么传参**：每个接口下的「参数」行列出顶层参数（带 * 的必填），完整入参出参表、请求与响应示例见 https://gowu.net/open/llms-full.txt（加 `?scene=` 只看一个场景）
- 终端用户：`x-open-user` 放你系统里的用户 ID，必须取自你服务端的登录态；各场景下的含义见对应一节
- 鉴权等级：**服务端签名**（接入方服务端调用：强制 HMAC 签名，不带 x-open-user）；**用户态**（交易接口：必带 x-open-user 标识终端用户，且强制 HMAC-SHA256 签名）；**appKey**（请求头带 x-app-key 即可；该 appKey 配了 app_secret 时同样要签名）；**免鉴权**（无需任何请求头，可直接调用）
- 沙箱与凭证：开发者在 https://open.gowu.net/console 手机号登录即有体验 appKey（外部 Agent 同款权限但不含退款售后，7 天有效、每天 1000 次调用）；签名密钥、MCP Token、用量与正式接入申请都在控制台（没有匿名申请接口）

## 接入场景（举例，不限于此）

- AI 购物助手（Agent）：理解需求、选品比价、代用户下单并跟进到货与售后。（场景：消费者购物）
- Skill 与工具插件：把「找商品、下单、查物流」封装成工具，交给大模型调用。（场景：消费者购物 / 员工福利购物 / 企业采购）
- 企业福利商城：节日福利、生日关怀、福豆任务，企业出钱、员工选购，也可由员工自己付现金。（场景：员工福利购物）
- 员工采购与办公集采：办公用品、劳保物资由员工按需下单，部门预算控制，企业统一结算开票。（场景：企业采购）
- 消费者小程序与网站商城：在你的小程序、H5 或网站里直接开店卖货。（场景：消费者购物）
- 订阅与周期购：咖啡、纸品、宠物粮按月配送：每期给用户一个付款链接，付款后平台发货。（场景：消费者购物）
- 导购与内容电商：在内容、社区或比价产品里嵌入购买链路。（场景：消费者购物）

## 场景 1：员工福利购物

给自己公司搭员工福利应用（类福利GO）：企业把福利额度（福豆）发给员工，员工用额度选购，差额可用支付宝补；还有福豆任务、签到、生日福利等激励玩法。

交易模式：企业额度，可全额或混合支付

完整入参出参与示例：https://gowu.net/open/llms-full.txt?scene=welfare（文本）；OpenAPI 规格：https://gowu.net/open/openapi/welfare.yaml

流程：在开发者控制台申请正式接入（选「员工福利购物」或「企业采购」）并录入企业信息 → 平台审核：开通接口权限、建好企业并开通交易（开通前下单返回 `ORG_EGP_NOT_READY`）→ 企业预充值或授信，平台按约定配置付款方式（全额由企业额度支付，或员工在企业购收银台付现金：支付宝 / 微信 / 对公）→ 你的服务端 `GET /v1/partner/orgs` 查到企业、`PUT /v1/partner/orgs/{orgId}/members/{userId}` 把你的用户绑成员工（终端用户自带账号，userId 即 x-open-user）→ 管理员 `POST /v1/enterprise/org/points` 发放额度 → 员工 `POST /v1/enterprise/orders` 下单：`payWith: "auto"` 按企业配置付款（要付现金时先让员工从结算预览的 `cash.payTypes` 选 `payType`，下单返回 `launchUrl`，员工付完后平台结清，结果以订单详情的 `mixedPay.status` 为准）→ 订单自动开票，企业按账单结算。收货地址传省、市、区名称，用 `GET /v1/divisions` 逐级选出（乡镇街道放 street；叫法不一致上游会拒单）。可选：发布福豆任务让员工赚额度或兑福利，开每日签到，按员工生日发福利。

### 企业与员工

企业在开发者控制台申请正式接入时录入，平台审批通过后建好并归属你的 appKey。你的服务端查到自己的企业后，把你的用户绑成员工、设管理员；员工的 userId 就是他之后请求时放进 x-open-user 的值。

- `GET /v1/partner/orgs` — 你的企业（审批通过后由平台建好）：orgId、审核状态（服务端签名）
  参数：无参数
- `GET /v1/partner/orgs/{orgId}` — 企业详情：审核状态、开票信息、额度池余额（服务端签名）
  参数：路径 orgId*(string)
- `GET /v1/partner/orgs/{orgId}/members` — 已绑定员工：角色、在职状态、额度余额（服务端签名）
  参数：路径 orgId*(string)
- `PUT /v1/partner/orgs/{orgId}/members/{userId}` — 把你的用户绑成员工（owner / admin / member），同时开通采购权限（服务端签名）
  参数：路径 orgId*(string)、userId*(string)；请求体 name(string)、phone(string)、role(string)、platform(string)
- `DELETE /v1/partner/orgs/{orgId}/members/{userId}` — 员工离职：未用额度退回企业额度池，收回采购权限（服务端签名）
  参数：路径 orgId*(string)、userId*(string)；请求体 reason(string)

### 企业管理

以企业管理员身份调用：x-open-user 放一个被绑成 owner 或 admin 的用户。查额度池、看账单、向员工发放额度。

- `GET /v1/enterprise/org` — 企业概览、额度池余额与流水（用户态）
  参数：无参数
- `PUT /v1/enterprise/org/profile` — 修改企业资料（名称、信用代码开户后不可改）（用户态）
  参数：请求体 shortName(string)、region(string)、contactName(string)、adminTitle(string)、adminEmail(string)、licenseUrl(string)、joinPolicy(string)、invoice(object)
- `GET /v1/enterprise/org/bills` — 企业账单（?id= 查看单张）（用户态）
  参数：查询 id(string)
- `POST /v1/enterprise/org/points` — 向员工发放 / 回收额度，或全员发放（100 = 1 元）。用 userId 指定员工即可（用户态）
  参数：请求体 action(string)、userId(string)、accountId(string)、amount*(integer)、theme(string)、name(string)、expiresInDays(number)、budgetCategory(string)、lotId(string)、remark(string)
- `GET /v1/enterprise/points/themes` — 福利类型列表（发放时 theme 的可选值）（appKey）
  参数：无参数
- `GET /v1/enterprise/org/dashboard` — 管理看板：员工数、额度池、本月发放与消耗（用户态）
  参数：查询 period(string)
- `GET /v1/enterprise/org/members` — 员工列表（含各自额度余额）（用户态）
  参数：无参数
- `GET/PUT /v1/enterprise/org/members/{userId}` — 员工详情 / 修改资料（带 ?by=userId 时路径里放你的用户 ID）（用户态）
  参数：GET：路径 accountId*(string)；查询 by(string) ｜ PUT：路径 accountId*(string)；查询 by(string)；请求体 realName(string)、departmentId(string)、birthday(string)、gender(string)
- `POST /v1/enterprise/org/members/{userId}` — 停用 / 恢复员工（带 ?by=userId 时路径里放你的用户 ID）（用户态）
  参数：路径 accountId*(string)；查询 by(string)；请求体 action*(string)、reason(string)、role(string)
- `GET/PATCH /v1/enterprise/org/points-settings` — 签到规则、发放默认有效期等企业级设置（用户态）
  参数：GET：无参数 ｜ PATCH：请求体 checkinEnabled(boolean)、checkinDailyAmount(number)、checkinStreakDays(number)、checkinStreakBonus(number)、pointsExpiryDays(number)
- `GET /v1/enterprise/org/consumption` — 员工消耗记录与汇总（按人、时间筛选）（用户态，可选）
  参数：查询 accountId(string)、from(string(date))、to(string(date))、kind(string)、page(integer)、pageSize(integer)
- `GET /v1/enterprise/org/birthdays` — 近期生日员工（?range=today|week|month），发生日福利用（用户态，可选）
  参数：查询 range(string)、missing(string)
- `GET/POST/PUT/DELETE /v1/enterprise/org/departments` — 部门管理（用户态，可选）
  参数：GET：无参数 ｜ POST：请求体 name*(string)、sort(number) ｜ PUT：请求体 id*(string)、name(string)、sort(number) ｜ DELETE：查询 id*(string)
- `GET/POST/DELETE /v1/enterprise/org/budgets` — 部门预算（用户态，可选）
  参数：GET：查询 period(string)、dashboard(string) ｜ POST：请求体 period*(string)、category(string)、departmentId(string)、amount*(integer)、alertPct(integer)、overspendPolicy(string) ｜ DELETE：查询 id*(string)

### 员工额度

以员工身份调用：查余额、流水与每批额度的到期时间，结算前判断能否用企业额度支付。

- `GET/PUT /v1/buyer/me` — 当前用户资料与所属企业（org：企业 id、名称、状态、本人角色、余额；没有归属为 null）（用户态）
  参数：GET：无参数 ｜ PUT：请求体 nickname(string)、avatar(string)、realName(string)、birthday(string)、gender(string)
- `GET /v1/enterprise/points` — 结算页判断：这单能否用企业额度支付、余额多少（用户态）
  参数：无参数
- `GET /v1/enterprise/points/summary` — 额度总览：余额、即将到期、所属企业与角色（用户态）
  参数：无参数
- `GET /v1/enterprise/points/ledger` — 额度流水（发放 / 下单 / 退回 / 过期）（用户态）
  参数：查询 type(string)、page(integer)、pageSize(integer)
- `GET /v1/enterprise/points/welfares` — 按发放批次查看剩余额度与到期日（用户态）
  参数：查询 theme(string)、expiringWithin(integer)
- `GET /v1/enterprise/points/rules` — 额度使用规则文案（登录前可看）（appKey）
  参数：无参数
- `GET/POST /v1/enterprise/points/checkin` — 每日签到：GET 看今天能否领与连续天数，POST 领取（幂等）（用户态，可选）
  参数：GET：无参数 ｜ POST：无参数
- `GET/POST /v1/enterprise/notifications` — 站内信：GET 列表（?unread=1），POST 标已读（用户态，可选）
  参数：GET：查询 unread(string) ｜ POST：请求体 ids(string[])

### 福豆任务

管理员发布任务（奖励型：员工完成后得额度；兑换型：员工用额度兑福利），员工报名、提交凭证、兑换，管理员审核与核销。奖励型发布时从企业额度池冻结预算。全部可选，做员工激励时再接。

- `GET/POST /v1/enterprise/org/tasks` — 管理员：任务列表与概览（?filter=）/ 发布任务（带 idempotencyKey）（用户态，可选）
  参数：GET：查询 filter(string)、cursor(string) ｜ POST：请求体 title*(string)、description(string)、coverUrl*(string)、category(string)、settleMode*(string)、points*(integer)、quota(integer)、scopeKind(string)、scopeIds(string[])、startAt(string)、endAt*(string)、needSignup(boolean)、signupQuota(integer)、completeMode(string)、reviewMode(string)、submitSchema(object[])、needWriteoff(boolean)、pickupInfo(object)、idempotencyKey(string)
- `GET /v1/enterprise/org/tasks/budget-preview` — 管理员：发布前试算预计最高支出与额度池余额（用户态，可选）
  参数：查询 settleMode(string)、points(integer)、quota(integer)、scopeKind(string)、scopeIds(string)、taskId(string)
- `GET/POST /v1/enterprise/org/tasks/{taskId}` — 管理员：任务详情与参与人 / 编辑、提前结束（用户态，可选）
  参数：GET：路径 taskId*(string) ｜ POST：路径 taskId*(string)；请求体 action*(string)、expectedVersion(integer)、title(string)、description(string)、coverUrl(string)、category(string)、settleMode(string)、points(integer)、quota(integer)、scopeKind(string)、scopeIds(string[])、startAt(string)、endAt(string)、needSignup(boolean)、signupQuota(integer)、completeMode(string)、reviewMode(string)、submitSchema(object[])、needWriteoff(boolean)、pickupInfo(object)
- `POST /v1/enterprise/org/task-cover` — 管理员：上传任务封面（先换上传票据，再上传文件）（用户态，可选）
  参数：请求体 fileName(string)、contentType(string)、size(integer)
- `GET/POST /v1/enterprise/org/task-reviews` — 管理员：待审核的提交 / 批量通过或驳回（驳回须填原因）（用户态，可选）
  参数：GET：查询 status(string)、taskId(string)、cursor(string) ｜ POST：请求体 action*(string)、submissionIds*(string[])、reason(string)
- `GET/POST /v1/enterprise/org/task-redemptions` — 管理员：待核销兑换（可按码查）/ 核销或撤销（撤销退额度）（用户态，可选）
  参数：GET：查询 status(string)、code(string)、cursor(string) ｜ POST：请求体 action*(string)、entryId(string)、code(string)
- `GET /v1/enterprise/tasks` — 员工：可参与的任务（?tab=earn|redeem）（用户态，可选）
  参数：查询 tab(string)、cursor(string)
- `GET /v1/enterprise/tasks/mine` — 员工：我参与的任务 / 我的兑换（用户态，可选）
  参数：查询 kind(string)、cursor(string)
- `GET/POST /v1/enterprise/tasks/{taskId}` — 员工：任务详情 / 报名、完成、提交、兑换（带 idempotencyKey）（用户态，可选）
  参数：GET：路径 taskId*(string) ｜ POST：路径 taskId*(string)；请求体 action*(string)、payload(object)、idempotencyKey(string)
- `POST /v1/enterprise/task-proof` — 员工：上传任务凭证（先换上传票据，再上传文件）（用户态，可选）
  参数：请求体 taskId*(string)、fileName(string)、contentType(string)、size(integer)

### 商品

商品接口正在重构为统一商品层，届时所有场景用同一套接口、同一种商品 ID。在那之前员工福利与企业采购用 /v1/enterprise/*，消费者购物用 /v1/lm/*，每条接口标了适用场景。按关键词或类目找商品都用搜索，不提供翻完整个货盘的列表接口。

- `GET /v1/enterprise/products/{id}` — 商品详情（appKey）
  参数：路径 id*(string)
- `GET /v1/enterprise/products/batch` — 商品批量详情（ids 逗号分隔，最多 20 件）（appKey）
  参数：查询 ids*(string)
- `GET /v1/enterprise/products/by-tag` — 按标签取商品（tags 逗号分隔，match=any/all，支持按销量 / 价格 / 上架 / 打标时间排序或随机打散）（appKey）
  参数：查询 tags*(string)、match(string)、sortBy(string)、page(integer)、pageSize(integer)
- `GET /v1/enterprise/products/{id}/desc` — 图文详情（长图文，单独缓存）（appKey）
  参数：路径 id*(string)
- `POST /v1/enterprise/products/search` — 搜索 / 按条件浏览：商品 + 推荐规格，可附符合程度（mode=strict 只要完全符合的）（appKey）
  参数：请求体 version*(integer)、query(object)、filter(object)、unknown(string)、mode(string)、sort(string)、profile(string)、prefer(object[])、excludeFields(string[])、limit(integer)、cursor(string)、include(string[])
- `GET /v1/enterprise/nav` — 类目导航 · 一级（appKey）
  参数：无参数
- `GET /v1/enterprise/nav/branch` — 类目导航 · 二级（带图）（appKey）
  参数：查询 ids*(string)
- `GET /v1/enterprise/zones` — 首页专区（运营位 banner），点开用下一条取商品（appKey，可选）
  参数：无参数
- `GET /v1/enterprise/zones/{id}/products` — 专区商品（appKey，可选）
  参数：路径 id*(string)；查询 page(integer)、pageSize(integer)
- `GET /v1/enterprise/bundles` — 组货方案列表（按调用方所属产品，按场景分组，如「新企开办 → 1人团队」）（appKey，可选）
  参数：查询 scene(string)、realm(string)
- `GET /v1/enterprise/bundles/{code}` — 组货方案详情：规格 + 建议数量，价格库存实时，买不到的带原因（appKey，可选）
  参数：路径 code*(string)；查询 realm(string)
- `GET /v1/enterprise/products/suggest` — 搜索联想（?q=&limit=）；q 为空返回热门搜索（appKey，可选）
  参数：查询 q(string)、limit(integer)
- `POST /v1/enterprise/products/events` — 上报搜索结果上的点击 / 加购 / 下单（带回搜索返回的 searchId），帮助搜索排序（appKey，可选）
  参数：请求体 productId*(string)、event*(string)、searchId(string)、position(integer)

### 结算与下单

结算与下单都收内联商品与收货人，购物车与地址簿可以用平台的，也可以自己做。下单固定传 payWith: "auto"，付款方式由平台按企业配置（全额扣员工额度，或员工在企业购收银台付现金：支付宝 / 微信 / 对公）；扣款与建单在同一事务里，idempotencyKey 同键重试不会重复建单。要员工付现金时，结算预览返回 cash（金额与可选的支付方式 payTypes）。

- `GET /v1/divisions` — 行政区划逐级查（省 → 市 → 区县 → 乡镇街道）：收货地址的 province / city / area / street 用这里选出的名称（appKey）
  参数：查询 parent(string)
- `POST /v1/enterprise/checkout/render` — 结算预览：权威价、运费、库存、额度是否足够（用户态）
  参数：请求体 items*(object[])、device(string)
- `POST /v1/enterprise/orders` — 下单（payWith: auto，付款方式按企业配置；要员工付现金时返回付款链接 launchUrl）（用户态）
  参数：请求体 items*(object[])、receiver(object)、addressId(string)、payWith(string)、payType(string)、returnUrl(string)、device(string)、idempotencyKey(string)、remark(string)
- `GET /v1/enterprise/orders` — 订单列表（用户态）
  参数：查询 limit(integer)
- `GET/POST /v1/enterprise/orders/{bizOrderId}` — 订单详情（要员工付现金的单带 mixedPay）/ 确认收货、取消、继续支付（action=resume-pay）（用户态）
  参数：GET：路径 bizOrderId*(string)；查询 returnUrl(string)、device(string) ｜ POST：路径 bizOrderId*(string)；查询 action(string)；请求体 action(string)、payType(string)、returnUrl(string)、device(string)
- `GET /v1/enterprise/orders/{bizOrderId}/logistics` — 物流轨迹（用户态）
  参数：路径 bizOrderId*(string)
- `GET /v1/enterprise/orders/in-transit` — 在路上的订单与最新物流节点（最近 3 单）（用户态，可选）
  参数：无参数
- `GET/DELETE /v1/enterprise/cart` — 购物车（含合计与额度是否够）/ 清空（用户态，可选）
  参数：GET：无参数 ｜ DELETE：无参数
- `POST/PUT/DELETE /v1/enterprise/cart/items` — 加购（累加）/ 设数量 / 移出（DELETE ?productId=&skuId=）（用户态，可选）
  参数：POST：请求体 productId*(string)、skuId(string)、qty(integer) ｜ PUT：请求体 productId*(string)、skuId(string)、qty(integer) ｜ DELETE：查询 productId*(string)、skuId(string)

### 售后与开票

售后按子订单发起，已发货的回传退货运单。企业购订单提交后自动开票，抬头取自注册时的企业信息。

- `POST /v1/enterprise/refunds` — 发起售后（用户态）
  参数：请求体 bizOrderId*(string)、subOrderId(string)、reasonId(string)、reasonText(string)、amount(number)、needReturn(boolean)
- `GET /v1/enterprise/refunds` — 售后列表（用户态）
  参数：查询 limit(integer)
- `GET/POST /v1/enterprise/refunds/{refundId}` — 售后详情 / 撤销、回传退货运单（用户态）
  参数：GET：路径 refundId*(string) ｜ POST：路径 refundId*(string)；查询 action(string)；请求体 logisticsCompany(string)、invoiceNo(string)、mobile(string)
- `GET /v1/buyer/invoices` — 开票记录（状态、发票号、下载地址）（用户态）
  参数：无参数

### 接入与账户

查当前 appKey 的权限与用量。沙箱 key、签名密钥与 MCP Token 在开发者控制台（open.gowu.net/console）里管理。

- `GET /v1/access-clients/me` — 当前 appKey 的权限、渠道与调用量（appKey）
  参数：无参数
- `GET /v1/health` — 健康检查（免鉴权）
  参数：无参数

## 场景 2：企业采购

给自己公司搭采购应用：企业把采购额度发给采购人员，按部门做预算，员工用企业额度下单，超出部分可用支付宝补；企业统一结算开票。

交易模式：企业额度，可全额或混合支付

完整入参出参与示例：https://gowu.net/open/llms-full.txt?scene=procurement（文本）；OpenAPI 规格：https://gowu.net/open/openapi/procurement.yaml

流程：在开发者控制台申请正式接入（选「员工福利购物」或「企业采购」）并录入企业信息 → 平台审核：开通接口权限、建好企业并开通交易（开通前下单返回 `ORG_EGP_NOT_READY`）→ 企业预充值或授信，平台按约定配置付款方式（全额由企业额度支付，或员工在企业购收银台付现金：支付宝 / 微信 / 对公）→ 你的服务端 `GET /v1/partner/orgs` 查到企业、`PUT /v1/partner/orgs/{orgId}/members/{userId}` 把你的用户绑成员工（终端用户自带账号，userId 即 x-open-user）→ 管理员 `POST /v1/enterprise/org/points` 发放额度 → 员工 `POST /v1/enterprise/orders` 下单：`payWith: "auto"` 按企业配置付款（要付现金时先让员工从结算预览的 `cash.payTypes` 选 `payType`，下单返回 `launchUrl`，员工付完后平台结清，结果以订单详情的 `mixedPay.status` 为准）→ 订单自动开票，企业按账单结算。收货地址传省、市、区名称，用 `GET /v1/divisions` 逐级选出（乡镇街道放 street；叫法不一致上游会拒单）。采购应用的界面上叫「企业额度」而不是福豆，接口与字段（`points`）不变；不含福豆任务、签到与生日福利。

### 企业与员工

企业在开发者控制台申请正式接入时录入，平台审批通过后建好并归属你的 appKey。你的服务端查到自己的企业后，把你的用户绑成员工、设管理员；员工的 userId 就是他之后请求时放进 x-open-user 的值。

- `GET /v1/partner/orgs` — 你的企业（审批通过后由平台建好）：orgId、审核状态（服务端签名）
  参数：无参数
- `GET /v1/partner/orgs/{orgId}` — 企业详情：审核状态、开票信息、额度池余额（服务端签名）
  参数：路径 orgId*(string)
- `GET /v1/partner/orgs/{orgId}/members` — 已绑定员工：角色、在职状态、额度余额（服务端签名）
  参数：路径 orgId*(string)
- `PUT /v1/partner/orgs/{orgId}/members/{userId}` — 把你的用户绑成员工（owner / admin / member），同时开通采购权限（服务端签名）
  参数：路径 orgId*(string)、userId*(string)；请求体 name(string)、phone(string)、role(string)、platform(string)
- `DELETE /v1/partner/orgs/{orgId}/members/{userId}` — 员工离职：未用额度退回企业额度池，收回采购权限（服务端签名）
  参数：路径 orgId*(string)、userId*(string)；请求体 reason(string)

### 企业管理

以企业管理员身份调用：x-open-user 放一个被绑成 owner 或 admin 的用户。查额度池、看账单、向员工发放额度。

- `GET /v1/enterprise/org` — 企业概览、额度池余额与流水（用户态）
  参数：无参数
- `PUT /v1/enterprise/org/profile` — 修改企业资料（名称、信用代码开户后不可改）（用户态）
  参数：请求体 shortName(string)、region(string)、contactName(string)、adminTitle(string)、adminEmail(string)、licenseUrl(string)、joinPolicy(string)、invoice(object)
- `GET /v1/enterprise/org/bills` — 企业账单（?id= 查看单张）（用户态）
  参数：查询 id(string)
- `POST /v1/enterprise/org/points` — 向员工发放 / 回收额度，或全员发放（100 = 1 元）。用 userId 指定员工即可（用户态）
  参数：请求体 action(string)、userId(string)、accountId(string)、amount*(integer)、theme(string)、name(string)、expiresInDays(number)、budgetCategory(string)、lotId(string)、remark(string)
- `GET /v1/enterprise/points/themes` — 福利类型列表（发放时 theme 的可选值）（appKey）
  参数：无参数
- `GET /v1/enterprise/org/dashboard` — 管理看板：员工数、额度池、本月发放与消耗（用户态）
  参数：查询 period(string)
- `GET /v1/enterprise/org/members` — 员工列表（含各自额度余额）（用户态）
  参数：无参数
- `GET/PUT /v1/enterprise/org/members/{userId}` — 员工详情 / 修改资料（带 ?by=userId 时路径里放你的用户 ID）（用户态）
  参数：GET：路径 accountId*(string)；查询 by(string) ｜ PUT：路径 accountId*(string)；查询 by(string)；请求体 realName(string)、departmentId(string)、birthday(string)、gender(string)
- `POST /v1/enterprise/org/members/{userId}` — 停用 / 恢复员工（带 ?by=userId 时路径里放你的用户 ID）（用户态）
  参数：路径 accountId*(string)；查询 by(string)；请求体 action*(string)、reason(string)、role(string)
- `GET/PATCH /v1/enterprise/org/points-settings` — 签到规则、发放默认有效期等企业级设置（用户态）
  参数：GET：无参数 ｜ PATCH：请求体 checkinEnabled(boolean)、checkinDailyAmount(number)、checkinStreakDays(number)、checkinStreakBonus(number)、pointsExpiryDays(number)
- `GET /v1/enterprise/org/consumption` — 员工消耗记录与汇总（按人、时间筛选）（用户态，可选）
  参数：查询 accountId(string)、from(string(date))、to(string(date))、kind(string)、page(integer)、pageSize(integer)
- `GET/POST/PUT/DELETE /v1/enterprise/org/departments` — 部门管理（用户态，可选）
  参数：GET：无参数 ｜ POST：请求体 name*(string)、sort(number) ｜ PUT：请求体 id*(string)、name(string)、sort(number) ｜ DELETE：查询 id*(string)
- `GET/POST/DELETE /v1/enterprise/org/budgets` — 部门预算（用户态，可选）
  参数：GET：查询 period(string)、dashboard(string) ｜ POST：请求体 period*(string)、category(string)、departmentId(string)、amount*(integer)、alertPct(integer)、overspendPolicy(string) ｜ DELETE：查询 id*(string)

### 员工额度

以员工身份调用：查余额、流水与每批额度的到期时间，结算前判断能否用企业额度支付。

- `GET/PUT /v1/buyer/me` — 当前用户资料与所属企业（org：企业 id、名称、状态、本人角色、余额；没有归属为 null）（用户态）
  参数：GET：无参数 ｜ PUT：请求体 nickname(string)、avatar(string)、realName(string)、birthday(string)、gender(string)
- `GET /v1/enterprise/points` — 结算页判断：这单能否用企业额度支付、余额多少（用户态）
  参数：无参数
- `GET /v1/enterprise/points/summary` — 额度总览：余额、即将到期、所属企业与角色（用户态）
  参数：无参数
- `GET /v1/enterprise/points/ledger` — 额度流水（发放 / 下单 / 退回 / 过期）（用户态）
  参数：查询 type(string)、page(integer)、pageSize(integer)
- `GET /v1/enterprise/points/welfares` — 按发放批次查看剩余额度与到期日（用户态）
  参数：查询 theme(string)、expiringWithin(integer)
- `GET /v1/enterprise/points/rules` — 额度使用规则文案（登录前可看）（appKey）
  参数：无参数
- `GET/POST /v1/enterprise/notifications` — 站内信：GET 列表（?unread=1），POST 标已读（用户态，可选）
  参数：GET：查询 unread(string) ｜ POST：请求体 ids(string[])

### 商品

商品接口正在重构为统一商品层，届时所有场景用同一套接口、同一种商品 ID。在那之前员工福利与企业采购用 /v1/enterprise/*，消费者购物用 /v1/lm/*，每条接口标了适用场景。按关键词或类目找商品都用搜索，不提供翻完整个货盘的列表接口。

- `GET /v1/enterprise/products/{id}` — 商品详情（appKey）
  参数：路径 id*(string)
- `GET /v1/enterprise/products/batch` — 商品批量详情（ids 逗号分隔，最多 20 件）（appKey）
  参数：查询 ids*(string)
- `GET /v1/enterprise/products/by-tag` — 按标签取商品（tags 逗号分隔，match=any/all，支持按销量 / 价格 / 上架 / 打标时间排序或随机打散）（appKey）
  参数：查询 tags*(string)、match(string)、sortBy(string)、page(integer)、pageSize(integer)
- `GET /v1/enterprise/products/{id}/desc` — 图文详情（长图文，单独缓存）（appKey）
  参数：路径 id*(string)
- `POST /v1/enterprise/products/search` — 搜索 / 按条件浏览：商品 + 推荐规格，可附符合程度（mode=strict 只要完全符合的）（appKey）
  参数：请求体 version*(integer)、query(object)、filter(object)、unknown(string)、mode(string)、sort(string)、profile(string)、prefer(object[])、excludeFields(string[])、limit(integer)、cursor(string)、include(string[])
- `GET /v1/enterprise/nav` — 类目导航 · 一级（appKey）
  参数：无参数
- `GET /v1/enterprise/nav/branch` — 类目导航 · 二级（带图）（appKey）
  参数：查询 ids*(string)
- `GET /v1/enterprise/zones` — 首页专区（运营位 banner），点开用下一条取商品（appKey，可选）
  参数：无参数
- `GET /v1/enterprise/zones/{id}/products` — 专区商品（appKey，可选）
  参数：路径 id*(string)；查询 page(integer)、pageSize(integer)
- `GET /v1/enterprise/bundles` — 组货方案列表（按调用方所属产品，按场景分组，如「新企开办 → 1人团队」）（appKey，可选）
  参数：查询 scene(string)、realm(string)
- `GET /v1/enterprise/bundles/{code}` — 组货方案详情：规格 + 建议数量，价格库存实时，买不到的带原因（appKey，可选）
  参数：路径 code*(string)；查询 realm(string)
- `GET /v1/enterprise/products/suggest` — 搜索联想（?q=&limit=）；q 为空返回热门搜索（appKey，可选）
  参数：查询 q(string)、limit(integer)
- `POST /v1/enterprise/products/events` — 上报搜索结果上的点击 / 加购 / 下单（带回搜索返回的 searchId），帮助搜索排序（appKey，可选）
  参数：请求体 productId*(string)、event*(string)、searchId(string)、position(integer)

### 结算与下单

结算与下单都收内联商品与收货人，购物车与地址簿可以用平台的，也可以自己做。下单固定传 payWith: "auto"，付款方式由平台按企业配置（全额扣员工额度，或员工在企业购收银台付现金：支付宝 / 微信 / 对公）；扣款与建单在同一事务里，idempotencyKey 同键重试不会重复建单。要员工付现金时，结算预览返回 cash（金额与可选的支付方式 payTypes）。

- `GET /v1/divisions` — 行政区划逐级查（省 → 市 → 区县 → 乡镇街道）：收货地址的 province / city / area / street 用这里选出的名称（appKey）
  参数：查询 parent(string)
- `POST /v1/enterprise/checkout/render` — 结算预览：权威价、运费、库存、额度是否足够（用户态）
  参数：请求体 items*(object[])、device(string)
- `POST /v1/enterprise/orders` — 下单（payWith: auto，付款方式按企业配置；要员工付现金时返回付款链接 launchUrl）（用户态）
  参数：请求体 items*(object[])、receiver(object)、addressId(string)、payWith(string)、payType(string)、returnUrl(string)、device(string)、idempotencyKey(string)、remark(string)
- `GET /v1/enterprise/orders` — 订单列表（用户态）
  参数：查询 limit(integer)
- `GET/POST /v1/enterprise/orders/{bizOrderId}` — 订单详情（要员工付现金的单带 mixedPay）/ 确认收货、取消、继续支付（action=resume-pay）（用户态）
  参数：GET：路径 bizOrderId*(string)；查询 returnUrl(string)、device(string) ｜ POST：路径 bizOrderId*(string)；查询 action(string)；请求体 action(string)、payType(string)、returnUrl(string)、device(string)
- `GET /v1/enterprise/orders/{bizOrderId}/logistics` — 物流轨迹（用户态）
  参数：路径 bizOrderId*(string)
- `GET /v1/enterprise/orders/in-transit` — 在路上的订单与最新物流节点（最近 3 单）（用户态，可选）
  参数：无参数
- `GET/DELETE /v1/enterprise/cart` — 购物车（含合计与额度是否够）/ 清空（用户态，可选）
  参数：GET：无参数 ｜ DELETE：无参数
- `POST/PUT/DELETE /v1/enterprise/cart/items` — 加购（累加）/ 设数量 / 移出（DELETE ?productId=&skuId=）（用户态，可选）
  参数：POST：请求体 productId*(string)、skuId(string)、qty(integer) ｜ PUT：请求体 productId*(string)、skuId(string)、qty(integer) ｜ DELETE：查询 productId*(string)、skuId(string)

### 售后与开票

售后按子订单发起，已发货的回传退货运单。企业购订单提交后自动开票，抬头取自注册时的企业信息。

- `POST /v1/enterprise/refunds` — 发起售后（用户态）
  参数：请求体 bizOrderId*(string)、subOrderId(string)、reasonId(string)、reasonText(string)、amount(number)、needReturn(boolean)
- `GET /v1/enterprise/refunds` — 售后列表（用户态）
  参数：查询 limit(integer)
- `GET/POST /v1/enterprise/refunds/{refundId}` — 售后详情 / 撤销、回传退货运单（用户态）
  参数：GET：路径 refundId*(string) ｜ POST：路径 refundId*(string)；查询 action(string)；请求体 logisticsCompany(string)、invoiceNo(string)、mobile(string)
- `GET /v1/buyer/invoices` — 开票记录（状态、发票号、下载地址）（用户态）
  参数：无参数

### 接入与账户

查当前 appKey 的权限与用量。沙箱 key、签名密钥与 MCP Token 在开发者控制台（open.gowu.net/console）里管理。

- `GET /v1/access-clients/me` — 当前 appKey 的权限、渠道与调用量（appKey）
  参数：无参数
- `GET /v1/health` — 健康检查（免鉴权）
  参数：无参数

## 场景 3：消费者购物

面向普通消费者：你传每个用户自己的 open-id，用户在浏览器里用支付宝付给平台，平台自动下单。适合消费者商城、导购与内容电商、AI 购物助手。

交易模式：用户在线支付

完整入参出参与示例：https://gowu.net/open/llms-full.txt?scene=consumer（文本）；OpenAPI 规格：https://gowu.net/open/openapi/consumer.yaml

流程：开通 appKey → `x-open-user` 直接传用户 open-id，首次访问自动建档 → `POST /v1/lm/products/search` 找商品、`GET /v1/lm/products/{id}` 取 SKU → `GET /v1/divisions` 查行政区划码（区县码 divisionCode 必填，乡镇码 townDivisionCode 强烈建议）→ `POST /v1/lm/checkout/render` 结算预览 → 下单拿支付链接：有完整收货地址时 `POST /v1/lm/pay/web-prepare` 直接拿支付宝链接 `payUrl`（`idempotencyKey` 必填，同键重放返回同一张收款单），没有地址时 `POST /v1/lm/checkout/sessions` 拿托管结账页 `checkoutUrl` 让用户自己填 → 用户在浏览器里付款，平台自动下单、失败自动退款 → `GET /v1/lm/pay/orders/{outTradeNo}` 查结果（status = fulfilled 即已下单），`GET /v1/lm/orders` 查订单与物流，退款用 `POST /v1/lm/pay/refund`。

### 商品

商品接口正在重构为统一商品层，届时所有场景用同一套接口、同一种商品 ID。在那之前员工福利与企业采购用 /v1/enterprise/*，消费者购物用 /v1/lm/*，每条接口标了适用场景。按关键词或类目找商品都用搜索，不提供翻完整个货盘的列表接口。

- `GET /v1/lm/products/{id}` — 商品详情（含 SKU，下单每行都要带 skuId）（appKey）
  参数：路径 id*(string)
- `POST /v1/lm/products/search` — 搜索 / 按条件浏览：商品 + 推荐规格，可附符合程度（mode=strict 只要完全符合的）（appKey）
  参数：请求体 version*(integer)、query(object)、filter(object)、unknown(string)、mode(string)、sort(string)、profile(string)、prefer(object[])、excludeFields(string[])、limit(integer)、cursor(string)、include(string[])
- `GET /v1/lm/categories` — 类目列表（按商品数排序，作为搜索的 category 参数）（appKey）
  参数：查询 limit(integer)

### 用户与收货地址

用户身份直接用你那边每个用户的 open-id（放进 x-open-user），首次访问自动建档，不需要先注册。收货地址要用行政区划码，先用区划接口级联选出来；地址簿是可选的便利，不用也能下单。

- `GET /v1/divisions` — 行政区划级联（下单要的 divisionCode / townDivisionCode；老路径 /v1/lm/divisions 仍可用）（appKey）
  参数：查询 parent(string)
- `GET/POST /v1/buyer/addresses` — 地址簿列表 / 新增（complete 标记能否直接下单）（用户态，可选）
  参数：GET：无参数 ｜ POST：请求体 receiver*(string)、receiverPhone*(string)、addressDetail*(string)、province(string)、city(string)、district(string)、street(string)、divisionCode(string)、townDivisionCode(string)、isDefault(boolean)
- `PUT/POST/DELETE /v1/buyer/addresses/{id}` — 改 / 设默认 / 删地址（用户态，可选）
  参数：PUT：路径 id*(string)；请求体 receiver*(string)、receiverPhone*(string)、addressDetail*(string)、province(string)、city(string)、district(string)、street(string)、divisionCode(string)、townDivisionCode(string)、isDefault(boolean) ｜ POST：路径 id*(string)；查询 action*(string) ｜ DELETE：路径 id*(string)

### 结算与订单

下单前用结算预览拿权威价、运费与可售状态。下单与付款走下面的「平台收银台」：用户付款后平台自动下单，建出的订单在这里查订单、物流、确认收货。

- `POST /v1/lm/checkout/render` — 结算预览：权威价、运费、可售状态（用户态）
  参数：请求体 items*(object[])
- `GET /v1/lm/orders` — 订单列表（用户态）
  参数：查询 limit(integer)
- `GET/POST /v1/lm/orders/{id}` — 订单详情 / 确认收货（用户态）
  参数：GET：路径 id*(string) ｜ POST：路径 id*(string)；查询 action(string)、orderId(string)；请求体 action(string)、orderId(string)
- `GET /v1/lm/orders/{id}/logistics` — 子订单物流轨迹（用户态）
  参数：路径 id*(string)

### 平台收银台

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

- `POST /v1/lm/pay/web-prepare` — 下单并返回支付短链 payUrl 与它的二维码 qrImageUrl（需带收货地址；idempotencyKey 同键重放返回同一张收款单）（用户态）
  参数：请求体 items*(object[])、receiver(object)、addressId(string)、idempotencyKey*(string)、device(string)、returnUrl(string)、remark(string)
- `POST /v1/lm/checkout/sessions` — 托管结账页：返回 checkoutUrl，用户在页面上核对、填地址后用支付宝付款（地址可不传；带 idempotencyKey 时同键重试返回同一个结账页）（用户态）
  参数：请求体 items*(object[])、receiver(object)、idempotencyKey(string)、addressId(string)、returnUrl(string)、remark(string)
- `GET /v1/lm/checkout/sessions/{sessionId}` — 结账会话进度（待支付 / 已过期 / 已发起支付 + 收款单状态）（用户态）
  参数：路径 sessionId*(string)
- `GET /v1/lm/pay/orders` — 收款单列表（用户态）
  参数：查询 limit(integer)
- `GET /v1/lm/pay/orders/{outTradeNo}` — 收款单详情（付款后查它：status = fulfilled 即已下单，带订单号与退款进度）（用户态）
  参数：路径 outTradeNo*(string)；查询 subOrderId(string)
- `POST /v1/lm/pay/refund` — 退款申请（未发货整单退；多件需指定订单行）（用户态）
  参数：请求体 outTradeNo*(string)、subOrderId(string)、reasonId(string)、reason(string)
- `GET /v1/lm/refunds` — 售后列表；render=1 取可退金额与可选原因（选中的原因 id 作为 reasonId 传给退款申请）（用户态）
  参数：查询 render(string)、orderId(string)、orderLineId(string)
- `GET/POST /v1/lm/refunds/{disputeId}` — 售后详情 / 撤销售后（action=cancel）（用户态）
  参数：GET：路径 disputeId*(string) ｜ POST：路径 disputeId*(string)；查询 action(string)
- `POST /v1/lm/pay/refund/return` — 退货退款：回传退货运单号（用户态）
  参数：请求体 outTradeNo*(string)、logisticsCompany*(string)、invoiceNo*(string)、subOrderId(string)

### 接入与账户

查当前 appKey 的权限与用量。沙箱 key、签名密钥与 MCP Token 在开发者控制台（open.gowu.net/console）里管理。

- `GET /v1/access-clients/me` — 当前 appKey 的权限、渠道与调用量（appKey）
  参数：无参数
- `GET /v1/health` — 健康检查（免鉴权）
  参数：无参数

## 注意

- 商品：员工福利与企业采购用 /v1/enterprise/*，消费者购物用 /v1/lm/*。找商品统一用搜索，不提供翻完整个货盘的列表接口。下单时原样使用商品接口返回的商品 id 与规格 skuId，不要自己拼接或解析。
- 搜索（`POST /v1/{enterprise,lm}/products/search`）：请求体带 `"version": 2`（响应同样带 `version: 2`，解析前先校验）；每条结果是商品 + 推荐规格 `sku`。给用户推荐商品时传 `"mode": "strict"`（只要完全符合的）与 `"include": ["match"]`（每个条件满足与否及凭据）；用户说「无所谓」的词放 `query.optional`；结果不够时看 `relaxHints`，向用户确认后把那个词放进 `query.optional` 重搜；翻页用 `nextCursor`。不带 version 的是旧版接口（返回 items / page），新接入请用新版。
- 付款（员工福利、企业采购）：下单带 `payWith: "auto"`，固定传这个值，由平台按企业配置决定扣员工额度还是让员工付现金。要付现金时结算预览返回 `cash.payTypes`，让员工选一种作为 `payType` 下单，响应带 `launchUrl`（24 小时有效），把员工带过去付款（支付宝 / 微信 / 对公转账）；是否付清以订单详情的 `mixedPay.status = confirmed` 或 `order.status` 推送为准。员工付现金需平台为 appKey 开通。
- `/v1/*` 下还有一批平台自用路径（支付网关异步通知、上游 webhook、推广埋点、平台账号登录与小程序收银台等自家应用专用接口），**不在开放范围内**，不做兼容承诺，请勿依赖。