> 完整文档索引见 [llms.txt](https://docs.wanduanapi.com/llms.txt)。本站每个文档页均提供 Markdown 镜像；当前页面的 Markdown 版本见 [此处](https://docs.wanduanapi.com/products/china-calendar/rest/quickstart.md)。

# REST 快速开始

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

## 先决条件

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

## 第一次请求

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

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

响应如下：

```json
{
  "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 参考](./reference.md)。

## 更多端点

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

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

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

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

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

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

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

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

```json
{
  "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 参考](./reference.md)。

全部端点与参数见 [REST 参考](./reference.md)。

## 官方安排尚未发布时

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

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

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

## 错误处理

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

```json
{
  "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` 都会被拒绝。全部错误类型的触发条件与修复方式见[错误说明](../../../problems/index.md)。

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

## 后续步骤

→ [REST 参考](./reference.md)：全部端点、参数与 operationCode

→ [数据范围与可信度](../data-and-coverage.md)：支持范围与判定顺序

→ [MCP 快速开始](../mcp/quickstart.md)：同样的能力，接入 AI Agent