API 参考

Castimer REST API、嵌入组件、Webhooks 和快速入门指南的完整参考文档。

REST API

认证

所有 API 请求都需要在 Authorization 请求头中携带 Bearer 令牌。从控制面板获取您的 API 密钥。

Authorization: Bearer YOUR_API_KEY

基础 URL 和请求头

基础 URL：https://castimer.com/api/v1

请求头	值	必需
Authorization	Bearer {api_key}	是
Content-Type	application/json	是（POST/PATCH）
Accept	application/json	否

接口端点

GET/events

列出认证用户的所有计时器事件。

curl -X GET https://castimer.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/timers

创建新计时器。

curl -X POST https://castimer.com/api/v1/timers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "会议计时器",
    "type": "countdown",
    "duration": 1800
  }'

GET/timers/:id

通过 ID 获取特定计时器。

curl -X GET https://castimer.com/api/v1/timers/tmr_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

PATCH/timers/:id/state

更新计时器状态（启动、暂停、恢复、重置）。

curl -X PATCH https://castimer.com/api/v1/timers/tmr_abc123/state \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "state": "running" }'

DELETE/timers/:id

删除计时器。

curl -X DELETE https://castimer.com/api/v1/timers/tmr_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

错误码

状态码	含义
400	错误请求 — 参数无效
401	未授权 — API 密钥无效或缺失
404	未找到 — 计时器不存在
422	无法处理 — 验证错误
429	请求过多 — 超出速率限制
500	服务器内部错误

速率限制

套餐	请求/分钟	请求/天
免费版	30	1,000
Pro	120	10,000
企业版	600	无限

SDK 和库

官方和社区 SDK，支持主流语言和框架。

JavaScript/TypeScript

官方GitHub

Python

官方GitHub

PHP

社区GitHub

Widget URL 格式

Widget 通过单个 URL 提供服务，使用查询参数进行配置：

https://castimer.com/widget?type=countdown&title=My+Timer&duration=300&theme=dark&primary_color=6C63FF&lang=en

参数参考

参数	类型	默认值	说明
type	string	countdown	计时器类型：countdown、event、interval
title	string	-	显示标题
duration	number	-	倒计时时长（秒）
target_date	string	-	目标日期（ISO8601），仅 event 类型
timezone	string	UTC	时区，仅 event 类型
work	number	20	工作时长（秒），仅 interval 类型
rest	number	10	休息时长（秒），仅 interval 类型
rounds	number	8	轮次数，仅 interval 类型
theme	string	dark	主题：light、dark、auto
primary_color	string	6C63FF	主色调（hex 无 #）
lang	string	en	语言：en、zh、ja、es、fr、de、ko
show_title	0\|1	1	显示标题
show_date	0\|1	1	显示日期（仅 event 类型）
alarm	0\|1	1	完成时播放闹钟声音
show_brand	0\|1	1	显示 Castimer 品牌（Pro）

iframe 集成

使用标准 iframe 元素嵌入组件：

<iframe
  src="https://castimer.com/widget?type=countdown&duration=300&theme=dark"
  style="width:360px;height:360px;border:none;"
  loading="lazy"
  title="倒计时计时器"
></iframe>

• style — 设置宽度和高度（最小 100×200，最大 600×600）

• loading="lazy" — 推荐用于性能优化

• title — 无障碍标签

嵌入生成器工具

使用我们的可视化嵌入生成器配置组件并即时生成 iframe 代码。无需手动构建 URL。

提示：生成器提供实时预览，您可以在复制代码之前准确查看组件的外观。

Webhooks

在计时器事件发生时获取实时通知。完整文档请参阅Webhooks 指南。

概述

Webhooks 让 Castimer 能够在计时器事件发生时实时通知您的服务器——比如启动、暂停或归零。在创建或更新计时器时注册 Webhook URL。

事件类型

事件	触发条件
timer.started	计时器开始运行
timer.paused	计时器被暂停
timer.resumed	计时器从暂停状态恢复
timer.completed	计时器归零
timer.reset	计时器重置为初始时长
interval.round_end	间隔计时器的一轮完成
interval.completed	间隔计时器所有轮次完成

数据格式

{
  "event": "timer.completed",
  "timestamp": "2026-05-10T14:30:00Z",
  "timer_id": "tmr_abc123xyz",
  "title": "限时促销倒计时",
  "type": "event",
  "data": {
    "state": "completed",
    "duration": 1800,
    "actual_duration": 1803,
    "started_at": "2026-05-10T14:00:00Z",
    "completed_at": "2026-05-10T14:30:00Z"
  },
  "signature": "sha256=a8f3b2c..."
}

签名验证

Castimer 使用 HMAC-SHA256 对每个 Webhook 进行签名。签名包含在 X-Castimer-Signature 请求头中。

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return `sha256=${expected}` === signature;
}

重试机制

如果您的端点返回非 2xx 响应或超时，Castimer 将使用指数退避策略重试：

1第 1 次立即（首次）

2第 2 次1 分钟

3第 3 次5 分钟

4第 4 次30 分钟

5第 5 次2 小时

快速开始

创建第一个计时器

1从控制面板获取 API 密钥
2通过 API 创建计时器：

curl -X POST https://castimer.com/api/v1/timers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "我的第一个计时器",
    "type": "countdown",
    "duration": 300
  }'

3使用返回的计时器 ID 来控制它（启动、暂停等）

嵌入组件

1打开嵌入生成器
2可视化配置计时器设置
3复制生成的 iframe 代码并粘贴到您的网站中

设置 Webhooks

1在您的服务器上创建接收 POST 请求的端点
2创建计时器时包含 webhook_url
3验证传入请求的 HMAC-SHA256 签名

curl -X POST https://castimer.com/api/v1/timers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Webhook 计时器",
    "type": "countdown",
    "duration": 60,
    "webhook_url": "https://yourapp.com/webhooks/castimer"
  }'