西柚洞察OPENAPI-V2接入指引

概述

本文档介绍如何接入西柚洞察 OpenAPI v2 服务，包括 API Key 鉴权、请求头规范、请求示例、错误处理和调用最佳实践。

OpenAPI v2 复用现有业务接口路径，通过请求头 X-Auth-Version: 2.0 切换到新版鉴权方式。接入方不再需要计算签名，也不再需要传递 X-Client-Id、X-Timestamp、X-Sign。

基本信息

服务地址：https://openapi.xydc.com

接口路径：沿用现有 /v1/... 业务路径

API 版本：v2

认证方式：API Key 请求头鉴权

数据格式：JSON

字符编码：UTF-8

接入流程

1. 申请接入

请在我们的数据平台网站上申请接入：https://platform.xydc.com

2. 保存 API Key

请将 API Key 安全保存到服务端配置或环境变量中：

{
  "api_key": "your_openapi_v2_api_key"
}

安全提醒：

不要在前端代码、客户端 App 或公开仓库中保存 API Key。

不要在日志中打印完整 API Key。

建议定期轮换 API Key。

如果怀疑 API Key 泄露，请及时禁用旧 Key 并重新生成。

3. 发起请求

所有 OpenAPI v2 请求都必须携带：

可选携带：

如果未传 X-Trace-Id，服务端会自动生成，并在响应头中返回。

认证机制

请求头要求

字段名	类型	必填	说明
`X-Auth-Version`	string	是	固定值：`2.0`，用于启用 OpenAPI v2 鉴权
`X-Api-Key`	string	是	平台分配的 OpenAPI API Key
`Content-Type`	string	是	固定值：`application/json`
`X-Trace-Id`	string	否	追踪 ID；不传时服务端自动生成

与 v1 的区别

项目	v1	v2
认证方式	Client ID + Client Secret 签名	API Key
必填认证头	`X-Client-Id`、`X-Timestamp`、`X-Sign`	`X-Auth-Version`、`X-Api-Key`
是否需要签名	是	否
接口路径	`/v1/...`	`/v1/...`
版本切换方式	默认 v1	请求头 `X-Auth-Version: 2.0`

请求示例

curl 示例

Python 示例

Go 示例

响应头

字段名	说明
`X-Trace-Id`	本次请求的链路追踪 ID。排查问题时请提供该值
`X-Cost-Credits`	本次请求消耗的额度。不同接口、参数规模可能对应不同额度
`Retry-After`	触发限流时建议等待的秒数，仅在 429 响应中返回

错误处理

错误响应格式

{
  "code": 401,
  "reason": "APICredentialUnavailable",
  "message": "api key unavailable",
  "metadata": {}
}

字段说明：

字段名	类型	说明
`code`	int	HTTP 状态码
`reason`	string	业务错误码
`message`	string	错误说明
`metadata`	object	错误扩展信息

常见错误码

HTTP 状态码	reason	说明	处理建议
400	`InvalidParams` / `InvalidBiz`	请求参数错误	检查 JSON 格式、字段类型和必填字段
401	`APICredentialUnavailable`	API Key 缺失、无效或不可用	检查 `X-Auth-Version` 和 `X-Api-Key`
403	`CreditBalanceInsufficient`	额度余额不足	充值、续费或联系支持处理额度
403	`CreditAccountUnavailable`	额度账户不可用	联系技术支持确认账号状态
404	`APICredentialNotFound`	API Key 不存在	确认 API Key 是否正确、是否已删除
404	`CreditAccountNotFound`	额度账户不存在	联系技术支持初始化额度账户
429	`RateLimitExceeded`	请求频率超限	按 `Retry-After` 等待后重试
500	`InternalError`	服务内部错误	稍后重试；持续失败请联系技术支持

限流规则

请按默认 40 次/分钟设计客户端调用节奏。若收到 429 响应，请读取响应头 Retry-After，等待对应秒数后再重试。

示例：

额度扣费说明

OpenAPI v2 会根据实际接口和返回结果计算本次请求消耗的额度，并通过响应头 X-Cost-Credits 返回。

扣费说明：

请求鉴权时会检查 API Key 和账号额度是否可用。

请求成功后，服务端会记录本次用量并进入后续结算流程。

如果接口返回错误，通常不会产生业务扣费。

同一个业务请求请尽量复用同一个 X-Trace-Id，方便链路排查。

最佳实践

1. 使用服务端调用

API Key 应只保存在服务端，不要放到浏览器、移动端或小程序中。

2. 记录关键日志

建议记录以下信息，便于排查：

请求时间

请求接口路径

请求参数摘要

HTTP 状态码

响应头 X-Trace-Id

响应头 X-Cost-Credits

错误响应体

不要记录完整 API Key。

3. 设置超时

建议客户端设置 30 秒请求超时。对于网络超时或 5xx 错误，可以进行有限重试。

4. 处理重试

建议重试策略：

400 / 401 / 403：不要自动重试，先修正参数、鉴权或额度问题。

429：读取 Retry-After 后再重试。

5xx / 网络错误：可进行最多 3 次指数退避重试。

5. 保留 Trace ID

每次请求都会返回 X-Trace-Id。如果需要技术支持排查问题，请提供该值。

技术支持

如果接入过程中遇到问题，请提供以下信息：

API Key 的部分脱敏值，例如前 6 位和后 4 位。

请求时间。

请求接口路径。

响应状态码和错误响应体。

响应头 X-Trace-Id。

相关代码片段，需去除 API Key 等敏感信息。

文档版本：v1.0.0

最后更新：2026-06-24

维护团队：西柚洞察技术部

西柚洞察OPENAPI-V2接入指引

概述#

基本信息#

接入流程#

1. 申请接入#

2. 保存 API Key#

3. 发起请求#

认证机制#

请求头要求#

与 v1 的区别#

请求示例#

curl 示例#

Python 示例#

Go 示例#

响应头#

错误处理#

错误响应格式#

常见错误码#

限流规则#

额度扣费说明#

最佳实践#

1. 使用服务端调用#

2. 记录关键日志#

3. 设置超时#

4. 处理重试#

5. 保留 Trace ID#

技术支持#

概述