场景
适用场景
这个接口适合用在什么地方？下面的场景可以帮你判断它是不是你要找的那个。
- 在接入前先查询哪些日期有导出文件，避免请求不存在的日期。
- 给导出页做一个年月选择器，年份和月份直接来自 availableYears 和 availableMonths。
问答
常见问题
接入时最常遇到的疑问，先看看这里能不能解答。
不传 year 和 month 会怎样？
服务端会自动选择最近有导出文件的一年一月，并把 selectedYear、selectedMonth 返回给你。
items 里的 serviceDay 是什么？
它表示有导出文件的日期，是按上海时间自 1970-01-01 起的天数（epoch day），例如 20679 对应 2026-08-14。需要展示日期时再换算，不要直接当日期字符串用。
扣费
扣费规则
每次请求按固定额度扣费，不随返回条数变化。
固定 10 点额度/次
实际扣费以响应头 x-api-cost 为准。
请求说明
参数
查询参数
yearinteger
按年份筛选导出索引，例如 2026。留空时自动选择最近有导出文件的月份。
示例：2026
monthinteger
按月份筛选导出索引，取值 1-12。留空时自动选择最近有导出文件的月份。
示例：8
响应说明
状态码与响应格式
200
当前可用的导出日期索引。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"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
}
}
}
}
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 10
},
"data": {
"selectedYear": 2026,
"selectedMonth": 8,
"availableYears": [
2024,
2025,
2026
],
"availableMonths": [
1,
2,
3,
4,
5,
6,
7,
8
],
"items": [
{
"serviceDay": 20679
},
{
"serviceDay": 20678
}
]
}
}400
请求参数不合法：可能是日期格式、游标格式或 limit 不符合要求。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "invalid_param",
"message": "date 必须使用 YYYYMMDD 格式。"
}
}401
请求未携带有效的认证信息，或提供的 API Key 已失效。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "invalid_api_key",
"message": "API Key 无效或已过期。"
}
}403
当前凭证缺少调用该接口所需的 scope。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "forbidden",
"message": "缺少调用该接口所需的权限。"
}
}429
额度不足或请求过于频繁，建议等 Retry-After 提示的时间后再试。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "rate_limited",
"message": "额度不足，请稍后再试。"
}
}