# 格物知心 · 开放平台

> 格物知心（GoWu）开放 API：第三方可基于此搭建企业采购小程序、网站商城、Skill 或 Agent。覆盖企业购（企业开户与额度、员工管理、货盘、下单、售后、开票），以及接入账户相关的通用接口。

企业购的资金路径：企业注册（统一社会信用代码即开票税号）→ 平台审核激活 → 预充值或授信进额度池 → 管理员向员工发放额度 → 员工下单时传 `payWith: "points"` 从额度扣减 → 按账单结算。当前不经过在线支付。

- 开放平台：https://open.gowu.net
- API Base URL：`https://api.gowu-ai.com`（与文档站不是同一个域）
- 鉴权：请求头 `x-app-key`；为 appKey 配置 `app_secret` 后强制 HMAC-SHA256 签名 + 防重放
- 终端用户：涉及终端用户的接口须带 `x-open-user`，数据按 `open:<appKey>:<user>` 隔离
- 沙箱：`POST /open/access-clients/apply` 免鉴权自助申请只读 appKey（同一 IP 每天 3 次）

## 机读文件

- [OpenAPI 3.0 规格](https://open.gowu.net/openapi.yaml)：全部接口的路径、参数与响应 schema，可直接导入 Postman / Apifox / Swagger UI。HMAC 签名的算法与签名串构成写在它的 `info.description` 里。

## 接口清单

鉴权等级：**服务端签名**（接入方服务端调用：强制 HMAC 签名，不带 x-open-user）；**用户态**（交易接口：必带 x-open-user 标识终端用户，且强制 HMAC-SHA256 签名）；**appKey**（请求头带 x-app-key 即可；该 appKey 配了 app_secret 时同样要签名）；**免鉴权**（无需任何请求头，可直接调用）。

### 企业开户与员工绑定

由接入方服务端为自己的客户开企业、绑员工，不依赖手机号授权。企业归属当前 appKey，只有它能往里绑人；开户后经平台审核激活才能充值与下单。员工的 userId 就是他之后请求时放进 x-open-user 的值。

- `POST /open/partner/orgs` — 开户：企业名称、统一社会信用代码（即开票税号）、营业执照（服务端签名）
- `GET /open/partner/orgs` — 本接入方名下的企业列表（服务端签名）
- `GET /open/partner/orgs/{orgId}` — 企业详情：审核状态、开票信息、额度池余额（服务端签名）
- `GET /open/partner/orgs/{orgId}/members` — 已绑定员工：角色、在职状态、额度余额（服务端签名）
- `PUT /open/partner/orgs/{orgId}/members/{userId}` — 把你的用户绑成员工（owner / admin / member），同时开通采购权限（服务端签名）
- `DELETE /open/partner/orgs/{orgId}/members/{userId}` — 员工离职：未用额度退回企业额度池，收回采购权限（服务端签名）

### 企业管理

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

- `GET /open/enterprise/org` — 企业概览、额度池余额与流水（用户态）
- `PUT /open/enterprise/org/profile` — 修改企业资料（名称、信用代码开户后不可改）（用户态）
- `GET /open/enterprise/org/bills` — 企业账单（?id= 查看单张）（用户态）
- `POST /open/enterprise/org/points` — 向员工发放 / 回收额度，或全员发放（100 = 1 元）。用 userId 指定员工即可（用户态）
- `GET /open/enterprise/points/themes` — 福利类型列表（发放时 theme 的可选值）（appKey）
- `POST /open/enterprise/org/members/{userId}` — 停用 / 恢复员工（带 ?by=userId 时路径里放你的用户 ID）（用户态）
- `GET/PATCH /open/enterprise/org/points-settings` — 发放默认有效期等企业级设置（用户态）
- `GET/POST/PUT/DELETE /open/enterprise/org/departments` — 部门管理（用户态）
- `GET/POST/DELETE /open/enterprise/org/budgets` — 部门预算（用户态）

### 员工额度

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

- `GET /open/enterprise/points` — 结算页判断：这单能否用企业额度支付、余额多少（用户态）
- `GET /open/enterprise/points/summary` — 额度总览：余额、即将到期、所属企业与角色（用户态）
- `GET /open/enterprise/points/ledger` — 额度流水（发放 / 下单 / 退回 / 过期）（用户态）
- `GET /open/enterprise/points/welfares` — 按发放批次查看剩余额度与到期日（用户态）
- `GET /open/enterprise/points/rules` — 额度使用规则文案（登录前可看）（appKey）

### 企业购货盘

商品列表、详情、图文详情、搜索与类目导航。搜索、按类目浏览与翻页需要带 x-open-user。

- `GET /open/enterprise/products` — 商品列表（关键词、类目、分页、精选位）（appKey）
- `GET /open/enterprise/products/{id}` — 商品详情（appKey）
- `GET /open/enterprise/products/{id}/desc` — 图文详情（长图文，单独缓存）（appKey）
- `POST /open/enterprise/products/search` — 搜索（品牌、价格区间、只看在售、排序）（appKey）
- `GET /open/enterprise/nav` — 类目导航 · 一级（appKey）
- `GET /open/enterprise/nav/branch` — 类目导航 · 二级（带图）（appKey）

### 结算与下单

结算与下单都收内联商品与收货人，不依赖平台的购物车或地址簿。下单传 payWith: "points" 从员工额度扣减，扣款与建单在同一事务里；idempotencyKey 同键重试不会重复建单。

- `POST /open/enterprise/checkout/render` — 结算预览：权威价、运费、库存、额度是否足够（用户态）
- `POST /open/enterprise/orders` — 下单（payWith: points 使用企业额度）（用户态）
- `GET /open/enterprise/orders` — 订单列表（用户态）
- `GET/POST /open/enterprise/orders/{bizOrderId}` — 订单详情 / 确认收货、取消（用户态）
- `GET /open/enterprise/orders/{bizOrderId}/logistics` — 物流轨迹（用户态）

### 售后与开票

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

- `POST /open/enterprise/refunds` — 发起售后（用户态）
- `GET /open/enterprise/refunds` — 售后列表（用户态）
- `GET/POST /open/enterprise/refunds/{refundId}` — 售后详情 / 撤销、回传退货运单（用户态）
- `GET /open/buyer/invoices` — 开票记录（状态、发票号、下载地址）（用户态）

### 接入与账户

自助拿沙箱 key、查当前 appKey 的权限与用量。

- `POST /open/access-clients/apply` — 自助申请沙箱 appKey（只读权限）（免鉴权）
- `GET /open/access-clients/me` — 当前 appKey 的权限、渠道与调用量（appKey）
- `GET /open/health` — 健康检查（免鉴权）

## 注意

- `/open/*` 下还有一批平台自用路径（支付网关异步通知、上游 webhook、推广埋点、自营商城的购物车、签到与运营看板；以及混合支付的收银台（上游支付尚未开通）），**不在开放范围内**，不做兼容承诺，请勿依赖。
- 通用接口的请求与响应定义以 OpenAPI 规格为准；企业购接口的完整定义正在并入规格，开通权限时随对接资料提供。