REST 快速开始

本页引导您完成第一次 REST 请求，并解释响应结构。

先决条件

具备执行命令行命令的环境，或可直接在浏览器中访问 URL；

第一次请求

查询 2026 年 10 月 1 日的状态：

curl 'https://api.wanduanapi.com/v1/china-calendar/dates/2026-10-01'

响应如下：

{
  "date": "2026-10-01",
  "dayOfWeek": "THURSDAY",
  "workStatus": "REST_DAY",
  "dayStatus": "HOLIDAY",
  "holidays": [
    {
      "code": "NATIONAL_DAY",
      "name": "国庆节",
      "statutoryDate": true
    }
  ],
  "datasetVersion": "2026-r1"
}

响应字段的含义：

第一次接入时通常先关注以下字段：

date 和 dayOfWeek：查询日期及其星期信息；
workStatus：粗粒度的上班或休息结论，适合排班与考勤场景；
dayStatus：更具体的日期状态，用于区分普通工作日、调休补班、周末和节假日安排；
holidays：关联节日列表；其中的 statutoryDate 用于区分法定节假日当天与同一节日安排下的其他日期；
datasetVersion：本次查询使用的数据集版本，目标年度官方安排尚未发布时为 null。

完整字段、可空规则和所有枚举值见 REST 参考。

更多端点

查询日期区间：返回区间内每天的完整状态（首尾均包含，最长 366 天）：

curl 'https://api.wanduanapi.com/v1/china-calendar/date-ranges?startDate=2026-10-01&endDate=2026-10-08'

统计工作日：直接返回计数结果，适用于算薪与排班：

curl 'https://api.wanduanapi.com/v1/china-calendar/workdays?startDate=2026-10-01&endDate=2026-12-31'

{
  "startDate": "2026-10-01",
  "endDate": "2026-12-31",
  "totalDays": 92,
  "workdayCount": 62,
  "restDayCount": 30,
  "unknownDayCount": 0
}

workdayCount、restDayCount 和 unknownDayCount 分别表示已确定的工作日、已确定的休息日，以及官方安排尚未发布的日期数量；完整字段说明见 REST 参考。

查询下一个节假日：适用于放假倒计时类功能：

curl 'https://api.wanduanapi.com/v1/china-calendar/next-holiday?fromDate=2026-09-16'

{
  "status": "FOUND",
  "date": "2026-09-25",
  "holidays": [
    {
      "code": "MID_AUTUMN_FESTIVAL",
      "name": "中秋节",
      "statutoryDate": true
    }
  ],
  "datasetVersion": "2026-r1"
}

status=FOUND 表示已找到下一节假日；如果后续年度的官方安排尚未发布，则返回 status=UNKNOWN，此时 date 和 datasetVersion 为 null，holidays 为空数组。完整字段和取值见 REST 参考。

全部端点与参数见 REST 参考。

官方安排尚未发布时

目标年度的官方安排尚未发布时，接口正常返回 200，dayStatus 与 workStatus 为 UNKNOWN，datasetVersion 为 null：

{
  "date": "2027-05-01",
  "dayOfWeek": "SATURDAY",
  "workStatus": "UNKNOWN",
  "dayStatus": "UNKNOWN",
  "holidays": [],
  "datasetVersion": null
}

注意

不应将 UNKNOWN 视为工作日或休息日。国务院通常在前一年年底发布下一年安排，发布后相关日期会自动更新为确定结论。

错误处理

错误响应使用 RFC 9457 Problem Details 格式，响应媒体类型为 application/problem+json，对应的 HTTP 响应头为 Content-Type: application/problem+json。type 指向对应的错误说明页，code 是稳定的程序可读短码：

{
  "type": "https://docs.wanduanapi.com/problems/invalid-date-format",
  "title": "日期格式无效",
  "status": 400,
  "detail": "日期必须使用 ISO 8601 yyyy-MM-dd 格式",
  "instance": "/v1/china-calendar/dates/2026-10-0",
  "code": "INVALID_DATE_FORMAT",
  "requestId": "f4935479-81fe-406f-b9d8-a4b67d6d6399"
}

最常见的错误是日期格式不符合要求：必须是 yyyy-MM-dd，2026/10/01 和 2026-10-0 都会被拒绝。全部错误类型的触发条件与修复方式见错误说明。

遇到无法定位的问题时，请保留响应中的 requestId，反馈时附上以便排查。

后续步骤

→ REST 参考：全部端点、参数与 operationCode

→ 数据范围与可信度：支持范围与判定顺序

→ MCP 快速开始：同样的能力，接入 AI Agent

先决条件​

第一次请求​

更多端点​

官方安排尚未发布时​

错误处理​

后续步骤​