标题

国家法定节假日数据 API

国家法定节假日数据接口，数据来源为国务院办公厅官方公告，每天凌晨 1:00 自动同步。

鉴权

所有接口均需在请求头中携带访问令牌：

Authorization: Bearer tf_xxxxxxxxxxxxxxxx

令牌在 用户设置 → 访问令牌 页面创建，创建时需勾选对应权限：

权限 说明
read:holiday_calendar 查询节假日数据
write:holiday_calendar 触发数据同步（管理员使用）

接口列表

1. 查询节假日

GET /api/holiday-calendar

所需权限：read:holiday_calendar

查询参数

参数 类型 必填 说明
year integer 与 date 二选一 查询整年数据，例如 2025
date string 与 year 二选一 查询单日，格式 YYYY-MM-DD，例如 2025-01-01

year 和 date 必须传其中一个，同时传以 date 优先。

返回值

按年查询

{
  "status": "success",
  "data": {
    "year": 2025,
    "days": [
      {
        "id": 1,
        "year": 2025,
        "name": "元旦",
        "date": "2025-01-01",
        "is_off_day": 1
      },
      {
        "id": 2,
        "year": 2025,
        "name": "元旦",
        "date": "2025-01-02",
        "is_off_day": 0
      }
    ]
  }
}

按日期查询

{
  "status": "success",
  "data": {
    "id": 1,
    "year": 2025,
    "name": "元旦",
    "date": "2025-01-01",
    "is_off_day": 1
  }
}

当该日期不在节假日安排中时（普通工作日/周末）：

{
  "status": "success",
  "data": null
}

字段说明

字段 类型 说明
id integer 记录 ID
year integer 年份
name string 假期名称，例如「元旦」「春节」「清明节」
date string 日期，格式 YYYY-MM-DD
is_off_day integer 1 = 放假，0 = 补班（调休上班）

示例

# 查询 2025 年全部节假日
curl "https://trendforge.devlive.top/api/holiday-calendar?year=2025" \
  -H "Authorization: Bearer tf_xxxxxxxxxxxxxxxx"

# 查询 2025-01-01 是否是节假日
curl "https://trendforge.devlive.top/api/holiday-calendar?date=2025-01-01" \
  -H "Authorization: Bearer tf_xxxxxxxxxxxxxxxx"

2. 触发数据同步

POST /api/holiday-calendar/sync

所需权限：write:holiday_calendar

从国务院官方网站拉取最新放假公告并解析写入数据库。不传 year 时默认同步当年和次年。

系统每天凌晨 1:00 会自动执行同步，通常无需手动触发。

请求体（JSON）

参数 类型 必填 说明
year integer 否 指定同步年份，范围 1900–2100；不传则同步当年 + 次年

返回值

{
  "status": "success",
  "data": {
    "count": 42
  }
}
字段 说明
count 本次写入/更新的记录条数

示例

# 同步当年 + 次年
curl -X POST "https://trendforge.devlive.top/api/holiday-calendar/sync" \
  -H "Authorization: Bearer tf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

# 同步指定年份
curl -X POST "https://trendforge.devlive.top/api/holiday-calendar/sync" \
  -H "Authorization: Bearer tf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"year": 2025}'

错误响应

所有错误均返回 JSON 格式：

{
  "status": "error",
  "message": "错误描述"
}
HTTP 状态码 原因
400 参数无效（date 格式错误、year 超出范围等）
401 未携带令牌或令牌无效
403 令牌缺少所需权限
404 接口路径不存在
500 服务器内部错误（同步时网络异常等）

数据说明

  • 数据仅包含有调整的日期（放假或补班），普通周末和正常工作日不在其中
  • is_off_day = 1：该日放假（含法定假日本身及调休休息日）
  • is_off_day = 0：该日补班（因调休需要上班的周末）
  • 数据来源为国务院办公厅每年发布的放假通知，通常在上一年年底或当年年初发布
助手