# 淘宝电商 API：已实测接入清单

> 程序对接使用签名直连：奇门云鉴权签名，客户服务器直接请求淘宝并接收业务数据。先阅读[签名合同](https://api.miandanni.com/docs/signed-direct.md)，下载 [Python 客户端](https://api.miandanni.com/examples/qimenyun_direct.py)，或在服务台生成专属 AI 对接包。

当前默认推荐 **15 个已实测查询、1 个已实测修改**，共 6 个接口分组。这里只收录真实业务成功的方法；实测仅证明测试时的已授权店铺与具体业务场景，其他店铺仍需满足淘宝权限、授权和商家资格。

- [已实测接口目录](https://api.miandanni.com/docs/taobao-commerce-verified.json)：默认开发和 AI 对接使用的清单，包含实测状态与说明。
- [全部核实状态](https://api.miandanni.com/docs/taobao-commerce-availability.json)：明确拒绝、参数或场景不足、平台错误和未测试分别记录。
- [本站接入页面](https://api.miandanni.com/docs/taobao)：已实测清单在前，页面仅展示已实测清单，其他状态查看核实 JSON。
- [官方契约参考](https://api.miandanni.com/docs/taobao-commerce-methods.json)：共 513 条参考，**不是本应用可用接口清单**。
- [核对范围与未接入说明](https://api.miandanni.com/docs/taobao-commerce-audit.json)：官方契约核对日期 2026-10-16，文档差异、排除和待核实原因。

不要从完整参考目录挑一个方法便断言本应用可用；不要从一个查询成功推断同组写接口可用。缺少参数、无效目标、HTTP 200 和签名签发都不能计为业务实测成功。

## 已实测查询与修改

| 接口 | 方法 | 实测状态 | 说明 |
| --- | --- | --- | --- |
| [获取前台展示的店铺类目](https://developer.alibaba.com/docs/api.htm?apiId=64) | `taobao.shopcats.list.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 14:46:41） |
| [获取图片分类信息](https://developer.alibaba.com/docs/api.htm?apiId=137) | `taobao.picture.category.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 14:49:58） |
| [获取图片信息](https://developer.alibaba.com/docs/api.htm?apiId=138) | `taobao.picture.get` | 已实测查询 | 普通图片空间查询已成功；后续按商品图片URL过滤返回533 / PICTURE_PARAMETER_ERROR，该过滤方式尚未验证可用。（北京时间 2026/10/16 14:49:58） |
| [查询图片空间用户的信息](https://developer.alibaba.com/docs/api.htm?apiId=10914) | `taobao.picture.userinfo.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 14:49:58） |
| [图片是否被引用](https://developer.alibaba.com/docs/api.htm?apiId=10921) | `taobao.picture.isreferenced.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 14:49:58） |
| [图片获取](https://developer.alibaba.com/docs/api.htm?apiId=25591) | `taobao.picture.pictures.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 14:49:58） |
| [图片总数查询](https://developer.alibaba.com/docs/api.htm?apiId=25592) | `taobao.picture.pictures.count` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 14:49:58） |
| [根据商品ID列表获取SKU信息](https://developer.alibaba.com/docs/api.htm?apiId=30) | `taobao.item.skus.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 16:12:42） |
| [获取SKU](https://developer.alibaba.com/docs/api.htm?apiId=28) | `taobao.item.sku.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 15:35:40） |
| [获取当前会话用户出售中的商品列表](https://developer.alibaba.com/docs/api.htm?apiId=18) | `taobao.items.onsale.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 14:51:13） |
| [得到当前会话用户库存中的商品列表](https://developer.alibaba.com/docs/api.htm?apiId=162) | `taobao.items.inventory.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 14:46:41） |
| [获取单个商品详细信息](https://developer.alibaba.com/docs/api.htm?apiId=24625) | `taobao.item.seller.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 16:12:42） |
| [天猫商品/SKU商家编码更新接口](https://developer.alibaba.com/docs/api.htm?apiId=25076) | `tmall.item.outerid.update` | 已实测修改 | 仅验证单个SKU商家编码修改：新值读回成功、原值恢复后读回成功，9项价格/库存/属性及商品状态校验通过；不代表SKU展示名或详情编辑可用。（北京时间 2026/10/16 15:35:40） |
| [获取天猫商品尺码表模板列表](https://developer.alibaba.com/docs/api.htm?apiId=24327) | `tmall.item.sizemapping.templates.list` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 14:46:41） |
| [获取商品已生效营销活动更新规则](https://developer.alibaba.com/docs/api.htm?apiId=52753) | `taobao.item.promotion.rule.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 15:14:54） |
| [查询卖家用户信息](https://developer.alibaba.com/docs/api.htm?apiId=21349) | `taobao.user.seller.get` | 已实测查询 | 官方TOP只读业务调用成功；仅代表已测试授权店铺和参数。（北京时间 2026/10/16 16:12:42） |

## 如何判断核实状态

| 状态 | 含义 |
| --- | --- |
| verified_read | 已实测查询，取得真实查询成功响应 |
| verified_write | 已实测修改，取得真实修改成功证据 |
| permission_denied | 明确拒绝，不进入默认接入清单；查看应用、身份或资格对应原因 |
| inconclusive | 参数或场景不足，仍属未验证 |
| platform_error | 平台错误，仍属未验证，不能一概归为无权限 |
| not_tested | 尚无真实业务测试记录 |

当前明确拒绝 17 个、参数或场景不足 20 个、平台错误 3 个、未测试 457 个。记录不表示所有店铺通用；没有记录默认未测试。未经授权不得为了验证能力执行发布、退款、删除等写操作。

## 签名直连

先从已实测目录选择方法，打开该条目的 docUrl 官方网页，核对完整字段、类型、层级与商家条件。不要按名称猜参数。

```http
POST https://api.miandanni.com/api/taobao/sign
Authorization: Bearer 客户自己的奇门云密钥
Content-Type: application/json
```

```json
{"shopKey":"自己的已授权店铺","method":"从已实测目录选择的完整方法名","params":{}}
```

沿用有效万相台服务和同一淘宝应用的店铺授权。app_key、session、sign 由服务器生成，不放入 params。客户 Bearer 密钥只发给奇门云，不带到淘宝。

签名响应 `{ok:true,data:{version:1,ticketId,service,method,issuedAt,request}}` 只证明签名签发。SDK 还需执行 data.request 并检查淘宝业务响应；签名审计日志不证明调用或修改成功。AppSecret、refresh_token 不交付，本店 session/access_token 只放客户服务器内存，不写日志或前端。

## 参数、图片与返回处理

电商 params 的 UTF-8 JSON 上限为 **2 MiB**，签名外层 JSON 上限为 **3 MiB**。方法自身更小的限制仍以淘宝规则为准。XML/schema 字符串保留原始换行、中文和转义，不转换成 JSON 对象。

商品、SKU、用户等长 ID 预先使用字符串，例如 `"item_id":"12345678901234567"`，不能先经过 JSON 数字解析再转换。普通 String[]/Number[] 可按官方要求使用 CSV 或列表；复杂 JSON 对象及数组按对应方法填写。目录中的 `location.state` 等点分根字段保留完整字面键，不改成嵌套对象。普通电商不通用添加广告 top_service_context。

File/byte[] 不放 params。申请签名只传 `files[field]={"filename":"product.jpg"}`，SDK 的 files 参数使用客户本地路径，原始字节直接 multipart 上传淘宝。BMP 按具体方法允许的格式与大小使用；可选图未选时不虚构路径，必填图保留需替换的占位。byte[] 不参与 TOP 签名，奇门云不检查直传最终图片；网页代测图片总量另限 10 MiB。

HTTP 200 仍检查 error_response、top_result.info.ok、逐项失败和 request_id，不把错误当成零数据。签名超时或写操作结果未知时，先查询实际状态，不自动重试或换路执行。

## 官方契约参考的使用边界

以下只解释官方业务契约，**不构成接入推荐或实测成功声明**。使用具体方法前必须查看全部核实状态，默认开发清单仍以 verified.json 为准。

- 发布区分自研、分销铺货和全渠道场景，各自使用对应 publish.schema 与 submit，不混用 schema。上下架、删除、GPU 产品库发布分别遵循各自契约。
- 新版编辑先读取 `alibaba.item.edit.schema.get`，再按原始 XML schema 调用 edit.submit 或 edit.fastupdate。增量只修改现有 SKU，新增 SKU 使用全量提交并先设置销售属性。
- 主图、属性图与详情图分别处理。详情图片需先上传取得淘宝地址，再按编辑 schema 提交；上传或 `taobao.picture.replace.new` 替换成功本身不证明商品详情已更新。
- `taobao.fenxiao.product.download` 属于供销产品铺货，需有效合作、产品授权及商家资格；它出现在参考目录中不代表本应用已获权限。
- 子账号、角色、部门及赋权只作用于当前已授权商家身份。UD 仅本店直客 login_type=1、ext="{}"，不传代理或其他商家身份，指定 UDS 账户时会先核实归属。

聚石塔专用、私有或闭包、身份凭证及计费管理、契约不完整的方法，分别见核对范围的 excludedMethods/unresolvedMethods/documentationNotes，不整包开放。`TAOBAO_METHOD_NOT_ALLOWED` 是本站完整方法目录拒绝，不能据此断言淘宝应用权限不足；官方文档核对与实际业务验证分开记录。

AI 对接包的默认淘宝目录也只收录已实测方法，并附全部核实状态及实测证据。不要公开上传 config.json、客户密钥、店铺信息或签名响应。
