# 奇门云 AI 接入手册

版本：v1。更新日期：2026-09-13。
适用对象：帮助客户接入奇门云的 Codex 等 AI 编程助手，以及客户的开发人员。
网站固定为 https://api.miandanni.com；本手册只覆盖下面两种已核对的只读订单查询。

## 1. 先读资料，再开始修改

- [客户入口](https://api.miandanni.com/docs/ai)：开始 AI 协助接入。
- [平台教程](https://api.miandanni.com/docs)：查看授权、绑定和配置步骤。
- [OpenAPI 规范](https://api.miandanni.com/openapi.json)：核对两个查单请求的字段与错误结构。
- [旺店通 Python 示例](https://api.miandanni.com/examples/qimenyun_wangdian.py)。
- [聚水潭 Python 示例](https://api.miandanni.com/examples/qimenyun_jushuitan.py)。

先检查客户现有项目的说明、语言、配置方式和订单相关代码，沿用现有语言及请求库完成接入。
没有现有项目时，提供 Python 3.9+ 的独立查单脚本，优先沿用公开示例的标准库实现。
公开 Python 文件是可编辑 CONFIG 的模板；集成到客户项目时，将真实密钥改为从本地配置读取。
不要擅自重写整个项目、改订单业务流程或添加推单、退款、发货等写操作。

## 2. 只收集尚未提供的资料

| 资料 | 如何获取 |
| --- | --- |
| 选择的平台 | 旺店通企业版，或聚水潭；本手册不包含旺店通旗舰版 |
| 平台账号 | 旺店通：客户自己的 SID；聚水潭：客户 customer_id（本平台统一称为 sid） |
| 要查询的订单号 | 客户自己的原平台订单号，按字符串处理 |
| 奇门云密钥保存位置 | 询问客户电脑上的配置文件路径或环境变量名称，不要求发到聊天里 |
| 现有项目位置 | 已知则直接读取；没有项目就创建独立 Python 查单工具 |

客户已给过的信息直接使用，不要反复询问或凭空猜测缺失的账号、绑定编号与订单号。
客户需完成手机号验证码注册、平台授权、奇门云账号绑定和服务套餐开通。
奇门云绑定保存后立即启用，无需管理员审核；上游平台授权仍需完成。
注册、付款和上游授权可能需要客户收短信、确认付款或等待平台审核，不承诺 AI 可以无人操作完成。
如果尚未完成，先交付可用代码、占位配置与步骤，明确哪一步仍需客户操作。
不要索取或寻找奇门云运营方真实的淘宝、奇门 AppSecret；客户接入不需要它们。

## 3. 在客户本地保存奇门云密钥

`appsecret` 是客户自己的奇门云访问密钥，只用来生成 Bearer 请求头，不参与淘宝签名。
客户可以登录服务台，在“奇门云密钥”中点击“复制密钥”，将完整密钥保存到自己的本地配置。
新生成的密钥由服务器加密保存。历史密钥如果仅保存了摘要，无法恢复原文，仍可继续使用已有本地密钥；需要网页复制时，由客户明确重置一次。重置后旧密钥立即失效，必须同步更新程序配置，AI 不得自动重置。
新生成的密钥为 32 位小写十六进制字符串；历史密钥仍可能有效，不写死客户端格式检查。
密钥是否有效、账户是否停用、服务是否到期，以奇门云返回结果为准，不根据本地日期判断。

优先使用项目已有的环境变量机制。没有现成机制时，可使用本地 `.env`：

```dotenv
# .env.example 仅保留占位值；真实值由客户填入本地 .env
QIMENYUN_APPSECRET=REPLACE_WITH_YOUR_OWN_QIMENYUN_KEY
```

- 把 `.env`、本地密钥文件和真实订单结果文件加入版本控制忽略规则，并检查规则已生效。
- 可以提交 `.env.example`，但其中只能有占位值；不要覆盖客户已有 `.env` 内容。
- 从密钥文件读取后，不打印完整值、请求 Authorization、包含密钥的 CONFIG 或环境变量全集。
- 不把密钥放入浏览器前端、网页 URL、公共仓库、截图、公开粘贴服务或生成的说明文档。
- 密钥只发送给客户确认的奇门云 HTTPS 接口，不发送到文档站、搜索工具或第三方调试服务。
- 如需展示验证过程，只报告“已读取密钥”和结果状态；不回显密钥。

下方配置示意使用 `os.environ["QIMENYUN_APPSECRET"]`；Python 本身不会自动加载 `.env`。
AI 必须沿用项目的加载器，或给独立脚本补上明确的本地配置加载方式，并写清启动步骤。
文件不存在、密钥为空或仍为占位值时，应在联网前提示客户填写，不要代填其他账户的密钥。

## 4. 两个平台共用的请求规则

固定地址：`POST https://api.miandanni.com/api/gateway`。

```http
Content-Type: application/json; charset=utf-8
Authorization: Bearer <从客户本地读取的奇门云密钥>
```

请求正文为 JSON 对象；路由字段、`method`、`params` 放在顶层。
配置里的 `method` 与业务查询条件 `PARAMS` 分开，便于客户只修改必要字段。
请求顶层统一传 `sid`。同一客户跨平台的 SID 重复时，同时传 `platform`（wangdian_qyb、wangdian_qjb、wangdian_web 或 jushuitan）。旧 bindingId 兼容保留，不与 sid 同传。
不要向请求正文额外加入 `appkey`、`appsecret`、`provider`、`endpoint` 或自定义 `body`。
不要在 `params` 及其嵌套内容中加入 `sid`、`customer_id`、`target_app_key`、`sign` 等受保护字段。
奇门云核对密钥、有效期、绑定归属与平台开放状态，再填写上游路由和签名。
这是一层奇门云请求接口，不能直接把本手册当作原生淘宝 SDK 或聚水潭普通开放平台的配置。

## 5. 旺店通企业版

先按[旺店通奇门自助指南](https://open.wangdian.cn/open/guide?path=guide_qm_customize)创建正式授权。
在慧策开放平台申请时，卖家账号 `sid` 填客户自己的账号，接口账号 `appkey` 填 `34608423`。
授权上线后，在奇门云添加相同 SID 的旺店通企业版绑定，保存后立即启用。
慧策页面的真实接口密钥与客户代码中的奇门云 `appsecret` 含义不同，不要互相替换。

```python
import os

CONFIG = {
    "url": "https://api.miandanni.com/api/gateway",
    "appkey": "34608423",
    "appsecret": os.environ["QIMENYUN_APPSECRET"],
    "sid": "example_sid_replace_me",
    "method": "wdt.trade.query",
    "timeout": 30,
}
PARAMS = {"src_tid": "DEMO_WDT_ORDER_REPLACE_ME"}
```

SID 和订单号是明确的演示占位值，必须换成客户自己的值后才能验证；不是测试授权。
`appkey` 仅在 CONFIG 中保留默认值，不增加 `if appkey != "34608423"` 检查，也不发送到 JSON。
实际正文只取配置中的 SID、method 和 PARAMS：

```json
{"sid":"example_sid_replace_me","method":"wdt.trade.query","params":{"src_tid":"DEMO_WDT_ORDER_REPLACE_ME"}}
```

[查询订单官方文档](https://open.wangdian.cn/qyb/open/apidoc/doc?path=trade_query.php)中的服务名是 `trade_query.php`，对应奇门方法 `wdt.trade.query`。
`src_tid` 是原平台订单号，保留字符串及英文引号，不要转成 JavaScript Number 等可能丢失精度的类型。
此例按单号查询；不要未经查证加入时间范围或套用其他接口的参数。

## 6. 聚水潭

按[聚水潭奇门自定义场景指引](https://openweb.jushuitan.com/doc?docId=250)完成平台授权。
在 ERP 的“基础设置 → 开放平台 → 奇门自定义场景授权与配置”取得 `customer_id`；授权应用联系奇门云管理员确认。
在奇门云添加聚水潭时，将该值填入客户编号。保存后立即启用，查询代码的 `sid` 填同一个 customer_id，保持字符串。
`sid` 是本平台统一的账号字段名；对聚水潭，它的值就是 customer_id。

```python
import os

CONFIG = {
    "url": "https://api.miandanni.com/api/gateway",
    "appsecret": os.environ["QIMENYUN_APPSECRET"],
    "sid": "自己的聚水潭customer_id",
    "method": "jushuitan.order.list.query",
    "timeout": 30,
}
PARAMS = {"so_ids": "DEMO_JST_ORDER_REPLACE_ME", "page_index": 1, "page_size": 25}
```

示例 SID 和订单号均为占位值；sid 必须是自己已启用的账号字符串。
实际正文形状如下，示意中的 `0` 不能直接用于调用：

```json
{"sid":"自己的聚水潭customer_id","method":"jushuitan.order.list.query","params":{"so_ids":"DEMO_JST_ORDER_REPLACE_ME","page_index":1,"page_size":25}}
```

[聚水潭奇门订单官方文档](https://open.jushuitan.com/document.aspx?doc_id=2352)要求 `page_index`、`page_size`，从第 1 页开始，每页 1～100 条，示例取 25 条。
`so_ids` 为线上订单号字符串，多单使用英文逗号分隔；需要更多结果时按返回情况继续翻页。
业务字段平铺在 `params`；不套普通开放平台的 `biz`，不传 `customer_id`、AccessToken 或自行计算的签名。
这条奇门场景不提供收件人信息；不要把缺失收件人字段误判为奇门云配置错误。

## 7. 正确判断返回结果

奇门云成功转发时，保留上游的 HTTP 状态和正文，不统一包装成 `{ok:true,data:...}`。
HTTP 200 只说明收到响应；必须继续检查平台业务结果。
先解析 JSON；出现 `error_response` 时按奇门错误处理，即使 HTTP 为 200。
检查旺店通常见的 `response.errorcode`，以及适用响应结构中的 `code`；非 `0` / `"0"` 为业务错误。
字段不存在不能凭空当作已查到订单，应按对应接口文档核对集合、条数和实际返回字段。
不要固定给所有方法套 `result.data` 或 `result.response.trades`；聚水潭与旺店通结构不同。

旺店通成功响应形状示意（空结果，不是真实订单，也不保证全部响应字段）：

```json
{"response":{"errorcode":0,"message":"ok","total_count":0,"trades":[]}}
```

空集合应报告“请求成功，本次未查到订单”，不能报告“查单成功，已取得订单”。
真实订单结果只保存在客户本地。验证说明可列出数量、是否匹配所查单号，不展开收件人等业务信息。
出现非 JSON、缺少所需集合或未知结构时，保留脱敏诊断并解释不确定性，不虚构订单内容。

## 8. 奇门云错误与处理

奇门云自身错误正文为 `{"ok":false,"error":{"code":"错误码","message":"说明"}}`，有时含 `details`。
上游错误可能使用其他结构；优先保留 HTTP 状态与脱敏后的原始错误码，不把所有失败都说成密钥过期。

| HTTP / code | AI 应如何处理 |
| --- | --- |
| 401 `INVALID_API_KEY` | 检查奇门云密钥是否缺失、无效、被重置，或客户账号已停用；不要索取淘宝密钥 |
| 402 `SUBSCRIPTION_REQUIRED` | 服务未开通或已到期；引导客户在服务台购买或续费 |
| 400 `UNKNOWN_FIELDS` | 去掉正文中未支持的顶层字段，如 appkey、appsecret |
| 400 `VALIDATION_ERROR` / `INVALID_PARAMETER` / `INVALID_ROUTING_ID` | 按字段类型、SID 格式与请求结构修正配置 |
| 400 `CONFLICTING_ROUTE` | 不要同时发送 sid 和 bindingId |
| 400 `PROTECTED_PARAMETER` | 去掉 params 内的路由、应用或签名字段，不尝试换大小写绕过 |
| 400 `PROVIDER_METHOD_MISMATCH` / `PROVIDER_BODY_NOT_ALLOWED` | 核对平台与 method；业务字段放进 params，不传 body |
| 400 `INVALID_JSON` / `OBJECT_REQUIRED` | 正文必须是有效的 JSON 对象 |
| 403 `BINDING_REQUIRED` / `PLATFORM_METHODS_DISABLED` | 补齐有效绑定，或联系管理员确认该平台是否开放 |
| 404 `BINDING_NOT_FOUND` | 核对绑定属于当前密钥账号且已启用；不存在、停用或其他人的绑定均不可用 |
| 409 `AMBIGUOUS_SID` | 同账号存在重复启用的 SID 绑定；请客户或管理员核对后保留正确绑定，AI 不盲删 |
| 413 `BODY_TOO_LARGE` / 415 `JSON_REQUIRED` | 缩小请求内容，或修正 Content-Type 为 application/json |
| 502 `UPSTREAM_UNAVAILABLE` | 奇门云无法完成上游连接；提示稍后检查，不循环重试 |
| 503 `GATEWAY_NOT_CONFIGURED` / `PROVIDER_NOT_CONFIGURED` | 联系奇门云管理员处理服务器配置，不修改客户账号或猜上游凭据 |
| 500 `INTERNAL_ERROR` / `INVALID_PROVIDER_ROUTE` | 提供时间、状态和脱敏错误信息给管理员，不将其归因于客户密钥 |

## 9. AI 应交付什么，以及如何验证

1. 可直接启动的接入代码，沿用现有项目；无项目则交付独立 Python 查单脚本。
2. 清楚的 CONFIG、独立的 PARAMS、无真实密钥的 `.env.example` 和已生效的忽略规则。
3. 适合客户电脑的最少启动步骤：打开哪个文件夹、修改哪些字段、执行哪条命令、在哪里查看结果。
4. 参数和响应的本地模拟验证；资料齐备、授权与套餐就绪后，按客户本次已授权的接入范围执行一次只读查单实测，不重复索取已有授权。
5. 明确区分“代码检查通过”“已联网请求”“业务成功且取得订单”，并说明仍缺少的人工步骤。

Python 示例可用 `python -X utf8 qimenyun_wangdian.py` 或 `python -X utf8 qimenyun_jushuitan.py` 启动；先完成密钥加载配置。
每次请求使用 30 秒超时；关闭自动重定向，遇到跳转就停止，避免 Bearer 密钥被转发到其他地址。
默认不自动重试；先检查错误原因，也不要把只读查单脚本扩展成定时批量任务。
不要为“证明成功”生成虚假订单、绕过上游平台授权、自动代付套餐，或发送未经客户要求的短信。

## 10. 将来需要其他接口时

本手册和 OpenAPI 只描述 `wdt.trade.query`、`jushuitan.order.list.query` 两个已核对的查单例子。
网关接受某种方法前缀，不代表该前缀下全部接口已授权、可用或参数相同。
先查对应平台官方方法文档，确认客户授权、奇门云平台开放状态、方法名称、PARAMS 和返回结构，再实现新功能。
订单创建、退款、修改、发货等会改变业务数据的功能，必须取得客户相应操作授权，不能从查单请求推定。
如文档与实际返回不一致，记录方法、时间、HTTP 状态及脱敏错误，向奇门云管理员核对，不猜字段或上游密钥。


旺店通客户端旗舰版也使用 sid，例如 `{"sid":"自己的SID","platform":"wangdian_qjb","method":"wdt.sales.tradequery.querywithdetail","params":{"params":{"src_tid":"自己的原始单号","accurate_query":true},"pager":{"page_no":1,"page_size":25}}}`。网页版说明见 `/docs/wangdian-web`。