API 参考指南

入门

开始使用 API 时，我们建议使用 API 测试工具。Bruno 和 Postman 都非常适合在开始编程之前测试 API 请求并理顺工作流程。

Bruno 入门

首先，您需要下载并安装 Bruno。Bruno 是一款出色的开源工具，可在开始编程之前测试 API 请求并理顺工作流程。

下载此文件导入我们的 Bruno 集合，即可添加我们所有的端点和参数。
将集合导入 Bruno
身份验证通过 API 密钥完成，方法是添加请求头 "apiKey"。
如何在 Bruno 中添加 API 密钥
API 密钥可在以下位置生成： 管理后台 设置 API

Postman 入门

首先，您需要下载并安装 Postman。Postman 是一款出色的工具，可在开始编程之前测试 API 请求并理顺工作流程。

复制此链接导入我们的 Postman 集合，即可添加我们所有的端点和参数。
将集合导入 Postman
身份验证通过 API 密钥完成，方法是添加请求头 "apiKey"。
如何在 Postman 中添加 API 密钥
API 密钥可在以下位置生成： 管理后台 设置 API

参考

获取群组

返回群组对象的信息。将返回所有群组。

示例查询

GET https://timeclock.kiwi/api/groups

响应示例

[
    {
        "id": "d2358de1-3631-428a-a314-f1bdb8ab53a2",
        "name": "Auckland",
        "deleted": false,
        "last_updated": "2024-06-06T21:19:17.622Z",
        "created": "2024-06-06T21:19:17.622Z"
    },
    {
        "id": "369b6e85-b90f-4262-9fab-08da623fe3bd",
        "name": "Christchurch",
        "deleted": false,
        "last_updated": "2024-08-12T20:00:36.701Z",
        "created": "2024-08-12T20:00:36.701Z"
    }
]

获取工单

返回工单对象的信息。默认返回所有工单。

Parameters

PropertyDescriptionTypeRequirementDefault
id提供 ID 将返回该特定工单。不提供此值将返回所有工单。UUIDOptional
completed仅返回 completed 字段与该值匹配的工单。BooleanOptionalfalse
deleted仅返回 deleted 字段与该值匹配的工单。BooleanOptionalfalse

Example Query

GET https://timeclock.kiwi/api/jobs?id=01d2aa95-1866-4718-8d86-08aa5182f20d&completed=true&deleted=true

响应示例

[
    {
        "id": "055fdff9-c264-4c5d-a98e-e98bab581d1a",
        "name": "63 Handover Rd",
        "description": "",
        "cost_code": null,
        "due_date": null,
        "completed": false,
        "permanent": false,
        "deleted": false,
        "budget_hours": 120,
        "priority": false,
        "last_updated": "2024-11-01T02:22:56.973Z",
        "created": "2024-11-01T02:22:56.973Z",
        "groups": [
            {
                "id": "f8a97df7-85b9-4331-a284-9463c68810b8",
                "name": "Mosgiel"
            }
        ],
        "people": null
    },
]

添加工单

添加一个工单对象。

Body

PropertyDescriptionTypeRequirementDefault
name工作的名称。StringRequired
description工作的描述。StringOptional
permanent这是可以标记为已完成的工作吗？BooleanOptionalfalse
due_date工作应完成的日期。Stringpermanent == false 时必填
cost_code工作的成本代码。StringOptional
completed此工作是否已完成？BooleanOptionalfalse
deleted此工作是否已删除？BooleanOptionalfalse
budget_hours为工作预算（报价）的人工工时。null 表示无预算。NumberOptionalnull
priority这是优先工作吗？优先工作在终端上最先显示。BooleanOptionalfalse

Example Query

POST https://timeclock.kiwi/api/jobs
{
    "name": "99 Bamford St",
    "description": "Renovating kitchen in 6 apartments",
    "permanent": false,
    "due_date": "2024-11-30 09:00",
    "cost_code": "123456",
    "budget_hours": 120,
    "priority": false,
    "completed": false,
    "deleted": false
}

响应示例

{
    "name": "99 Bamford St",
    "description": "Renovating kitchen in 6 apartments",
    "permanent": false,
    "due_date": "2024-11-30 09:00",
    "cost_code": "123456",
    "budget_hours": 120,
    "priority": false,
    "completed": false,
    "deleted": false,
    "id": "b6dac400-5097-4763-8021-137222cb1ad4"
}

删除工单

删除列出的工单对象。

请求体

属性描述类型是否必填默认
UUID要删除的所有工单的 UUID 列表。UUID必填

Example Query

DELETE https://timeclock.kiwi/api/jobs
["01d2aa95-1866-4718-8d86-08aa5182f20d", "13074d81-2483-46ea-8bce-b8d761c2580e"]

响应示例

{
    "status": 200
}

更新工单

更新一个工单对象。

请求体

属性描述类型是否必填默认
id您要修改的工单的 UUID。UUID必填
name工单的名称。String必填
description工单的描述。String可选
permanent此工单是否可以标记为已完成？Boolean可选false
due_date工单应完成的日期。String当 permanent == false 时必填
cost_code工单的成本代码。String可选
completed此工单是否已完成？Boolean可选false
deleted此工单是否已删除？Boolean可选false
budget_hours为工作预算（报价）的人工工时。null 表示无预算。Number可选null
priority这是优先工作吗？优先工作在终端上最先显示。Boolean可选false
groups此工单所属的所有群组的 UUID。UUID可选
people可以看到此工单的所有人员的 UUID。UUID可选
materials此工单中使用过的所有材料列表。材料必须由某个人使用过。UUID可选
notes为工单添加一条新备注。UUID可选

Example Query

PUT https://timeclock.kiwi/api/jobs
{
    "id": "dfb37a1e-692e-44d5-bedf-309b44b9e136",
    "name": "99 Bamford St",
    "description": "Renovating kitchen in 6 apartments",
    "permanent": true,
    "due_date": "2024-11-30 09:00",
    "cost_code": "123456",
    "completed": true,
    "deleted": true,
    "groups": ["d2358de1-3631-428a-a314-f1bdb8ab53a2","d2358de1-3631-428a-a314-f1bdb8ab53a3"],
    "people": ["d2358de1-3631-428a-a314-f1bdb8ab53a2","d2358de1-3631-428a-a314-f1bdb8ab53a3"],
    "materials": [{ "id": "03b133a9-4546-4e73-89c8-119fb5042fdb", "person_id": "017a1008-de92-4df2-a533-4e17b643123e", "quantity": 5}],
    "notes": [{ "person_id": "017a1008-de92-4df2-a533-4e17b643123e", "note": "Concrete has cat paw prints on it."}]
}

响应示例

{
    "status": 200
}

获取终端

返回终端对象的信息。将返回所有终端。

示例查询

GET https://timeclock.kiwi/api/kiosks

响应示例

[
    {
        "id": "353e1f09-9851-42c8-9b2c-e536ce2cd3bb",
        "name": "Back Stairs",
        "deleted": false,
        "status": "Offline",
        "last_updated": "2024-06-10T00:09:43.169Z",
        "created": "2024-06-10T00:09:43.169Z"
    },
    {
        "id": "7276d2e1-0fe2-4b64-8d89-1e9b65f4a969",
        "name": "Factory Front",
        "deleted": false,
        "status": "Offline",
        "last_updated": "2024-06-10T02:22:51.027Z",
        "created": "2024-06-10T02:22:51.027Z"
    }
]

获取材料

返回材料对象的信息。将返回所有材料。

示例查询

GET https://timeclock.kiwi/api/materials

响应示例

[
    {
        "id": "03b133a9-4546-4e73-89c8-119fb5042fdb",
        "name": "M2 Screw",
        "cost_code": "0001",
        "unit": "none",
        "description": "2mm thick screw",
        "last_updated": "2024-08-19T21:42:33.021Z",
        "created": "2024-08-19T21:42:33.021Z"
    },
    {
        "id": "c127106f-0570-485c-9466-dcf543d9ffbd",
        "name": "MDF18",
        "cost_code": "ABC123",
        "unit": "m²",
        "description": "18mm MDF",
        "last_updated": "2024-08-05T03:08:12.870Z",
        "created": "2024-08-05T03:08:12.870Z"
    }
]

获取人员

返回人员对象的信息。将返回所有人员。

示例查询

GET https://timeclock.kiwi/api/people

响应示例

[
    {
        "id": "b6cc9e4b-cccb-4206-92a0-a387ff121c69",
        "first_name": "Aspen",
        "last_name": "Brewster",
        "email": "[email protected]",
        "pin_enabled": false,
        "pin": null,
        "permission": 3,
        "last_updated": "2024-09-09T02:44:06.604Z",
        "created": "2024-09-09T02:44:06.604Z"
    },
    {
        "id": "2d68300b-f34e-45f9-a1a5-fdf0daa59729",
        "first_name": "Bryne",
        "last_name": "Lynton",
        "email": null,
        "pin_enabled": false,
        "pin": null,
        "permission": 3,
        "last_updated": "2024-09-09T02:44:06.604Z",
        "created": "2024-09-09T02:44:06.604Z"
    }
]

获取班次

返回班次对象的信息。

参数

属性描述类型是否必填默认
start-date要返回的班次的第一天（含）。ISO 8601 日期 (YYYY-MM-DD)必填
end-date要返回的班次的最后一天（含）。ISO 8601 日期 (YYYY-MM-DD)必填
group-id仅返回属于此群组的人员的班次。UUID可选
person-id仅返回此人的班次。UUID可选

Example Query

GET https://timeclock.kiwi/api/shifts?start-date=2026-02-20&end-date=2026-02-27&group-id=752d68b5-5d57-4727-8c1c-85383b76fecf&person-id=a8b3e429-d307-4cd1-bde4-1c2510b6b8ef

响应示例

[
  {
    "person_id": "a8b3e429-d307-4cg1-bde4-1c2510b8b8ef",
    "first_name": "Ada",
    "last_name": "Nicodemou",
    "days": [
      {
        "date": "2026-02-20",
        "total_hours": 6.82,
        "hours_worked": 6.57,
        "break_hours": 0.25
      },
      {
        "date": "2026-02-21",
        "total_hours": 6.98,
        "hours_worked": 6.73,
        "break_hours": 0.25
      },
      {
        "date": "2026-02-22",
        "total_hours": 7.02,
        "hours_worked": 6.77,
        "break_hours": 0.25
      }
    ]
  },
  {
    "person_id": "b1d8859f-84cc-49c0-ba94-175c8a1e16c4",
    "first_name": "Fred",
    "last_name": "Flinstone",
    "days": [
      {
        "date": "2026-02-20",
        "total_hours": 8.12,
        "hours_worked": 7.95,
        "break_hours": 0.17
      },
      {
        "date": "2026-02-21",
        "total_hours": 8.13,
        "hours_worked": 7.88,
        "break_hours": 0.25
      },
      {
        "date": "2026-02-22",
        "total_hours": 1.97,
        "hours_worked": 1.72,
        "break_hours": 0.25
      }
    ]
  }
]

我们随时乐意为您提供帮助。
欢迎联系我们，我们会尽力让我们的员工考勤系统满足您的需求。