REST 快速开始

REST 接口以 /v1 为产品契约前缀。日期参数必须使用 ISO 8601 yyyy-MM-dd。

查询单日状态

curl --fail-with-body \
  'https://api.zkogow.top/v1/china-calendar/dates/2026-10-01'

响应中的 dayStatus 表示精细日期状态，workStatus 表示可工作或休息的粗粒度结论：

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

处理未知安排

目标年度的官方安排尚未发布时，接口仍返回 HTTP 200，但 dayStatus 和 workStatus 为 UNKNOWN，datasetVersion 为 null。调用方不得把未知安排当作工作日或休息日。

处理错误

错误响应的媒体类型是 application/problem+json。type 是问题类型的主标识，指向可执行的修复说明；code 是稳定、简短的应用级别别名。

{
  "type": "https://docs.zkogow.top/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"
}

查阅错误说明了解各类型的触发条件和处理方法。