API Developer BerKarya

GET/ping

Identitas kunci: perusahaan mana, izin apa.

Scope: tidak ada

Panggil ini pertama kali. Membedakan "kunci salah" (401) dari "izin kurang" (403) sebelum menebak-nebak.

{
  "ok": true,
  "key": { "id": "clk…", "name": "Livioo produksi", "platform": false },
  "scopes": ["org:read", "employees:read", "attendance:read"],
  "company": { "id": "clc…", "name": "PT Contoh", "slug": "pt-contoh", "timezone": "Asia/Jakarta" },
  "serverTime": "2026-10-03T01:00:00.000Z"
}

GET/org

Kantor, jabatan, shift, dan hari libur sekaligus.

Scope: org:read

GET/employees

Daftar karyawan, berhalaman.

Scope: employees:read · Parameter: status, updatedSince, limit, cursor

{
  "ok": true,
  "data": [
    {
      "id": "cle…",
      "externalId": "LIV-882",
      "nip": "0012",
      "name": "Siti Rahma",
      "email": null,
      "phone": "+6281234567890",
      "area": null,
      "status": "active",
      "joinDate": "2026-03-01",
      "managerId": null,
      "position": { "id": "clp…", "name": "Front Office" },
      "office": { "id": "clo…", "name": "Kantor Pusat" },
      "createdAt": "2026-03-01T02:00:00.000Z",
      "updatedAt": "2026-09-20T08:12:00.000Z"
    }
  ],
  "nextCursor": null
}

POST/employees

Buat atau perbarui karyawan (upsert lewat externalId).

Scope: employees:write

Dijalankan dua kali menghasilkan satu karyawan. Field yang tidak dikirim tidak disentuh; null eksplisit mengosongkan.

curl -s -X POST https://berkarya.app/api/partner/v1/employees \
  -H "Authorization: Bearer $BERKARYA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "LIV-882",
  "name": "Siti Rahma",
  "phone": "+6281234567890",
  "position": "Front Office",
  "joinDate": "2026-03-01"
}'

GET/employees/{id}

Satu karyawan. {id} boleh id BerKarya atau externalId Anda.

Scope: employees:read

GET/attendance

Catatan kehadiran per tanggal kerja.

Scope: attendance:read · Parameter: from, to, employeeId, updatedSince, limit, cursor

Koordinat mentah dan foto tidak dikirim: yang ada jarak ke kantor dan hasSelfie.

{
  "ok": true,
  "data": [
    {
      "id": "cla…",
      "externalId": null,
      "employeeId": "cle…",
      "date": "2026-10-03",
      "checkIn": {
        "at": "2026-10-03T01:04:00.000Z",
        "status": "LATE",
        "lateMin": 4,
        "officeId": "clo…",
        "distanceM": 12,
        "accuracyM": 8,
        "hasSelfie": true,
        "mocked": false
      },
      "checkOut": null,
      "workedMin": null,
      "note": null,
      "flags": [],
      "reviewState": "AUTO_OK",
      "reviewedAt": null,
      "reviewNote": null,
      "updatedAt": "2026-10-03T01:04:00.000Z"
    }
  ],
  "nextCursor": null
}

GET/roster

Jadwal shift yang sudah ditetapkan.

Scope: roster:read · Parameter: from (wajib), to (wajib), employeeId

GET/requests

Pengajuan cuti, sakit, izin, lembur, reimburse beserta keputusannya.

Scope: requests:read · Parameter: status, type, employeeId, updatedSince, limit, cursor

GET/payroll

Slip gaji yang SUDAH diterbitkan. Draf tidak pernah ikut.

Scope: payroll:read · Parameter: period (YYYY-MM), employeeId

gross, deductions, net dikirim sebagai string desimal.

GET/points

Poin karyawan.

Scope: points:read · Parameter: employeeId

POST/points

Beri poin kepada karyawan (idempoten).

Scope: points:write

Kirim ulang dengan idempotencyKey yang sama: poin tidak ditambah dua kali, balasannya baris yang sama dengan "duplicate": true.

curl -s -X POST https://berkarya.app/api/partner/v1/points \
  -H "Authorization: Bearer $BERKARYA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "employee": "LIV-882",
  "points": 25,
  "reason": "Menyelesaikan misi Berkomunitas",
  "idempotencyKey": "berkomunitas-misi-9912"
}'

GET/webhooks

Daftar alamat webhook milik perusahaan ini.

Scope: webhooks:manage

POST/webhooks

Daftarkan alamat webhook. Rahasia penanda tangan ditampilkan sekali.

Scope: webhooks:manage · Parameter: url (https), events (kosong = semua, termasuk event baru), description

Hanya https. Alamat lokal dan jaringan privat ditolak. Simpan secret dari balasan; tidak bisa dibaca lagi.

curl -s -X POST https://berkarya.app/api/partner/v1/webhooks \
  -H "Authorization: Bearer $BERKARYA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://contoh.id/hooks/berkarya",
  "events": ["attendance.punched", "request.decided"],
  "description": "Sinkron absensi ke ERP"
}'

PATCH/webhooks/{id}

Nyalakan/matikan alamat atau ubah langganan event.

Scope: webhooks:manage · Parameter: active, events, description

DELETE/webhooks/{id}

Cabut alamat webhook.

Scope: webhooks:manage

GET/companies

Daftar perusahaan. Kunci platform saja.

Scope: companies:admin

POST/companies

Buat perusahaan baru. Kunci platform saja.

Scope: companies:admin