​

Sinkronisasi absen susulan otomatis: perbarui status kehadiran DingTalk secara real-time setelah persetujuan

​

Ikhtisar

​

Latar belakang

​

Manfaat utama

• Sinkronisasi lintas sistem otomatis: Setelah permintaan disetujui di sistem cuti dan absensi internal, sistem memanggil API DingTalk untuk menyinkronkan data absen susulan. Karyawan tidak perlu melakukan tindakan apa pun.
• Pemetaan status yang akurat: Berdasarkan hasil persetujuan (disetujui atau ditarik), sistem menetapkan status kehadiran DingTalk menjadi “Absen susulan disetujui” atau memulihkan status absen semula.
• Pencocokan jadwal cerdas: Sebelum sinkronisasi, sistem mengambil jadwal waktu absen karyawan pada tanggal terkait. Dengan begitu, data absen susulan terhubung ke waktu yang tepat.
• Alur persetujuan terpisah: Sinkronisasi tidak membuat Formulir persetujuan absen susulan di DingTalk. Hal ini mencegah persetujuan ganda dan menjaga Proses persetujuan internal Anda tetap independen.

​

Kasus penggunaan

• Sinkronisasi sistem OA internal: Setelah karyawan mengajukan permintaan absen susulan di sistem OA internal dan permintaan disetujui, hasilnya otomatis tersinkron ke DingTalk Attendance.
• Platform cuti dan absensi pihak ketiga: Saat Anda menggunakan sistem cuti dan absensi pihak ketiga, hasil persetujuan tersinkron ke aplikasi DingTalk Attendance secara real-time.
• Pemrosesan absen susulan massal: Saat HR mengimpor catatan absen susulan historis secara massal, catatan tersebut otomatis tersinkron ke DingTalk Attendance.
• Sinkronisasi penarikan: Setelah karyawan menarik permintaan absen susulan di sistem internal, status absen semula di DingTalk Attendance otomatis dipulihkan.

​

Skenario bisnis umum

​

Skenario 1: Sinkronkan ke DingTalk setelah permintaan absen susulan disetujui di sistem OA internal

​

Kendala

​

Validasi nilai

• Alur kerja otomatis

• Keunggulan utama
  • Pemicu sepenuhnya otomatis: Setelah persetujuan di sistem OA internal, sistem memanggil API DingTalk untuk menyinkronkan data absen susulan. Karyawan tidak perlu melakukan apa pun.
  • Pencocokan akurat: Sebelum sinkronisasi, sistem mengambil jadwal waktu absen karyawan pada tanggal terkait. Dengan begitu, data absen susulan terhubung ke waktu yang tepat.
  • Berlaku seketika: Data absen susulan langsung berlaku setelah tersinkron. Status kehadiran DingTalk berubah dari “Absen terlewat” menjadi “Absen susulan disetujui”.
  • Alur persetujuan terpisah: Sinkronisasi tidak membuat Formulir persetujuan absen susulan di DingTalk. Hal ini mencegah persetujuan ganda dan menjaga alur persetujuan internal Anda tetap independen.

​

Skenario 2: Pulihkan status absen semula setelah permintaan absen susulan ditarik

​

Kendala

​

Validasi nilai

• Alur kerja otomatis
• Keunggulan utama
  • Pemulihan status otomatis: Setelah permintaan absen susulan ditarik di sistem internal, sistem memanggil API DingTalk untuk memulihkan status absen semula.
  • Konsistensi data: Status kehadiran DingTalk selalu sesuai dengan hasil persetujuan di sistem OA internal.
  • Jejak audit: Setiap sinkronisasi atau penarikan mencatat operator, stempel waktu, dan ID Formulir persetujuan untuk memenuhi persyaratan kepatuhan.
  • Error yang dapat dilacak: Saat sinkronisasi gagal, sistem mencatat informasi error secara detail untuk membantu Anda menelusuri dan memperbaiki masalah.

​

Panduan implementasi

​

Arsitektur teknis

• Lapisan autentikasi: Menggunakan Client ID dan Client Secret untuk mendapatkan access_token, yang mengamankan panggilan API.
• Lapisan pengelolaan grup absensi: Menyediakan dukungan API lengkap untuk membuat, mengambil, memperbarui, dan menghapus grup absensi. Mendukung grup absensi shift tetap maupun grup absensi berbasis shift.
• Lapisan pengelolaan shift: Menyediakan API untuk membuat dan mengambil shift. Shift merupakan sumber daya prasyarat untuk grup absensi.
• Lapisan penanganan error: Sistem kode error yang lengkap membantu Anda menemukan dan menyelesaikan masalah dengan cepat.

​

Prasyarat

• Penyiapan aplikasi: Buat dan konfigurasikan Aplikasi internal. Untuk detailnya, lihat Membuat dan mengonfigurasi aplikasi.
• Izin: Miliki izin Admin Organisasi atau Sub Admin DingTalk, lalu ajukan izin API berikut:
  • qyapi_attendance_group_manage (izin pengelolaan grup absensi)
  • qyapi_attendance_group_read (izin baca grup absensi)
• Lingkungan pengembangan: Instal lingkungan pengembangan Java (JDK 1.6 atau lebih baru) dan build tool Maven.
• SDK: Unduh SDK Sisi server DingTalk. Untuk detailnya, lihat unduhan SDK Sisi server. SDK mendukung Java, Python, Go, dan bahasa lainnya.

​

Implementasi kode

1. Saat karyawan mengajukan permintaan absen susulan di sistem absensi internal, panggil Server API Mengambil jadwal pengguna dengan tanggal yang dipilih karyawan. API ini mengembalikan jadwal waktu absen karyawan pada tanggal tersebut.
2. Karyawan mengajukan Formulir persetujuan absen susulan di sistem cuti dan absensi internal. Tindakan berikutnya bergantung pada hasil persetujuan.
   • Jika permintaan disetujui, panggil Server API Notifikasi persetujuan absen susulan. Data absen susulan yang diajukan tersinkron ke aplikasi DingTalk Attendance, dan status kehadiran berubah dari “Absen terlewat” menjadi “Absen susulan disetujui”.

​

Catatan

• Jika karyawan menarik permintaan absen susulan, panggil Server API Notifikasi penarikan persetujuan. API ini menarik permintaan absen susulan yang telah tersinkron ke DingTalk dan memulihkan status kehadiran ke status absen sebelum perubahan.

​

Langkah implementasi

​

Langkah 1: Dapatkan kredensial aplikasi

1. Masuk ke DingTalk Developer Console.
2. Pilih aplikasi target untuk membuka halaman detailnya.
3. Klik Basic Information > Credentials and Basic Information.
4. Catat Client ID dan Client Secret aplikasi.

​

Catatan

​

Langkah 2: Tambahkan izin API

1. Di halaman detail aplikasi, klik Kelola izin.
2. Di kotak pencarian izin, masukkan identifier izin berikut lalu ajukan:
   • qyapi_attendance_group_manage (izin pengelolaan grup absensi): Digunakan untuk menyinkronkan dan menarik data absen susulan.
   • qyapi_attendance_group_read (izin baca grup absensi): Digunakan untuk mengambil jadwal karyawan.

​

Langkah 3: Dapatkan Kredensial akses (access_token)

public void getAccessToken() throws ApiException {
  DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/gettoken");
  OapiGettokenRequest req = new OapiGettokenRequest();
  req.setAppkey("dingxxxxxxxxxhgn");
  req.setAppsecret("9G_xxxxxxxxxxxxxxx1JDf0Qq3nexxxxxxxxGIO");
  req.setHttpMethod("GET");
  OapiGettokenResponse rsp = client.execute(req);
  System.out.println(rsp.getBody());
}

• Caching: access_token berlaku selama 2 jam. Simpan di cache memori atau Redis, dan perbarui 5 menit sebelumnya masa berlaku habis.
• Kontrol konkurensi: Cegah beberapa thread memperbarui token secara bersamaan. Gunakan distributed lock jika diperlukan.
• Coba ulang saat error: Lakukan percobaan ulang otomatis saat jaringan tidak stabil, maksimal 3 kali, dengan interval yang meningkat (1s → 2s → 4s).

​

Langkah 4: Panggil API inti

1. Ambil jadwal pengguna: Saat karyawan mengajukan permintaan absen susulan di sistem absensi internal, panggil Server API Mengambil jadwal pengguna dengan tanggal yang dipilih karyawan. API ini mengembalikan jadwal waktu absen karyawan pada tanggal tersebut.
   public void scheduleInfo() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/schedule/listbyday");
       OapiAttendanceScheduleListbydayRequest req = new OapiAttendanceScheduleListbydayRequest();
       req.setOpUserId("ma******75");
       req.setUserId("014*********041");
       req.setDateTime(166*******00L);
       OapiAttendanceScheduleListbydayResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   
2. Kirim notifikasi persetujuan absen susulan: Karyawan mengajukan Formulir persetujuan absen susulan di sistem cuti dan absensi internal. Jika permintaan disetujui, panggil Server API Notifikasi persetujuan absen susulan. Data absen susulan yang diajukan tersinkron ke aplikasi DingTalk Attendance, dan status kehadiran berubah dari “Absen terlewat” menjadi “Absen susulan disetujui”.

​

Catatan

public void approveCheck() throws ApiException {
    DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/approve/check");
    OapiAttendanceApproveCheckRequest req = new OapiAttendanceApproveCheckRequest();
    req.setUserid("ma****75");
    req.setWorkDate("2022-10-10 09:00:00");
    req.setPunchId(1006170802L);
    req.setPunchCheckTime("2022-10-10 09:00:00");
    req.setUserCheckTime("2022-10-10 08:00:00");
    req.setApproveId("dingTalk10001");
    req.setJumpUrl("https://www.dingtalk.io");
    req.setTagName("Absen susulan");
    OapiAttendanceApproveCheckResponse rsp = client.execute(req, "access_token");
    System.out.println(rsp.getBody());
}

​

Parameter:

3. Kirim notifikasi penarikan persetujuan: Jika karyawan menarik permintaan absen susulan, panggil Server API Notifikasi penarikan persetujuan. API ini menarik permintaan absen susulan yang telah tersinkron ke DingTalk dan memulihkan status kehadiran ke status absen sebelum perubahan.
   public void approveCancel() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/approve/cancel");
       OapiAttendanceApproveCancelRequest req = new OapiAttendanceApproveCancelRequest();
       req.setUserid("ma****75");
       req.setApproveId("dingTalk10001");
       OapiAttendanceApproveCancelResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   

• ✅ Semua panggilan API mengembalikan kode status berhasil (errcode=0).
• ✅ Setelah absen susulan tersinkron, panggil API pengambilan jadwal untuk memverifikasi bahwa waktu absen sudah benar.
• ✅ Setelah penarikan, verifikasi bahwa status kehadiran telah dipulihkan ke kondisi semula.
• ✅ Log error lengkap dan mencakup ID Formulir persetujuan, ID pengguna karyawan, dan waktu operasi.
• ✅ Data absen susulan di sistem OA internal dan DingTalk Attendance dibandingkan secara berkala dan tetap konsisten.

​

FAQ

• Q1: Apa perbedaan sinkronisasi absen susulan dengan persetujuan absen susulan bawaan DingTalk? A: Keduanya memiliki tujuan yang sepenuhnya berbeda:
  • Persetujuan absen susulan bawaan DingTalk: Karyawan mengajukan permintaan absen susulan di aplikasi DingTalk → atasan menyetujuinya → status kehadiran diperbarui secara otomatis. Cocok untuk organisasi yang tidak memiliki sistem OA sendiri.
  • Sinkronisasi absen susulan dalam solusi ini: Karyawan mengajukan permintaan absen susulan di sistem OA atau sistem cuti dan absensi internal → persetujuan OA lolos → API menyinkronkan hasilnya ke DingTalk. Cocok untuk organisasi dengan alur persetujuan OA yang matang dan mencegah karyawan mengulangi pekerjaan di dua sistem.
  Perbedaan utama: Solusi ini tidak membuat Formulir persetujuan absen susulan di DingTalk. Solusi ini hanya menyinkronkan hasil persetujuan OA ke catatan kehadiran DingTalk, sehingga Proses persetujuan internal Anda tetap independen.
• Q2: Bagaimana cara menangani kegagalan pada sebagian karyawan saat sinkronisasi absen susulan massal? A: Untuk sinkronisasi massal, proses catatan satu per satu dan coba ulang yang gagal:
  1. Proses per batch: Sertakan maksimal 50 karyawan per batch untuk menghindari request timeout.
  2. Isolasi kegagalan: Uraikan respons, lalu ambil ID pengguna karyawan yang gagal beserta penyebab error (errcode/errmsg).
  3. Tangani per kategori:
     • User not in attendance group: Periksa apakah karyawan sudah bergabung ke grup absensi yang benar.
     • Date out of range: Pastikan tanggal absen susulan berada dalam rentang waktu yang diizinkan.
     • Network timeout: Coba ulang otomatis maksimal 3 kali dengan interval yang meningkat (1s/2s/4s).
  4. Pencatatan log: Untuk setiap kegagalan, catat ID Formulir persetujuan, ID pengguna karyawan, penyebab error, dan jumlah percobaan ulang agar staf dapat menindaklanjutinya secara manual.
• Q3: Bagaimana cara memverifikasi konsistensi data setelah sinkronisasi absen susulan? A: Siapkan mekanisme verifikasi tiga lapis:
  1. Pemeriksaan real-time: Setelah sinkronisasi berhasil, segera pastikan status kehadiran karyawan pada hari tersebut telah berubah dari “Absen terlewat” menjadi “Absen susulan disetujui”.
  2. Perbandingan terjadwal: Jalankan tugas perbandingan menyeluruh setiap dini hari. Ambil catatan persetujuan absen susulan hari tersebut dari sistem OA internal dan catatan absen susulan dari DingTalk Attendance. Cocokkan keduanya berdasarkan ID Formulir persetujuan dan ID pengguna karyawan. Jika ditemukan ketidaksesuaian, buat tiket peringatan.
  3. Pemantauan error: Picu peringatan untuk setiap karyawan yang sinkronisasinya gagal 3 kali berturut-turut, lalu beri tahu Admin HR untuk memeriksa secara manual. Kemungkinan penyebabnya antara lain karyawan yang sudah keluar tetapi belum dihapus dari grup absensi, atau jadwal yang belum dikonfigurasi.
• Q4: Apa yang terjadi setelah absen susulan ditarik jika karyawan memiliki catatan absen normal pada hari tersebut? A: Penarikan memulihkan status kehadiran DingTalk ke status absen semula sebelum absen susulan. Secara spesifik:
  • Jika statusnya “Absen terlewat” (tidak ada absen) → status kembali menjadi “Absen terlewat”.
  • Jika statusnya “Absen normal” → status kembali menjadi “Absen normal”, dan catatan absen susulan dihapus.
  • Jika statusnya “Keterlambatan/Pulang lebih awal” → status kembali menjadi “Keterlambatan/Pulang lebih awal”, dan catatan absen susulan dihapus.
  Penting: Penarikan tidak dapat dibatalkan. Setelah dijalankan, status absen susulan tidak dapat dipulihkan. Tambahkan langkah konfirmasi kedua di sistem OA internal Anda untuk mencegah penarikan yang tidak disengaja.