xiyou-openapi
    • 西柚洞察OPENAPI-V2接入指引
    • 西柚洞察OPENAPI接入指引（已归档）
    • Release Notes
    • 西柚洞察OPENAPI-V1接入指引（该接入已归档）
    • asins
      • asin流量得分
        POST
      • asin基础信息变动趋势（天）
        POST
      • asin流量得分趋势（天）
        POST
      • asin广告信息变动趋势（天）
        POST
      • asin BSR排名趋势（天）
        POST
      • asin订单量趋势（月）
        POST
      • asin商品信息趋势图（天）
        POST
      • asin反查关键词列表（最近天）
        POST
      • asin反查关键词列表（月）
        POST
      • asin商品信息
        POST
      • 获取asin变体接口
        POST
    • asinSearchTerms
      • asin词流量趋势（天）
        POST
      • asin词排名趋势（天）
        POST
      • asin词排名趋势（小时）
        POST
    • searchTerms
      • 关键词分析列表（最近天）
        POST
      • 关键词分析列表（月）
        POST
      • 关键词ABA数据趋势（周）
        POST
      • 关键词信息（最近一周）
        POST
    • client
      • 获取client Id的余额
        POST

    西柚洞察OPENAPI-V1接入指引（该接入已归档）

    OpenAPI 接入指南#

    概述#

    本文档介绍如何接入我们的OpenAPI服务，包括认证方式、签名计算和接入流程。

    基本信息#

    服务地址: https://openapi.xydc.com
    API版本: v1
    认证方式: 基于Client ID和Client Secret的签名认证
    数据格式: JSON
    字符编码: UTF-8

    接入流程#

    1. 申请接入#

    1.
    联系我们的技术支持团队
    2.
    提供您的企业信息和使用场景
    3.
    我们为您分配：
    Client ID: 16位字符串，用于标识您的应用
    Client Secret: 24位字符串，用于签名验证

    2. 配置认证信息#

    将获得的认证信息安全保存：
    
{
  "client_id": "your16charclientid",
  "client_secret": "your24charclientsecret"
}
    ⚠️ 安全提醒：
    请妥善保管Client Secret，不要泄露给第三方
    不要在代码中硬编码认证信息
    建议使用环境变量或配置文件存储

    认证机制#

    签名算法#

    我们使用SHA256签名算法，签名计算方式如下：
    
签名 = SHA256(client_id + timestamp + client_secret + request_body)

    
signature = sha256(sign_str).hexdigest()

参数说明:

client_id: 与 X-Client-Id 相同

timestamp: 与 X-Timestamp 相同（秒级 UNIX 时间戳）

client_secret: 分配给调用方的密钥（务必妥善保管）

request_body: 与实际请求体完全一致的字符串

若为 JSON，请进行“有序序列化”：键名按字典序升序、无多余空格，序列化等价于 Python 的 json.dumps(obj, separators=(',', ':'), sort_keys=True)

若无请求体（如 GET），则置为空字符串 ""

    请求头要求#

    每个API请求必须包含以下HTTP头：
    | 字段名 | 类型 | 必填 | 说明 |
    |--------|------|------|------|
    | X-Client-Id | string | 是 | 您的16位Client ID |
    | X-Timestamp | string | 是 | 当前时间戳（秒级，10位数字） |
    | X-Sign | string | 是 | 计算得出的签名（小写十六进制） |
    | Content-Type | string | 是 | 固定值：application/json |

    签名计算示例#

    Python示例#

    Go示例#

    请求示例#

    完整的HTTP请求示例#

    Python完整示例#

    我们建议您使用我们提供的SDK来进行调用#

    SDK参考#

    Python SDK调用示例#

    您可以直接复制下方提供的安装命令在Terminal中执行，以完成SDK的安装：
    
pip3 install xiyou-sdk
    完整示例

    错误处理#

    常见错误码#

    | 错误码 | 说明 | 解决方案 |
    |--------|------|----------|
    | 400 | 请求参数错误 | 检查请求参数格式和必填字段 |
    | 401 | 认证失败 | 检查Client ID、时间戳和签名是否正确 |
    | 403 | 权限不足 | 联系技术支持确认账户状态 |
    | 429 | 请求频率超限 | 降低请求频率，遵循限流规则 |
    | 500 | 服务器内部错误 | 稍后重试，或联系技术支持 |

    错误响应格式#

    
{
  "code": 400,
  "reason": "InvalidClientId",
  "message": "invalid client id: must be exactly 16 characters",
  "metadata": {}
}

    字段描述#

    | 字段名 | 类型 | 必填 | 说明 |
    |--------|------|------|------|
    | code | int | 是 | 返回的http状态吗 |
    | reason | string | 是 | 返回的业务错误码 |
    | message | string | 是 | 返回的错误信息 |
    | metadata | map | 是 | 返回的错误详细信息 |

    具体的业务错误类型示例#

    | 错误类型 | 错误码 | 说明 |
    |----------|--------|------|
    | InvalidClientId | 400 | Client ID格式错误（必须是16位字符） |
    | InvalidTimestamp | 400 | 时间戳格式错误或已过期 |
    | InvalidSign | 400 | 签名验证失败 |
    | InvalidBiz | 400 | 业务参数格式错误 |
    | ClientInActive | 403 | 客户端未激活 |
    | ClientQuotaInsufficient | 403 | 客户端配额不足 |

    限流规则#

    默认限流: 40次/分钟
    超出限流: 返回429错误码
    建议在返回的请求头中的Retry-After的秒数后再次请求：

    最佳实践#

    1. 时间戳同步#

    确保客户端时间与服务器时间同步，时间差不应超过1分钟。

    2. 请求重试#

    对于网络错误，建议重试3次
    对于限流错误（429），请根据返回的相应头中的Retry-After数值休眠对应秒数后再请求
    对于认证错误（401），请检查client_id是否有效，其次检查签名计算逻辑，如果还是不行，请联系支持

    3. 日志记录#

    建议记录以下信息：
    请求时间戳
    请求参数
    响应状态码
    相应头的X-Trace-Id
    错误信息

    4. 安全建议#

    定期轮换Client Secret
    使用HTTPS传输
    不要在日志中记录Client Secret
    直接使用官方SDK进行调用

    技术支持#

    如果您在接入过程中遇到问题，请联系我们的技术支持团队：
    1v1咨询: 客服二维码
    工作时间: 周一至周五 9:30-19:00 (GMT+8)
    响应时间: 24小时内
    请提供以下信息以便我们快速解决问题：
    Client ID（隐藏部分字符）
    错误信息
    请求时间戳
    相应头的X-Trace-Id
    相关代码片段（去除敏感信息）
    文档版本: v1.0.2
    最后更新: 2026年6月
    维护团队: 西柚找词技术部
    修改于 2026-06-29 09:51:49
    上一页
    Release Notes
    下一页
    asin流量得分
    Built with