Back to Details

clockify-tracker

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clockify time tracking (REST API)

Clockify时间追踪（REST API）

Integrate with Clockify using HTTPS requests to 
https://api.clockify.me/api/v1
. Do not assume any local 
clockify_tracker
binary exists.
通过向
https://api.clockify.me/api/v1
发送HTTPS请求与Clockify集成。不要假设本地存在
clockify_tracker
二进制文件。

Environment

环境

VariableRequiredPurpose
CLOCKIFY_API_KEY
YesAPI key from Clockify (Profile → API)
CLOCKIFY_TZ_OFFSET
NoLocal offset from UTC in whole hours (e.g. 
-3
for Argentina). Use when the shell or runtime reports UTC but the user gives local 
HH:mm
.
变量是否必填用途
CLOCKIFY_API_KEY
是来自Clockify的API密钥（个人资料 → API）
CLOCKIFY_TZ_OFFSET
否本地时间与UTC的偏移量（以整小时为单位，例如阿根廷为
-3
）。当Shell或运行时报告UTC时间，但用户提供本地
HH:mm
时间时使用。

Authentication

认证

Every request:
  • Header: 
    X-Api-Key: <CLOCKIFY_API_KEY>
  • Header: 
    Content-Type: application/json
    (for POST bodies)
Never paste the API key into chat; use the environment variable in the tool/shell you run.
每个请求需包含：
  • 请求头：
    X-Api-Key: <CLOCKIFY_API_KEY>
  • 请求头：
    Content-Type: application/json
    （用于POST请求体）
切勿在聊天中粘贴API密钥；请在运行的工具/Shell中使用环境变量。

Endpoints (mirror of former CLI behavior)

端点（与原CLI行为一致）

List workspaces

列出工作区

GET /workspaces
Returns a JSON array of workspaces; each item includes 
id
and 
name
.
GET /workspaces
返回工作区的JSON数组；每个条目包含
id
和
name
。

List projects in a workspace

列出工作区中的项目

GET /workspaces/{workspaceId}/projects?page-size=5000
Returns a JSON array of projects; each item includes 
id
and 
name
.
Flow: If the user might have multiple workspaces, call 
GET /workspaces
first and let them pick (or use the only one). Then list projects for the chosen 
workspaceId
.
GET /workspaces/{workspaceId}/projects?page-size=5000
返回项目的JSON数组；每个条目包含
id
和
name
。
流程： 如果用户可能有多个工作区，先调用
GET /workspaces
，让用户选择（或使用唯一的那个）。然后为选中的
workspaceId
列出项目。

Create a time entry

创建时间条目

POST /workspaces/{workspaceId}/time-entries
JSON body (fields aligned with the previous CLI):
FieldRequiredNotes
start
YesISO 8601 UTC string, e.g. 
2025-03-25T12:00:00.000Z
description
YesWork description
billable
NoBoolean, default 
false
if omitted
end
NoISO 8601 UTC; omit for open-ended entry
projectId
NoClockify project id
POST /workspaces/{workspaceId}/time-entries
JSON请求体（字段与之前的CLI对齐）：
字段是否必填说明
start
是ISO 8601格式的UTC字符串，例如
2025-03-25T12:00:00.000Z
description
是工作描述
billable
否布尔值，省略时默认
false
end
否ISO 8601格式的UTC时间；留空表示未结束的条目
projectId
否Clockify项目ID

Converting user-local 
HH:mm
to UTC 
start
/ 
end

将用户本地
HH:mm
时间转换为UTC格式的
start
/
end

When the user gives local time as 
HH:mm
(and optional 
YYYY-MM-DD
, default today in their locale intent):
  1. Parse date 
    D
    (year, month, day) and time parts 
    hour
    , 
    minute
    .
  2. Let 
    tzOffset
    be the offset in hours from UTC for that local zone: 
    +5
    for UTC+5, 
    -3
    for UTC-3. Use 
    CLOCKIFY_TZ_OFFSET
    if set (integer hours); otherwise infer from the user (e.g. Argentina → 
    -3
    ) or from context.
  3. Build UTC instant: 
    utc_hour = hour - tzOffset
    then normalize into a proper UTC 
    DateTime
    on calendar day 
    D
    (carry overflow across day boundaries as needed), and serialize with 
    Z
    (ISO 8601 UTC).
Examples:
  • Local 
    09:00
    on 
    2025-03-10
    , 
    tzOffset = -3
    → UTC hour 
    9 - (-3) = 12
    → 
    2025-03-10T12:00:00.000Z
    .
  • If the user already provides full ISO strings with 
    T
    and timezone/
    Z
    , pass them through without this conversion.
当用户提供本地时间
HH:mm
（可选
YYYY-MM-DD
，默认是用户所在时区的当天）时：
  1. 解析日期
    D
    （年、月、日）和时间部分
    hour
    、
    minute
    。
  2. 设
    tzOffset
    为本地时区与UTC的小时偏移量：UTC+5为
    +5
    ，UTC-3为
    -3
    。如果已设置
    CLOCKIFY_TZ_OFFSET
    （整数小时）则使用该值；否则从用户信息（例如阿根廷→
    -3
    ）或上下文推断。
  3. 构建UTC时间： 
    utc_hour = hour - tzOffset
    然后将其规范化为日历日
    D
    上的正确UTC
    DateTime
    （必要时跨日边界处理溢出），并以
    Z
    结尾的ISO 8601 UTC格式序列化。
示例：
  • 本地时间
    2025-03-10
    的
    09:00
    ，
    tzOffset = -3
    → UTC小时
    9 - (-3) = 12
    → 
    2025-03-10T12:00:00.000Z
    。
  • 如果用户已提供包含
    T
    及时区/
    Z
    的完整ISO字符串，直接使用无需转换。

Multiple calendar days

跨多个日历日

For ranges ("March 2–6") or discrete lists ("March 23, 24, 25, 26 and 27"), create one POST per day with the same local times and the appropriate date for each 
start
(and 
end
if any). When no year is provided, assume the current calendar year.
对于时间范围（如“3月2日至6日”）或离散日期列表（如“3月23、24、25、26和27日”），每天创建一个POST请求，使用相同的本地时间和对应日期的
start
（如有
end
则同理）。如果未提供年份，默认使用当前日历年度。

Operational flow

操作流程

  1. Confirm 
    CLOCKIFY_API_KEY
    is available to the execution environment.
  2. If workspace is unknown: 
    GET /workspaces
    ; resolve 
    workspaceId
    .
  3. If project is needed: 
    GET /workspaces/{workspaceId}/projects?page-size=5000
    ; resolve 
    projectId
    .
  4. Collect description, start (and optional end), date if needed, and timezone offset if not obvious.
  5. Build JSON and 
    POST /workspaces/{workspaceId}/time-entries
    .
  6. Show the API JSON response or a clear error (status code + body).
  1. 确认执行环境中已配置
    CLOCKIFY_API_KEY
    。
  2. 如果工作区未知：调用
    GET /workspaces
    ；确定
    workspaceId
    。
  3. 如果需要项目：调用
    GET /workspaces/{workspaceId}/projects?page-size=5000
    ；确定
    projectId
    。
  4. 收集描述、开始时间（可选结束时间）、所需日期，以及不明确的时区偏移量。
  5. 构建JSON并发送
    POST /workspaces/{workspaceId}/time-entries
    请求。
  6. 显示API的JSON响应或清晰的错误信息（状态码+响应体）。

Errors

错误处理

On non-success status, read the response body and adjust (invalid id, permissions, malformed body). Official reference: Clockify API documentation.
收到非成功状态码时，读取响应体并调整请求（如无效ID、权限问题、请求体格式错误）。官方参考：Clockify API文档。