格物 开放 API通用约定
文档 · 通用规则
通用约定
- 地址：REST 接口
https://api.gowu.net/v1/…，MCPhttps://api.gowu.net/mcp；请求与响应都是 JSON（content-type: application/json）。 - 终端用户由你自己的账号体系管理，把你那边稳定的用户 ID 放进
x-open-user：员工福利与企业采购是员工在你系统里的 ID，消费者购物是每个用户的 open-id。 平台按「appKey + 用户 ID」隔离数据，同一个 ID 在不同 appKey 下是不同的人。 - 订单号、售后单号、商品 ID 都是不透明字符串，原样保存、原样回传，不要解析格式。
- 下单请带
idempotencyKey（消费者购物为必填），建议用你系统的订单号或支付单号：响应丢了就用同一个 key 重试，不会重复建单。
x-open-user 必须取自你服务端的登录态，不能直接透传前端传来的值—— 平台只能验证签名，验证不了这个值是不是当前登录的人。
1// ✅ 从你服务端的登录态里取2 app.post("/api/order", requireLogin, async (req, res) => {3 const openUser = req.session.userId; // 你自己系统里的用户 ID4 const headers = gowuHeaders({ appKey, appSecret, method: "POST",5 path: "/v1/lm/pay/web-prepare", body, openUser });6 // ...7 });8 9 // ❌ 不要直接用前端传上来的用户 ID10 const openUser = req.body.userId;限流
- 只读接口：每个 appKey 每分钟 300 次。
- 交易类接口（下单、售后、企业管理等用户态接口）：每个 appKey 每分钟 60 次。
- 自助申请沙箱 key：同一 IP 每天 3 次。
- MCP：工具调用计入同一个 appKey 的上述额度；MCP 连接本身（初始化、列工具等）另有每分钟 600 次的上限。
超限返回 429，按 Retry-After 头等待后重试。正式上线前可以联系我们按业务量调整额度。
1HTTP/1.1 429 Too Many Requests2Retry-After: 123 4{ "code": "RATE_LIMITED", "message": "请求过于频繁" }状态码与错误
错误统一返回 { "code": "...", "message": "..." }，HTTP 状态码同时表意。
| 状态 | 常见 code | 含义 | 适用 |
|---|---|---|---|
| 400 | BAD_REQUEST | 参数不合法，message 会说明哪一项 | 通用 |
| 401 | UNAUTHORIZED | appKey 无效或停用、签名错误、时间戳超出 ±300 秒 | 通用 |
| 403 | FORBIDDEN | 该路径不在这个 appKey 的权限白名单里 | 通用 |
| 404 | NOT_FOUND | 资源不存在，或不归属你的 appKey | 通用 |
| 429 | RATE_LIMITED | 超出限流 | 通用 |
| 403 | NOT_ORG_MEMBER / NOT_ORG_ADMIN | 这个用户没绑到企业 / 不是企业管理员 | 福利 / 采购 |
| 403 | ORG_NOT_ACTIVE / ORDER_NOT_ALLOWED | 企业未激活或已停用 / 员工没有采购权限 | 福利 / 采购 |
| 400 | ORG_EGP_NOT_READY | 企业的企业购交易尚未开通，联系平台 | 福利 / 采购 |
| 409 | ALREADY_BOUND / ORG_EXISTS | 用户已属于别的企业 / 该信用代码已在平台注册 | 福利 / 采购 |
| 409 | IDEMPOTENCY_CONFLICT | 平台收款：同一 idempotencyKey 已用于商品或地址不同的订单，换新 key | 消费者 |
| 409 | ALREADY_PAID / PAY_CLOSED | 平台收款：这个 key 的订单已支付 / 已超时关闭，响应带 outTradeNo | 消费者 |
| 400 | PAY_EXPIRED / BAD_RETURN_URL | 平台收款：支付链接已过付款截止 / returnUrl 不是你登记的域名 | 消费者 |
经 MCP 调用时，工具返回 isError: true，内容就是上表的 { code, message }；连接级的错误见「MCP 常见问题」。
1HTTP/1.1 403 Forbidden2 3{4 "ok": false,5 "code": "FORBIDDEN",6 "message": "该路径不在当前 appKey 的权限内"7}