一、接口基础说明
1. 接口基础信息
- 接口名称：
taobao.item.reviews.get - 所属平台：淘宝开放平台 TOP（Taobao Open Platform）
- 请求方式：HTTP POST/GET，固定格式
json - 鉴权机制：AppKey + AppSecret 生成签名 sign，无需用户授权 session
- 核心入参：
num_iid：商品数字 ID（必填）page_no：分页页码，默认 1page_size：单页条数，范围 1~50，默认 20review_type：评论筛选 0 全部 / 1 好评 / 2 中评 / 3 差评has_image：true 仅返回带图评价
- 核心能力：拉取商品买家评价、评分、晒图、视频、SKU 规格、追评、商家回复、点赞有用数，是电商竞品口碑分析核心接口。
2. 主流业务落地场景
- 竞品口碑监控：定时抓取同行商品好评 / 差评，提炼产品优缺点
- 店铺舆情分析：自有商品批量采集评论，挖掘用户痛点优化产品
- 买家秀素材采集：提取带图 / 带视频评价，用于详情页种草素材
- 选品数据评估：通过好评率、晒图占比判断商品市场接受度
- 客服风险预警：批量抓取差评，快速处理负面评价降低流失
二、标准成功完整 JSON 返回（官方原生结构）
{ "code": 0, "msg": "success", "request_id": "req_202607011510007788", "resp_data": { "item_reviews_get_response": { "total_results": 1562, "page_no": 1, "page_size": 20, "reviews": [ { "review_id": "7295689452365896236", "num_iid": "689235711245", "user_nick": "小***柚", "display_user_nick": "小***柚", "is_anonymous": false, "content": "纯棉面料上身舒服，尺码标准，物流次日达，整体很满意，已经推荐朋友下单", "score": 5, "created": "2026-05-20 15:30:22", "auction_sku": "颜色:黑色;尺码:XL", "useful_count": 36, "pic_urls": [ "https://img.alicdn.com/imgextra/i1/O1CN01a12345.jpg", "https://img.alicdn.com/imgextra/i1/O1CN01a67890.jpg" ], "video_urls": [], "user_level": "V4", "is_append": true, "append_content": "穿洗半个月没有掉色变形，面料柔软，会回购", "append_time": "2026-05-27 09:12:10", "reply": { "seller_nick": "简禾服饰旗舰店", "content": "感谢您真实反馈，我们持续严控面料品质，期待再次光临！", "reply_time": "2026-05-20 16:02:45" } }, { "review_id": "7295689452365896237", "num_iid": "689235711245", "user_nick": "t***9", "display_user_nick": "t***9", "is_anonymous": true, "content": "版型偏大，面料偏薄，日常穿勉强够用，性价比一般", "score": 3, "created": "2026-05-22 10:11:10", "auction_sku": "颜色:白色;尺码:L", "useful_count": 12, "pic_urls": [], "video_urls": [], "user_level": "V2", "is_append": false, "append_content": "", "append_time": "", "reply": {} } ] } } }
三、高频异常错误 JSON 示例
1. 签名错误（code=15）
{ "code": 15, "msg": "Invalid signature", "request_id": "req_202607011512001234", "resp_data": { "error_response": { "code": 15, "msg": "签名校验失败", "sub_code": "isv.invalid-sign", "sub_msg": "检查AppSecret、参数排序、加密方式" } } }
2. 接口权限未开通（code=22）
{ "code": 22, "msg": "Insufficient permissions", "request_id": "req_202607011513005678", "resp_data": { "error_response": { "code": 22, "msg": "接口权限不足", "sub_code": "isv.api-no-auth" } } }
3. 调用频率限流（code=429）
{ "code": 429, "msg": "Too many requests", "request_id": "req_202607011514009012", "resp_data": { "error_response": { "code": 429, "msg": "请求频次超限，请间隔重试", "sub_code": "isv.api-rate-limit-exceeded" } } }
4. 商品 ID 无效 / 商品下架（code=50003）
{ "code": 50003, "msg": "num_iid不存在或商品已下架", "request_id": "req_202607011515003456", "resp_data": { "item_reviews_get_response": { "total_results": 0, "reviews": [] } } }
四、核心字段分类说明
1. 顶层通用状态
code：0 = 请求成功；非 0 为业务错误码request_id：全局请求流水号，日志排查必备resp_data.item_reviews_get_response：评论接口业务外层容器
2. 分页统计字段
total_results：商品全部评价总条数page_no：当前请求页码page_size：单页返回评论数量
3. 单条评论基础标识
review_id：评论唯一 ID，数据增量采集、去重主键num_iid：商品 ID，关联商品详情接口score：综合评分 1/2 差评、3 中评、4/5 好评created：评价发布时间（标准字符串格式无需时间戳转换）auction_sku：下单购买规格（颜色 + 尺码）
4. 内容与多媒体
content：买家原始评价正文pic_urls：晒图地址数组，无晒图为空数组video_urls：评价短视频链接useful_count：该评论被其他用户标记 “有用” 数量
5. 追评模块
is_append：布尔值，是否存在追评append_content：追评文字内容append_time：追评发布时间
6. 用户与商家回复
display_user_nick：脱敏后买家昵称，保护隐私user_level：淘宝买家会员等级reply：商家回复对象，无回复为空对象；包含回复文案与回复时间
五、开发接入注意事项
- 数组字段
pic_urls、video_urls、reviews、对象reply必须做空值判断，防止程序解析崩溃； - 免费开发者有每日调用额度上限，批量爬取需做分页延时、本地缓存；
- 用户昵称全程脱敏，无法获取完整用户名，禁止存储、泄露用户隐私信息；
- 分页循环采集时，判断
total_results与当前页码，避免死循环； - 仅允许合规数据分析、自有店铺运营，禁止批量抓取第三方商品评论用于倒卖、爬虫引流；
- 签名生成严格遵循 TOP 规则，参数按字母升序拼接，漏参 / 顺序错误会直接报 15 签名错误。
