# 奇门云签名直连

更新日期：2026-10-27。新生成 AI 对接包只提供 direct 签名直连。老客户原程序继续可用，无需迁移。

客户服务器先向奇门云申请签名，奇门云检查客户密钥、有效服务、店铺或绑定归属及授权，再返回一份官方请求。客户服务器执行这份请求，平台业务数据直接返回客户服务器。不要在浏览器前端保存或执行含授权凭据的签名请求。

奇门订单数据来自旺店通、聚水潭 ERP，请求通常经淘宝奇门路由到 ERP；旺店通网页版标准接口直接请求 ERP 官方网关。淘宝奇门是请求通道。万相台广告和淘宝电商 API 才是淘宝官方广告、电商业务数据。请按配置中的服务选择相应官方文档。

## 1. 申请签名

| 服务 | POST 签名地址 |
| --- | --- |
| 旺店通 / 聚水潭 ERP | https://api.miandanni.com/api/gateway/sign |
| 万相台 | https://api.miandanni.com/api/wanxiang/sign |
| 淘宝电商 | https://api.miandanni.com/api/taobao/sign |

申请签名使用 Content-Type: application/json 与 Authorization: Bearer 客户自己的奇门云密钥。密钥只发给奇门云，不能转发到官方平台。

奇门请求仍为 `{sid, platform?, method, params}`，sid 与 bindingId 不同时传；万相台及电商仍为 `{shopKey, method, params}`。参数按具体官方方法填写，不接受客户覆盖 app_key、session、sign、上游地址等公共参数。

聚水潭自 2026-10-27 起新增接入使用奇门 AppKey `34608423` 完成 [官方场景授权](https://openweb.jushuitan.com/doc?docId=250)，等“申请成功”后使用同一行 `customer_id` 绑定。老客户保留原授权和连接方式，不统一改绑或重置密钥。已有绑定以专属 AI 包该绑定的 `authorizationAppKey` 核对；`customerId`、`targetAppKey` 也仅供授权核对，不加入请求 `body.params`。

聚水潭的 `app_key`、`customer_id`、`target_app_key` 和 `sign` 由奇门云按绑定生成，客户端原样发送签发请求。成功数据可直接包含 `orders`、`data_count`、`has_next`，不强制要求 `flag=success`；平台错误要保留说明和请求号，不能当空数据。

万相台 AI 开发必须打开淘宝官方网页查找接口：
https://developer.alibaba.com/docs/api.htm?apiId=68719

淘宝电商优先使用 [已实测接口目录](https://api.miandanni.com/docs/taobao-commerce-verified.json) 中的方法，按 availability 查看查询或修改的验证范围；完整官方参考目录包含尚未验证及本次权限被拒的方法，不作为可用承诺。旺店通、聚水潭按各自官方文档。不要猜方法名、字段、金额单位或商家资格。

## 2. 执行签名请求

签发成功是 HTTP 200、`{"ok":true,"data":{...}}`，data 的合同为：

```json
{
  "version": 1,
  "ticketId": "仅供排查的请求标识",
  "service": "wanxiang",
  "method": "taobao.universalbp.new.account.get.can.use.bizcode",
  "issuedAt": "2026-10-15T00:00:00.000Z",
  "request": {
    "url": "https://eco.taobao.com/router/rest",
    "httpMethod": "POST",
    "encoding": "form",
    "headers": {"Content-Type": "application/x-www-form-urlencoded; charset=utf-8"},
    "fields": {"method": "官方方法", "session": "本店铺访问凭据", "sign": "当次签名"}
  }
}
```

以上为字段示意，不能当成可执行请求。程序只执行签发响应，不自行拼造公共鉴权字段。

- `raw`：奇门使用。`request.body` 是精确正文，以 UTF-8 原样发送，不解析、重新序列化或追加字段。Python 用 `data=body.encode("utf-8")`，不用 `json=...`。
- `form`：TOP 普通调用使用 `fields`，原样作为字符串表单发送，不能改变值或再次 JSON 编码。奇门若返回已编码的 `body`，必须把该字符串 UTF-8 原样发送，不能再次表单编码。
- `multipart`：TOP 文件上传。发送 `fields` 与 `fileFields` 对应的本地文件，按 multipart/form-data 编码；boundary 由客户端生成。

校验 HTTPS、官方域名和服务对应的固定请求路径，不跟随重定向，不将客户 Authorization、Cookie 或自定义鉴权头带到上游。不要打印完整签名 URL、请求正文或 fields。

签名成功只表示可以发起这次请求，不表示上游业务执行成功。官方响应直接到客户程序；保留原始 error_response、top_result、批量错误、错误码与 request_id。签名阶段失败使用奇门云 error 结构。

## 3. Python 客户端与上传

服务台“AI 对接包”会自动配置本客户的密钥、店铺和绑定。包内 `client.py` 与 [公开 Python 客户端](https://api.miandanni.com/examples/qimenyun_direct.py) 使用相同协议，无第三方依赖，Python 3.9+。

```python
import json
from pathlib import Path
from client import Client

config = json.loads(Path("config.json").read_text(encoding="utf-8"))
client = Client(config)  # 只支持 direct
result = client.call("taobao", {
    "shopKey": config["services"]["taobao"]["shops"][0]["shopKey"],
    "method": "taobao.shopcats.list.get", "params": {}
})
```

图片上传在申请签名时只传文件名，不上传图片内容：

```json
{"shopKey":"自己的店铺","method":"taobao.picture.upload","params":{"picture_category_id":0,"image_input_title":"商品图"},"files":{"img":{"filename":"product.jpg"}}}
```

AI 开发实际上传功能时调用 `client.call("taobao", body, files={"img": "product.jpg"})`。SDK 申请签名后，将文件直接上传淘宝。命令行演示保持只读，执行 `python client.py` 仅列出请求，不发网络请求。

淘宝 [TOP 签名规则](https://developer.alibaba.com/docs/doc.htm?articleId=101617&docType=1&treeId=49) 排除 byte[] 字段，因此签名不绑定最终图片字节；奇门云不会检查直连上传的最终图片。客户端检查只能防误用，文件大小、格式和内容最终由淘宝按具体接口规则校验。

## 4. 修改、创建、删除与退款

签名直连支持服务当前接入的官方查询及写方法，不能绕过官方权限、IP 白名单、聚石塔部署条件、店铺资格或具体业务状态。退款包中有哪些操作以该方法官方定义为准，不承诺任意退款都能执行。

先核对店铺、目标对象、金额和参数再执行。不要自动重试写请求，不要超时后换另一种调用方式再次执行。网络超时不表示未执行；先查询实际对象或业务状态。只有官方方法明确支持幂等字段时才按其文档使用，ticketId 不是平台幂等键。

## 5. 凭证、到期和老客户

- AppSecret 和 refresh_token 留在奇门云服务器，不进入对接包或签名响应。
- 万相台与淘宝电商的签名请求会包含客户自己店铺的 session/access_token。它属于客户店铺授权凭据，仍应私密保存在客户服务器内存，不放前端、日志或公共代码仓库。
- 每次申请都检查本站服务和绑定。万相台、电商还检查实际淘宝服务订购和授权；奇门套餐不套用淘宝服务市场周期。
- 停用、解绑、到期或重置密钥会阻止后续签发。已签发请求在平台接受的时间窗口内可能重复使用；已交付 Token 不能靠本地删除配置即时收回。不承诺签名一次性或平台所有请求即时失效。
- 新包客户端只支持签名直连，不提供模式切换；读取到非 direct 配置时会在联网前明确拒绝，不能静默改变调用方式。

直连调用的执行结果不经过奇门云，签发记录不是平台实际调用次数，也不是执行成功记录。
