Panduan Referensi API

Memulai

Untuk mulai menggunakan API, kami sarankan menggunakan alat untuk menguji API. Bruno dan Postman sama-sama bagus untuk mencoba permintaan API dan menyempurnakan alur kerja Anda sebelum mulai memprogram.

Memulai dengan Bruno

Untuk memulai, Anda perlu mengunduh dan menginstal Bruno. Bruno adalah alat sumber terbuka yang bagus untuk mencoba permintaan API dan menyempurnakan alur kerja Anda sebelum mulai memprogram.

Impor Koleksi Bruno kami dengan mengunduh file ini untuk menambahkan semua endpoint dan parameter kami.
Impor koleksi ke Bruno
Autentikasi dilakukan melalui kunci API dengan menambahkan header permintaan "apiKey".
Cara menambahkan kunci API ke Bruno
Kunci API dapat dibuat di Portal Pengaturan API

Memulai dengan Postman

Untuk memulai, Anda perlu mengunduh dan menginstal Postman. Postman adalah alat yang bagus untuk mencoba permintaan API dan menyempurnakan alur kerja Anda sebelum mulai memprogram.

Impor Koleksi Postman kami dengan menyalin tautan ini untuk menambahkan semua endpoint dan parameter kami.
Impor koleksi ke Postman
Autentikasi dilakukan melalui kunci API dengan menambahkan header permintaan "apiKey".
Cara menambahkan kunci API ke Postman
Kunci API dapat dibuat di Portal Pengaturan API

Referensi

Backup Get

Memeriksa kunci API dan mengembalikan perusahaan pemiliknya, beserta jenis catatan yang dapat Anda cadangkan dengan Backup Records Get.

Contoh Kueri

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

Contoh respons

{
    "api_version": 1,
    "company": {
        "id": "8c1f5a2e-4b7d-4e19-9a3c-2f6d8e0b1a47",
        "name": "Harbour Joinery",
        "country": "NZ"
    },
    "entities": ["people", "groups", "kiosks", "jobs", "tasks", "shifts", "scheduled_shifts", "time_off", "visits"]
}

Backup Records Get

Mengembalikan catatan Anda per halaman, dimulai dari perubahan terlama, sehingga Anda dapat menyimpan salinan sendiri.

Terus minta dengan next_cursor sampai has_more bernilai false, lalu simpan next_cursor terakhir. Lain kali, kirimkan untuk hanya mendapatkan yang berubah sejak saat itu. Cursor halaman terakhir mengulang perubahan dua jam sebelumnya, jadi perbarui catatan yang sudah Anda miliki alih-alih menambahkannya lagi.

Parameter

PropertiDeskripsiJenisPersyaratanDefault
entityJenis catatan yang dikembalikan: salah satu jenis catatan di bawah. Bagian dari path, misalnya /api/backup/shifts.StringWajib
cursornext_cursor dari halaman sebelumnya. Kosongkan untuk mulai dari awal.StringOpsional
limitBerapa banyak catatan yang dikembalikan dalam satu halaman, dari 1 sampai 1000.IntegerOpsional500

Jenis catatan

Jenis catatanDeskripsi
peopleSemua orang di akun, termasuk orang yang telah dihapus. Masing-masing memiliki peran dan ID grupnya.
groupsGrup dan lokasi, beserta alamat, radius GPS, dan zona waktunya.
kiosksKios dan lokasi masing-masing.
jobsSemua pekerjaan, termasuk yang sudah selesai dan dihapus.
tasksSemua tugas.
shiftsShift yang dikerjakan beserta waktu mulai dan selesai, total jam, jam kerja, dan jam istirahat, serta setiap kejadian dalam shift beserta pekerjaan, tugas, lokasi, dan posisi GPS-nya.
scheduled_shiftsShift di jadwal yang diterbitkan. Shift yang sudah tidak ada di jadwal yang diterbitkan dikembalikan dengan on_published_roster bernilai false.
time_offPermintaan cuti dan statusnya.
visitsTamu yang melakukan registrasi masuk dan keluar di kios registrasi lokasi.

Contoh Kueri

GET https://timeclock.kiwi/api/backup/shifts?limit=500&cursor=eyJ0IjoiMjAyNi0xMS0xMSAxNDo0MjowMi4xMjM0NTYiLCJpZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsInIiOjEyMH0

Contoh respons

{
    "data": [
        {
            "id": "3f2b8c41-9d6e-4a57-b1c0-7e5d2a9f4c18",
            "person_id": "b6cc9e4b-cccb-4206-92a0-a387ff121c69",
            "start_time": "2026-11-10T19:00:00.000Z",
            "end_time": "2026-11-11T03:30:00.000Z",
            "timezone": "Pacific/Auckland",
            "ongoing": false,
            "deleted": false,
            "total_hours": 8.5,
            "hours_worked": 8,
            "break_hours": 0.5,
            "job_ids": ["055fdff9-c264-4c5d-a98e-e98bab581d1a"],
            "events": [
                {
                    "type": "clock_in",
                    "time": "2026-11-10T19:00:00.000Z",
                    "recorded_time": "2026-11-10T19:02:41.512Z",
                    "edited": true,
                    "timezone": "Pacific/Auckland",
                    "kiosk_id": null,
                    "location_id": "cd4ba9ad-ec05-4f60-84d6-d9f6cc558b67",
                    "location_edited": false,
                    "latitude": -36.88181,
                    "longitude": 174.62938,
                    "gps_accuracy_metres": 12,
                    "gps_mocked": false,
                    "job_name": "63 Handover Rd",
                    "task_name": null,
                    "break_minutes": null,
                    "paid": null,
                    "notes": null,
                    "deleted": false
                },
                {
                    "type": "break_start",
                    "time": "2026-11-10T23:00:00.000Z",
                    "...": "..."
                }
            ],
            "created": "2026-11-10T19:02:41.512Z",
            "last_updated": "2026-11-11T03:30:12.044Z"
        }
    ],
    "next_cursor": "eyJ0IjoiMjAyNi0xMS0xMSAxNjozMDoxMi4wNDQwMDAiLCJpZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsInIiOjEyMH0",
    "has_more": false
}

Groups Get

Mengembalikan informasi tentang objek grup. Akan mengembalikan semua grup.

Contoh Kueri

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

Contoh respons

[
    {
        "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"
    }
]

Jobs Get

Mengembalikan informasi tentang objek pekerjaan. Secara default akan mengembalikan semua pekerjaan.

Parameters

PropertyDescriptionTypeRequirementDefault
idMemberikan ID akan mengembalikan pekerjaan tertentu. Jika nilai ini tidak diberikan, semua pekerjaan akan dikembalikan.UUIDOptional
completedHanya kembalikan pekerjaan yang kolom completed-nya cocok dengan nilai ini.BooleanOptionalfalse
deletedHanya kembalikan pekerjaan yang kolom deleted-nya cocok dengan nilai ini.BooleanOptionalfalse

Example Query

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

Contoh respons

[
    {
        "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
    },
]

Jobs Add

Menambahkan objek pekerjaan.

Body

PropertyDescriptionTypeRequirementDefault
nameNama pekerjaan.StringRequired
descriptionDeskripsi pekerjaan.StringOptional
permanentApakah pekerjaan ini dapat ditandai selesai?BooleanOptionalfalse
due_dateTanggal tenggat penyelesaian pekerjaan.StringWajib jika permanent == false
cost_codeKode biaya untuk pekerjaan.StringOptional
completedApakah pekerjaan ini sudah selesai?BooleanOptionalfalse
deletedApakah pekerjaan ini sudah dihapus?BooleanOptionalfalse
budget_hoursJam kerja yang dianggarkan (ditawarkan) untuk pekerjaan. null jika tanpa anggaran.NumberOptionalnull
priorityApakah ini pekerjaan prioritas? Pekerjaan prioritas ditampilkan pertama di kios.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
}

Contoh respons

{
    "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"
}

Jobs Delete

Menghapus objek pekerjaan yang tercantum.

Body

PropertiDeskripsiJenisPersyaratanDefault
UUIDDaftar UUID semua pekerjaan yang akan dihapus.UUIDWajib

Example Query

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

Contoh respons

{
    "status": 200
}

Jobs Update

Memperbarui objek pekerjaan.

Body

PropertiDeskripsiJenisPersyaratanDefault
idUUID pekerjaan yang ingin Anda ubah.UUIDWajib
nameNama pekerjaan.StringWajib
descriptionDeskripsi pekerjaan.StringOpsional
permanentApakah pekerjaan ini dapat ditandai selesai?BooleanOpsionalfalse
due_dateTanggal tenggat penyelesaian pekerjaan.StringWajib jika permanent == false
cost_codeKode biaya untuk pekerjaan.StringOpsional
completedApakah pekerjaan ini sudah selesai?BooleanOpsionalfalse
deletedApakah pekerjaan ini sudah dihapus?BooleanOpsionalfalse
budget_hoursJam kerja yang dianggarkan (ditawarkan) untuk pekerjaan. null jika tanpa anggaran.NumberOpsionalnull
priorityApakah ini pekerjaan prioritas? Pekerjaan prioritas ditampilkan pertama di kios.BooleanOpsionalfalse
groupsUUID semua grup tempat pekerjaan ini berada.UUIDOpsional
peopleUUID semua orang yang dapat melihat pekerjaan ini.UUIDOpsional
materialsDaftar semua material yang telah digunakan untuk pekerjaan ini. Material harus sudah digunakan oleh seseorang.UUIDOpsional
notesMenambahkan catatan baru ke pekerjaan.UUIDOpsional

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

Contoh respons

{
    "status": 200
}

Kiosks Get

Mengembalikan informasi tentang objek kios. Akan mengembalikan semua kios.

Contoh Kueri

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

Contoh respons

[
    {
        "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"
    }
]

Materials Get

Mengembalikan informasi tentang objek material. Akan mengembalikan semua material.

Contoh Kueri

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

Contoh respons

[
    {
        "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"
    }
]

People Get

Mengembalikan informasi tentang objek orang. Akan mengembalikan semua orang.

Contoh Kueri

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

Contoh respons

[
    {
        "id": "b6cc9e4b-cccb-4206-92a0-a387ff121c69",
        "first_name": "Aspen",
        "last_name": "Brewster",
        "email": "[email protected]",
        "pin_enabled": false,
        "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,
        "permission": 3,
        "last_updated": "2024-09-09T02:44:06.604Z",
        "created": "2024-09-09T02:44:06.604Z"
    }
]

Shifts Get

Mengembalikan informasi tentang objek shift.

Parameter

PropertiDeskripsiJenisPersyaratanDefault
start-dateHari pertama shift yang dikembalikan (inklusif).Tanggal ISO 8601 (YYYY-MM-DD)Wajib
end-dateHari terakhir shift yang dikembalikan (inklusif).Tanggal ISO 8601 (YYYY-MM-DD)Wajib
group-idHanya kembalikan shift untuk orang yang termasuk dalam grup ini.UUIDOpsional
person-idHanya kembalikan shift untuk orang ini.UUIDOpsional

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

Contoh respons

[
  {
    "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
      }
    ]
  }
]

Kami selalu senang membantu.
Hubungi kami dan kami akan berusaha sebaik mungkin agar sistem absensi karyawan kami sesuai untuk Anda.