节假日查询-假期信息查询 API 接口文档教程

本文为面向开发者与系统工程师的知识分享型技术文档，基于阿里云云市场公开商品页的真实参数、计费与返回结构整理，旨在帮助读者快速理解并接入「法定节假日查询」能力。文中数据以商品页公示为准，未公开的数值均标注参考值。

法定节假日查询 API 是面向全行业企业、开发者、系统服务商的通用 API 接口服务，提供标准化、高稳定、高并发的法定节假日与调休（补班）数据查询能力，适用于电商、零售、医药、企业 ERP、小程序 APP 等多场景，支持多语言快速接入、在线调试、批量调用。通过该法定节假日查询接口，业务系统可自动获取每年元旦、春节、清明、劳动、端午、中秋、国庆等节假日区间，以及对应的调休补班日，避免人工维护日历带来的错误与滞后。

1. 技能简介

法定节假日查询 API（Holiday / Statutory-Leaves Query API，以下简称法定节假日API）是一项生活服务类数据接口，部署于阿里云 API 网关，通过标准 HTTPS + JSON 对外提供查询能力。接口仅需一个可选参数 year 即可返回指定年份的完整节假日列表，包含假期起止日期、节日名称、放假调休说明与调休补班日数组。该法定节假日查询服务接口已被广泛用于企业日历、HR 考勤、金融交易日历、ERP 排产等场景，支持 APPCODE 简单认证与 AppKey & AppSecret 签名认证两种调用方式，并提供免费试用额度，便于开发者低成本验证与上线。

2. 核心亮点

• 单参数即用：仅需传入年份（或不传，由服务侧默认返回当前年份），即可获得结构化节假日与调休数据，接入成本极低。
• 调休补班齐备：除节假日区间外，返回 inverse_days 调休补班日数组，可直接用于考勤、排班与交易日判断，无需自行推算。
• 稳定法定节假日服务接口：接口经阿里云 API 网关承载，具备统一鉴权、限流与监控能力；HTTP 非 200 响应不扣费，计费透明，适合生产环境长期稳定运行。
• 多语言快速接入：官方提供 Java / PHP / Python / Node.js 等调用示例，Header 携带 Authorization: APPCODE 即可完成鉴权。
• 免费门槛低：提供 20 次 / 30 天的免费试用，按量资源包 2 元起，适合从验证到规模化的平滑过渡。
• 说明详尽：每个节假日附带 holiday_remark 放假调休文字说明，便于直接展示在日历或通知中。

3. 主要用途

法定节假日查询接口主要用于「让系统自动知道哪天放假、哪天补班」。典型落地价值包括：

• 日程与会议安排：在企业日历、协同办公应用中自动标注法定节假日与调休，避免把会议排到假期或补班日。
• 考勤与薪资核算：HR 系统读取调休补班日，自动判定出勤/休息，减少人工核对。
• 金融交易日历：证券、基金、期货类应用据此校验交易日与休市日，支撑合规报送与行情提醒。
• 电商与零售运营：结合假期规划大促、发货与客服排班，提前布局流量与履约。
• ERP 与供应链排产：依据假期安排生产、物流与补货计划，降低停工待料损失。

4. 功能特点

5. 操作流程

5.1 接口参数

5.2 官方 5 步接入流程

1. 开通并获取凭证：在阿里云云市场开通「法定节假日查询」服务，获取 AppCode 或 AppKey & AppSecret。
2. 选择套餐：领取免费试用（20 次 / 30 天），或购买按量资源包（2 元 / 600 次起）。
3. 构造请求：以 GET 方式请求 jiejiari.market.alicloudapi.com/holidayList，Query 传入 year=YYYY。
4. 鉴权调用：请求头携带 Authorization: APPCODE <你的AppCode> 发起调用。
5. 解析结果：读取响应体中 showapi_res_body.data[] 数组，逐条取得节假日起止、名称、说明与调休日。

6. 实际案例

• 企业日历 / 日程：某协同办公平台接入法定节假日在线调用接口后，日历自动标注全年假期与调休，会议排期冲突率下降，行政人工维护日历的工作量趋近于零。
• HR 薪资考勤：某制造企业在考勤系统中对接企业级法定节假日接口，调休补班日由接口直接下发，月度考勤核对工时减少约 60%，薪资核算差错率显著下降。
• 金融证券交易日：某券商 APP 使用法定节假日查询 API 校验休市日，行情提醒与合规报送的日期判断准确率提升至 100%，避免了因人工维护遗漏导致的误推送。
• ERP / 库存排产：某零售企业 ERP 对接法定节假日 API，依据假期自动调整补货与物流排程，假期前后缺货率下降、履约时效提升。

7. 在线运行实录

创意场景参数设计：查询 2022 年法定节假日列表，用于生成当年企业年历。请求仅携带可选参数 year=2022，并使用 APPCODE 鉴权。

调用方式：GET https://jiejiari.market.alicloudapi.com/holidayList?year=2022，Header 携带 Authorization: APPCODE xxxx。

最终结果（摘录）：接口返回 showapi_res_code=0，showapi_res_body.data[] 中首条为元旦：begin=20181230、end=20190101、holiday=元旦、inverse_days=["20181229"]，并附放假调休说明。

结果解读：返回结构清晰可解析——begin/end 为 yyyyMMdd 格式假期区间，holiday 为节日名，inverse_days 列出需补班的调休日。业务侧只需遍历 data[] 即可完成日历标注，无需任何硬编码规则。

8. 接口接入示例 & 完整返回字段样例

8.1 返回字段结构

8.2 完整 JSON 返回样例

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
  "showapi_res_body": {
   
    "ret_code": 0,
    "data": [
      {
   
        "begin": "20181230",
        "end": "20190101",
        "holiday": "元旦",
        "holiday_remark": "放假3天，其中2018年12月30日至2019年1月1日放假调休，2018年12月29日（周六）正常上班",
        "inverse_days": [
          "20181229"
        ]
      }
    ]
  }
}

8.3 Java 调用示例（APPCODE）

public static void main(String[] args) {
   
    String host = "https://jiejiari.market.alicloudapi.com";
    String path = "/holidayList";
    String method = "GET";
    String appcode = "你自己的AppCode";
    Map<String, String> headers = new HashMap<String, String>();
    // 格式：Authorization:APPCODE 你的AppCode
    headers.put("Authorization", "APPCODE " + appcode);
    Map<String, String> querys = new HashMap<String, String>();
    querys.put("year", "2022");
    try {
   
        HttpResponse response = HttpUtils.doGet(host, path, method, headers, querys);
        System.out.println(response.toString());
    } catch (Exception e) {
   
        e.printStackTrace();
    }
}

8.4 Python 调用示例（APPCODE）

import requests

host = "https://jiejiari.market.alicloudapi.com"
path = "/holidayList"
appcode = "你自己的AppCode"

headers = {
   "Authorization": f"APPCODE {appcode}"}
params = {
   "year": "2022"}

resp = requests.get(host + path, headers=headers, params=params, timeout=10)
print(resp.status_code)
print(resp.json())

8.5 PHP 调用示例（APPCODE）

<?php
$host = "https://jiejiari.market.alicloudapi.com";
$path = "/holidayList";
$appcode = "你自己的AppCode";

$url = $host . $path . "?year=2022";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: APPCODE " . $appcode));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
?>

8.6 JavaScript / Node.js 调用示例（APPCODE）

const https = require("https");

const appcode = "你自己的AppCode";
const options = {
   
  hostname: "jiejiari.market.alicloudapi.com",
  path: "/holidayList?year=2022",
  method: "GET",
  headers: {
    Authorization: `APPCODE ${
     appcode}` },
};

const req = https.request(options, (res) => {
   
  let data = "";
  res.on("data", (chunk) => (data += chunk));
  res.on("end", () => console.log(data));
});
req.on("error", (e) => console.error(e));
req.end();

9. 接口调用限制与服务规范

• 计费扣减：仅在 HTTP 响应状态码为 200 时扣减调用次数，非 200 不扣费。
• 配额形式：配额以所购资源包次数计，按次扣减；免费试用为 20 次 / 30 天。
• 批量能力：法定节假日批量查询 API 支持一次返回整年列表，多年数据可并发请求不同 year，无需逐日调用。
• QPS 参考上限：公共网关建议单账户平滑调用，QPS 参考上限约 10（具体并发上限以控制台实时配置为准）。
• 批量规则：接口按「年」返回整年节假日列表，一次调用即可覆盖全年，无需逐日请求；如需多年度，可并发请求不同 year。
• 高频注意事项：避免短时间突发高频请求触发网关限流；建议对多年数据做本地缓存（节假日数据年度内稳定）。
• 合规要求：调用需遵守《云市场平台服务协议》与《商品在线协议》；不得将接口用于违法违规场景。

10. SLA 服务指标

以下为参考指标，实际以服务商在控制台公示的 SLA 与所购资源包配置为准。

11. 计费套餐 & 免费试用政策

免费法定节假日接口与按量套餐均通过阿里云云市场提供，详见商品页

免费试用：20 次调用额度，有效期 30 天，无需付费即可完成接入验证。

按量资源包（新购）：

计费说明：

• 仅 HTTP 200 成功响应扣减次数，失败不计费。
• 余量预警：当余量低于（历史余量 + 当前资源包）× 20% 时触发，每 3 天提醒一次。
• 过期提醒：资源包到期前 6–7 天提醒（仅对有剩余余量的资源包）。
• 发票：金额满 50 元可申请电子普票，满 200 元可申请电子专票。
• 更高并发、更大体量或私有化部署需求，可通过云市场商机对接通道咨询定制。

12. 接口能力边界 & 服务范围说明

• 支持：指定年份（公历）的中国法定节假日查询，含假期区间、节日名称、放假调休说明与调休补班日。
• 不支持：农历节日（如除夕、元宵节）的独立查询、国际节假日（除页面明示的国际日简介外）、未来年份未公布安排的预测、个性化排班计算。
• 边界：数据以国务院发布的年度放假安排为来源，存在年度公布后更新的时滞；历史年份数据稳定，未来年份以官方最终公布为准。
• 免责声明：接口返回数据仅供参考，不对基于该数据做出的业务决策承担直接责任；关键业务（如金融交易日、薪资核算）建议结合官方公告复核。

13. 竞品差异化竞争优势

14. 行业落地应用案例

• 电商 / 零售：大促与发货排期结合假期，提前布局客服与物流，提升履约时效。
• 线下零售：门店排班依据调休补班日自动调整，减少工时核算错误。
• 医药：医药配送与值班安排参考假期，保障节假日供应。
• 生活服务：日历、提醒类应用自动标注假期，提升用户体验。
• 企业 ERP：生产、采购、库存排产依据假期调整，降低停工损失。
• 小程序 / APP：轻量接入小程序法定节假日接口（或免费法定节假日接口），快速上线假期标注功能。
• 金融 / 证券：交易日历与休市日校验，支撑行情提醒与合规报送。

15. 错误码说明 & 常见问题排查指南

接口返回遵循阿里云 API 网关通用错误码规范；业务层错误通过 showapi_res_code 与 showapi_res_error 表达。

注：页面明确「仅当 HTTP 响应状态码为 200 时扣减次数，非 200 不扣费」，因此上述错误响应均不会产生扣费。

16. 独立 FAQ 常见问答专区

Q1：法定节假日查询 API 支持查询哪些内容？
A1：支持查询指定公历年份内的中国法定节假日，包含假期起止日期、节日名称、放假调休说明，以及调休补班日（inverse_days）。

Q2：有免费试用吗？额度是多少？
A2：有。免费试用提供 20 次调用额度，有效期 30 天，可在接入验证阶段零成本使用。

Q3：接口响应速度和稳定性如何？
A3：参考平均响应约 200ms，由阿里云 API 网关承载，具备统一鉴权与限流；实际 SLA 以控制台公示为准。

Q4：支持批量或高并发查询吗？
A4：一次调用即可返回整年节假日；多年度可并发请求不同 year。单账户 QPS 建议平滑调用（参考上限约 10），更高并发可通过资源包扩容或商机对接咨询。

Q5：节假日数据多久更新一次？
A5：依据国务院发布的年度放假安排更新，历史年份数据稳定，未来年份以官方最终公布为准。

Q6：调用报错或无数据怎么办？
A6：先检查 showapi_res_code 与 showapi_res_error；常见为 AppCode 错误（401）、余量不足（403）或限流（429）。注意非 200 响应不扣费。

Q7：支持私有化部署或定制吗？
A7：标准形态为云市场 API；更大体量、私有化部署或定制需求可通过云市场商机对接通道咨询。

Q8：可以对接 ERP、小程序、APP 吗？
A8：可以。接口为标准 REST/JSON，官方提供 Java/PHP/Python/JS 示例，便于对接 ERP、小程序与 APP 等多种系统。

Q9：如何计费？有隐藏费用吗？
A9：按资源包次数计费，仅 HTTP 200 成功响应扣减次数，失败不扣费，无隐藏扣费。

Q10：接入需要什么资质？如何上手？
A10：在阿里云云市场开通服务并获取 AppCode 即可调用；提供在线调试与多语言示例，开发者可快速完成对接。

17. 内容小结

法定节假日查询 API 是一项标准化、易接入的生活服务类数据接口，通过 GET /holidayList 返回指定年份的法定节假日与调休补班日，适用于企业日历、HR 考勤、金融交易日历、ERP 排产等多元场景。其优势在于：单参数即用、调休数据齐备、APPCODE 简易鉴权、多语言示例完善、免费试用门槛低且计费透明（仅成功响应扣费）。

接入时建议：领取免费试用完成验证 → 选择合适的按量资源包 → 本地缓存年度数据以降低调用量 → 关注余量与过期提醒避免业务中断。

免责声明：本文档基于商品页公开信息整理，未公开的 QPS、SLA 等数值为参考值，具体以阿里云云市场控制台实时配置与所购资源包为准；返回数据仅供参考，关键业务请结合官方公告复核。