xiyou-openapi
    xiyou-openapi
    • 西柚找词OPENAPI接入指引
    • asins
      • asin流量得分
        POST
      • asin基础信息变动趋势（天）
        POST
      • asin流量得分趋势（天）
        POST
      • asin广告信息变动趋势（天）
        POST
      • asin BSR排名趋势（天）
        POST
      • asin订单量趋势（月）
        POST
      • asin商品信息趋势图（天）
        POST
      • asin反查关键词列表（最近天）
        POST
      • asin反查关键词列表（月）
        POST
      • asin商品信息
        POST
    • asinSearchTerms
      • asin词流量趋势（天）
        POST
      • asin词排名趋势（天）
        POST
    • searchTerms
      • 关键词ABA数据趋势（周）
        POST
      • 关键词信息（最近一周）
        POST

    西柚找词OPENAPI接入指引

    OpenAPI 接入指南#

    概述#

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

    基本信息#

    服务地址: https://openapi.xiyouzhaoci.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-Idstring是您的16位Client ID
    X-Timestampstring是当前时间戳（秒级，10位数字）
    X-Signstring是计算得出的签名（小写十六进制）
    Content-Typestring是固定值：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": {}
}

    字段描述#

    字段名类型必填说明
    codeint是返回的http状态吗
    reasonstring是返回的业务错误码
    messagestring是返回的错误信息
    metadatamap是返回的错误详细信息

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

    错误类型错误码说明
    InvalidClientId400Client ID格式错误（必须是16位字符）
    InvalidTimestamp400时间戳格式错误或已过期
    InvalidSign400签名验证失败
    InvalidBiz400业务参数格式错误
    ClientInActive403客户端未激活
    ClientQuotaInsufficient403客户端配额不足

    限流规则#

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

    最佳实践#

    1. 时间戳同步#

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

    2. 请求重试#

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

    3. 日志记录#

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

    4. 安全建议#

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

    技术支持#

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