API リファレンスガイド

はじめに

API を使い始めるには、API テスト用のツールを使うことをおすすめします。Bruno と Postman は、プログラミングを始める前に API リクエストを試してワークフローを整えるのに最適です。

Bruno をはじめる

まず Bruno をダウンロードしてインストールしてください。Bruno は、プログラミングを始める前に API リクエストを試してワークフローを整えるのに最適なオープンソースツールです。

コレクションを Bruno にインポート — このファイルをダウンロードして Bruno コレクションをインポートすると、すべてのエンドポイントとパラメーターが追加されます。

Bruno に API キーを追加する方法 — 認証は、リクエストヘッダー "apiKey" を追加して API キーで行います。

Postman をはじめる

まず Postman をダウンロードしてインストールしてください。Postman は、プログラミングを始める前に API リクエストを試してワークフローを整えるのに最適なツールです。

コレクションを Postman にインポート — このリンクをコピーして Postman コレクションをインポートすると、すべてのエンドポイントとパラメーターが追加されます。

Postman に API キーを追加する方法 — 認証は、リクエストヘッダー "apiKey" を追加して API キーで行います。

リファレンス

グループの取得

グループオブジェクトの情報を返します。すべてのグループが返されます。

クエリの例

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

レスポンスの例

`1`	`[`
`2`	`{`
`3`	`"id": "d2358de1-3631-428a-a314-f1bdb8ab53a2",`
`4`	`"name": "Auckland",`
`5`	`"deleted": false,`
`6`	`"last_updated": "2024-06-06T21:19:17.622Z",`
`7`	`"created": "2024-06-06T21:19:17.622Z"`
`8`	`},`
`9`	`{`
`10`	`"id": "369b6e85-b90f-4262-9fab-08da623fe3bd",`
`11`	`"name": "Christchurch",`
`12`	`"deleted": false,`
`13`	`"last_updated": "2024-08-12T20:00:36.701Z",`
`14`	`"created": "2024-08-12T20:00:36.701Z"`
`15`	`}`
`16`	`]`

作業の取得

作業オブジェクトの情報を返します。既定ではすべての作業が返されます。

Parameters

Property	Description	Type	Requirement	Default
id	ID を指定するとその作業が返されます。指定しない場合はすべての作業が返されます。	UUID	Optional
completed	completed フィールドが値と一致する作業のみを返します。	Boolean	Optional	false
deleted	deleted フィールドが値と一致する作業のみを返します。	Boolean	Optional	false

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

Property	Description	Type	Requirement	Default
name	ジョブの名前。	String	Required
description	ジョブの説明。	String	Optional
permanent	完了にできるジョブですか？	Boolean	Optional	false
due_date	ジョブの完了期限。	String	permanent == false の場合は必須
cost_code	ジョブの原価コード。	String	Optional
completed	このジョブは完了しましたか？	Boolean	Optional	false
deleted	このジョブは削除されましたか？	Boolean	Optional	false
budget_hours	ジョブに予算化（見積もり）された作業時間。予算なしは null。	Number	Optional	null
priority	優先ジョブですか？優先ジョブはキオスクの先頭に表示されます。	Boolean	Optional	false

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

`1`	`["01d2aa95-1866-4718-8d86-08aa5182f20d", "13074d81-2483-46ea-8bce-b8d761c2580e"]`

レスポンスの例

`1`	`{`
`2`	`"status": 200`
`3`	`}`

作業の更新

作業オブジェクトを更新します。

ボディ

プロパティ	説明	種類	必須/任意	既定
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."}]
}

レスポンスの例

`1`	`{`
`2`	`"status": 200`
`3`	`}`

キオスクの取得

キオスクオブジェクトの情報を返します。すべてのキオスクが返されます。

クエリの例

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

レスポンスの例

`1`	`[`
`2`	`{`
`3`	`"id": "353e1f09-9851-42c8-9b2c-e536ce2cd3bb",`
`4`	`"name": "Back Stairs",`
`5`	`"deleted": false,`
`6`	`"status": "Offline",`
`7`	`"last_updated": "2024-06-10T00:09:43.169Z",`
`8`	`"created": "2024-06-10T00:09:43.169Z"`
`9`	`},`
`10`	`{`
`11`	`"id": "7276d2e1-0fe2-4b64-8d89-1e9b65f4a969",`
`12`	`"name": "Factory Front",`
`13`	`"deleted": false,`
`14`	`"status": "Offline",`
`15`	`"last_updated": "2024-06-10T02:22:51.027Z",`
`16`	`"created": "2024-06-10T02:22:51.027Z"`
`17`	`}`
`18`	`]`

資材の取得

資材オブジェクトの情報を返します。すべての資材が返されます。

クエリの例

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

レスポンスの例

`1`	`[`
`2`	`{`
`3`	`"id": "03b133a9-4546-4e73-89c8-119fb5042fdb",`
`4`	`"name": "M2 Screw",`
`5`	`"cost_code": "0001",`
`6`	`"unit": "none",`
`7`	`"description": "2mm thick screw",`
`8`	`"last_updated": "2024-08-19T21:42:33.021Z",`
`9`	`"created": "2024-08-19T21:42:33.021Z"`
`10`	`},`
`11`	`{`
`12`	`"id": "c127106f-0570-485c-9466-dcf543d9ffbd",`
`13`	`"name": "MDF18",`
`14`	`"cost_code": "ABC123",`
`15`	`"unit": "m²",`
`16`	`"description": "18mm MDF",`
`17`	`"last_updated": "2024-08-05T03:08:12.870Z",`
`18`	`"created": "2024-08-05T03:08:12.870Z"`
`19`	`}`
`20`	`]`

メンバーの取得

メンバーオブジェクトの情報を返します。すべてのメンバーが返されます。

クエリの例

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
      }
    ]
  }
]

`1`	`[`
`2`	`{`
`3`	`"person_id": "a8b3e429-d307-4cg1-bde4-1c2510b8b8ef",`
`4`	`"first_name": "Ada",`
`5`	`"last_name": "Nicodemou",`
`6`	`"days": [`
`7`	`{`
`8`	`"date": "2026-02-20",`
`9`	`"total_hours": 6.82,`
`10`	`"hours_worked": 6.57,`
`11`	`"break_hours": 0.25`
`12`	`},`
`13`	`{`
`14`	`"date": "2026-02-21",`
`15`	`"total_hours": 6.98,`
`16`	`"hours_worked": 6.73,`
`17`	`"break_hours": 0.25`
`18`	`},`
`19`	`{`
`20`	`"date": "2026-02-22",`
`21`	`"total_hours": 7.02,`
`22`	`"hours_worked": 6.77,`
`23`	`"break_hours": 0.25`
`24`	`}`
`25`	`]`
`26`	`},`
`27`	`{`
`28`	`"person_id": "b1d8859f-84cc-49c0-ba94-175c8a1e16c4",`
`29`	`"first_name": "Fred",`
`30`	`"last_name": "Flinstone",`
`31`	`"days": [`
`32`	`{`
`33`	`"date": "2026-02-20",`
`34`	`"total_hours": 8.12,`
`35`	`"hours_worked": 7.95,`
`36`	`"break_hours": 0.17`
`37`	`},`
`38`	`{`
`39`	`"date": "2026-02-21",`
`40`	`"total_hours": 8.13,`
`41`	`"hours_worked": 7.88,`
`42`	`"break_hours": 0.25`
`43`	`},`
`44`	`{`
`45`	`"date": "2026-02-22",`
`46`	`"total_hours": 1.97,`
`47`	`"hours_worked": 1.72,`
`48`	`"break_hours": 0.25`
`49`	`}`
`50`	`]`
`51`	`}`
`52`	`]`

`1`	`[`
`2`	`{`
`3`	`"id": "055fdff9-c264-4c5d-a98e-e98bab581d1a",`
`4`	`"name": "63 Handover Rd",`
`5`	`"description": "",`
`6`	`"cost_code": null,`
`7`	`"due_date": null,`
`8`	`"completed": false,`
`9`	`"permanent": false,`
`10`	`"deleted": false,`
`11`	`"budget_hours": 120,`
`12`	`"priority": false,`
`13`	`"last_updated": "2024-11-01T02:22:56.973Z",`
`14`	`"created": "2024-11-01T02:22:56.973Z",`
`15`	`"groups": [`
`16`	`{`
`17`	`"id": "f8a97df7-85b9-4331-a284-9463c68810b8",`
`18`	`"name": "Mosgiel"`
`19`	`}`
`20`	`],`
`21`	`"people": null`
`22`	`},`
`23`	`]`

`1`	`{`
`2`	`"name": "99 Bamford St",`
`3`	`"description": "Renovating kitchen in 6 apartments",`
`4`	`"permanent": false,`
`5`	`"due_date": "2024-11-30 09:00",`
`6`	`"cost_code": "123456",`
`7`	`"budget_hours": 120,`
`8`	`"priority": false,`
`9`	`"completed": false,`
`10`	`"deleted": false`
`11`	`}`

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

`1`	`[`
`2`	`{`
`3`	`"id": "b6cc9e4b-cccb-4206-92a0-a387ff121c69",`
`4`	`"first_name": "Aspen",`
`5`	`"last_name": "Brewster",`
`6`	`"email": "[email protected]",`
`7`	`"pin_enabled": false,`
`8`	`"pin": null,`
`9`	`"permission": 3,`
`10`	`"last_updated": "2024-09-09T02:44:06.604Z",`
`11`	`"created": "2024-09-09T02:44:06.604Z"`
`12`	`},`
`13`	`{`
`14`	`"id": "2d68300b-f34e-45f9-a1a5-fdf0daa59729",`
`15`	`"first_name": "Bryne",`
`16`	`"last_name": "Lynton",`
`17`	`"email": null,`
`18`	`"pin_enabled": false,`
`19`	`"pin": null,`
`20`	`"permission": 3,`
`21`	`"last_updated": "2024-09-09T02:44:06.604Z",`
`22`	`"created": "2024-09-09T02:44:06.604Z"`
`23`	`}`
`24`	`]`

API リファレンスガイド

はじめに

Bruno をはじめる

Postman をはじめる

リファレンス

グループの取得

クエリの例

レスポンスの例

作業の取得

Parameters

Example Query

レスポンスの例

作業の追加

Body

Example Query

レスポンスの例

作業の削除

ボディ

Example Query

レスポンスの例

作業の更新

ボディ

Example Query

レスポンスの例

キオスクの取得

クエリの例

レスポンスの例

資材の取得

クエリの例

レスポンスの例

メンバーの取得

クエリの例

レスポンスの例

シフトの取得

パラメーター

Example Query

レスポンスの例

いつでも喜んでお手伝いします。 お気軽にお問い合わせください。当社の勤怠管理システムがお客様に合うよう、できる限りのことをいたします。

いつでも喜んでお手伝いします。
お気軽にお問い合わせください。当社の勤怠管理システムがお客様に合うよう、できる限りのことをいたします。