场景
适用场景
这个接口适合用在什么地方？下面的场景可以帮你判断它是不是你要找的那个。
- 在接入前先查询哪些日期有导出文件，避免请求不存在的日期。
- 给导出页做一个年月选择器，年份和月份直接来自 availableYears 和 availableMonths。
问答
常见问题
接入时最常遇到的疑问，先看看这里能不能解答。
不传 year 和 month 会怎样？
服务端会自动选择最近有导出文件的一年一月，并把 selectedYear、selectedMonth 返回给你。
请求的年月没有导出文件会怎样？
接口不会返回参数错误，而是选择最接近的可用年份和月份；最终采用的值以 selectedYear 和 selectedMonth 为准。
items 里的 serviceDay 是什么？
它表示有导出文件的日期，是按上海时间自 1970-01-01 起的天数（epoch day），例如 20679 对应 2026-08-14。需要展示日期时再换算，不要直接当日期字符串用。
扣费
扣费规则
每次请求按固定额度扣费，不随返回条数变化。
固定 10 点额度/次
实际扣费以响应头 x-api-cost 为准。
请求说明
参数
查询参数
yearinteger
请求优先选择的年份，例如 2026。留空或无法匹配时，服务端会选择最近的可用年份。
示例：2026
monthinteger
请求优先选择的月份。留空或没有完全匹配时，服务端会选择该年份最接近的可用月份。
示例：8
响应说明
状态码与响应格式
200
当前可用的导出日期索引。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "true",
"required": true,
"enum": [
true
]
},
"data": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"selectedYear",
"selectedMonth",
"availableYears",
"availableMonths",
"items"
],
"properties": {
"selectedYear": {
"type": "integer",
"required": true
},
"selectedMonth": {
"type": "integer",
"required": true
},
"availableYears": {
"type": "array<integer>",
"required": true,
"shape": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"availableMonths": {
"type": "array<integer>",
"required": true,
"shape": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"items": {
"type": "array<object>",
"required": true,
"shape": {
"type": "array",
"items": {
"type": "object",
"required": [
"serviceDay"
],
"properties": {
"serviceDay": {
"type": "integer",
"required": true
}
}
}
}
}
}
}
},
"error": {
"type": "",
"required": true,
"enum": [
""
]
}
}
}示例响应
{
"ok": true,
"data": {
"selectedYear": 2026,
"selectedMonth": 8,
"availableYears": [
2026
],
"availableMonths": [
8,
7,
6,
5,
4,
3
],
"items": [
{
"serviceDay": 20692
},
{
"serviceDay": 20691
}
]
},
"error": ""
}401
请求未携带有效的认证信息，或提供的 API Key 已失效。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "API Key 无效或已过期",
"error": "invalid_api_key"
}403
账号已被封禁。；当前凭证缺少调用该接口所需的 scope。；当前身份的额度上限低于接口最低调用成本。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}账号已被封禁。
{
"ok": false,
"data": "账号已被封禁",
"error": "account_banned"
}当前凭证缺少调用该接口所需的 scope。
{
"ok": false,
"data": "当前 API Key 缺乏访问该接口的权限",
"error": "forbidden_scope"
}当前身份的额度上限低于接口最低调用成本。
{
"ok": false,
"data": "当前身份额度上限不足，无法调用该接口",
"error": "cost_exceeds_quota_limit"
}406
Accept 请求头不支持 JSON 响应。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "Accept 不支持 application/json 或 application/x-protobuf",
"error": "not_acceptable"
}429
额度不足或请求过于频繁，建议等 Retry-After 提示的时间后再试。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "额度不足，请稍后再试",
"error": "quota_exceeded"
}500
服务内部错误或响应编码失败。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "服务内部错误，请稍后再试",
"error": "internal_error"
}