​

Integrasi persetujuan cuti dan absensi: Sinkronkan data cuti dan absensi ke aplikasi Absensi DingTalk secara otomatis

​

Ringkasan

​

Latar belakang

• Absen susulan manual yang tidak efisien: Setelah absen di sistem Anda sendiri, karyawan harus mengajukan absen susulan di DingTalk. Proses ini merepotkan, dan karyawan sering lupa.
• Data tidak sinkron: Data absensi terpisah antara sistem Anda sendiri dan DingTalk. HR harus mencocokkan catatan absensi di beberapa sistem.
• Kurang tepat waktu: Karyawan ingin langsung melihat status kehadiran mereka di DingTalk setelah absen. Mereka tidak ingin menunggu sinkronisasi batch keesokan harinya.

​

Nilai utama

• Sinkronisasi absen otomatis: Catatan absen dari sistem Anda sendiri terunggah ke DingTalk secara otomatis, tanpa pekerjaan manual.
• Satu titik pengelolaan: Semua data absensi masuk ke DingTalk. HR mengelola statistik kehadiran dan analisis dalam satu platform.
• Integrasi cepat dan hemat biaya: Hanya 2 API inti yang diperlukan, sehingga biaya pengembangan tetap rendah.

​

Kasus penggunaan

• Integrasi dengan sistem absensi Anda sendiri: Hubungkan sistem absensi internal atau perangkat absensi pihak ketiga (pembaca kartu akses, pemindai sidik jari, terminal pengenalan wajah, dan lainnya) ke aplikasi Absensi DingTalk untuk menyinkronkan data absen secara otomatis.
• Konsolidasi data dari beberapa perangkat: Organisasi Anda menggunakan berbagai perangkat absensi di sejumlah lokasi kerja dan membutuhkan semua catatan absen di DingTalk untuk pengelolaan terpusat.
• Status kehadiran real-time: Karyawan ingin langsung melihat status kehadiran mereka di DingTalk setelah absen, tanpa menunggu sinkronisasi batch keesokan harinya.
• Tanpa pencocokan lintas sistem bagi HR: HR tidak perlu lagi membandingkan data antara sistem absensi Anda sendiri dan DingTalk secara manual, sehingga statistik kehadiran lebih cepat diproses.

​

Skenario bisnis umum

​

Skenario 1: Sinkronkan data absen dari sistem absensi Anda sendiri

​

Kendala

​

Nilai

• Alur kerja otomatis Alur sinkronisasi data absen secara real-time terdiri atas 5 langkah:
  1. Karyawan absen di sistem Anda sendiri.
  2. Sistem absensi Anda memanggil API DingTalk untuk membuat saluran data.
  3. Sistem Anda mengambil pengenal unik karyawan di DingTalk (userId) melalui API.
  4. Sistem Anda mengunggah catatan absen ke aplikasi Absensi DingTalk.
  5. Aplikasi Absensi DingTalk menampilkan status absen secara real-time.
  Contoh parameter unggahan: userid, userCheckTime, deviceId.
• Manfaat utama
  • Tanpa pekerjaan berulang: Setelah karyawan absen di sistem absensi Anda sendiri, data tersinkron ke aplikasi Absensi DingTalk melalui API. Karyawan tidak perlu lagi mengajukan absen susulan atau memasukkan ulang data.
  • Lebih sedikit peninjauan manual: Catatan absen tersinkron secara real-time, sehingga HR tidak perlu lagi meninjau permintaan absen susulan satu per satu. Beban peninjauan manual jauh berkurang dan waktu lebih hemat.
  • Data lebih akurat: Sinkronisasi otomatis menghilangkan intervensi manual dan kesalahan input data. Data absensi tetap autentik, akurat, dan dapat dilacak.
  • Pengalaman pengguna lebih baik: Karyawan melihat status absen secara real-time dan tidak perlu khawatir lupa absen atau lupa mengajukan absen susulan.

​

Skenario 2: Konsolidasikan data dari beberapa perangkat absensi

​

Kendala

​

Nilai

• Alur kerja otomatis Alur data untuk mengonsolidasikan data absen dari beberapa perangkat absensi ke DingTalk:
  1. Karyawan absen di berbagai perangkat absensi.
  2. Setiap perangkat mengunggah datanya secara real-time ke sistem absensi Anda sendiri.
  3. Sistem Anda memanggil API DingTalk Open Platform untuk mengunggah data absensi secara batch.
  4. DingTalk menerima semua data absen dan mengonsolidasikannya untuk penyimpanan dan pengelolaan terpadu.
  5. HR melihat laporan dan analitik absensi terpadu di Workbench DingTalk.
  Pendekatan tradisional mengharuskan masuk ke beberapa sistem, mengekspor data Excel, dan menggabungkan data secara manual untuk menyusun laporan. Sebaliknya, alur ini menghimpun data ke DingTalk secara otomatis dan membuat laporan dengan satu klik.
• Manfaat utama
  • Data multisumber terpadu: Konsolidasikan data absen dari pemindai sidik jari, terminal pengenalan wajah, lokasi GPS, dan perangkat absensi lainnya ke dalam satu format standar di DingTalk, sehingga tidak ada lagi silo data.
  • Pengelolaan terpusat: HR melihat catatan absensi setiap karyawan di DingTalk secara real-time, tanpa perlu masuk ke beberapa sistem, mengekspor file Excel, dan menggabungkannya secara manual.
  • Statistik lebih cepat: Sistem menghimpun data dan membuat laporan secara otomatis, sehingga siklus statistik kehadiran jauh lebih singkat.
  • Lebih sedikit pekerjaan manual: Otomatisasi menggantikan proses ekspor, pembersihan, dan penggabungan manual yang berulang. Biaya tenaga kerja turun dan risiko kesalahan manusia berkurang.

​

Panduan implementasi

​

Arsitektur teknis

• Lapisan autentikasi: Gunakan Client ID / Client Secret untuk mendapatkan access_token dan mengamankan panggilan API.
• Lapisan pengelolaan izin: Ajukan izin API Kontak dan absensi.
• Lapisan pengambilan ID pengguna: Panggil Server API Kontak untuk mendapatkan detail pengguna departemen dan mengambil ID pengguna setiap karyawan dalam Struktur Organisasi DingTalk.
• Lapisan unggah absen: Panggil Server API absensi untuk mengunggah catatan absen, termasuk tanggal dan waktu absen dari sistem Anda sendiri, ke aplikasi Absensi DingTalk.

​

Prasyarat

• Aplikasi: Buat dan konfigurasikan Aplikasi internal. Untuk detailnya, lihat Buat dan konfigurasikan aplikasi.
• Izin: Miliki izin Admin Organisasi atau Sub Admin DingTalk, lalu ajukan izin API berikut:
  • qyapi_get_department_member (izin baca anggota departemen Kontak)
  • Pro.AttendanceRecord.Write (izin tulis catatan absen)
• 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 halaman unduhan SDK Sisi server. SDK mendukung Java, Python, Go, dan bahasa lainnya.

​

Implementasi kode

1. Panggil Server API Kontak Dapatkan detail pengguna departemen untuk mengambil ID pengguna setiap karyawan dalam Struktur Organisasi DingTalk.
2. Panggil Server API absensi Unggah catatan absen untuk mengunggah tanggal, waktu, dan detail absen karyawan lainnya dari sistem Anda sendiri ke aplikasi Absensi DingTalk. Langkah ini menyinkronkan data absensi.

​

Langkah implementasi

​

Langkah 1: Dapatkan kredensial aplikasi

1. Masuk ke Konsol Pengembang DingTalk.
2. Pilih aplikasi target untuk membuka halaman detail aplikasi.
3. Klik Informasi Dasar > Kredensial dan Informasi Dasar.
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 pengenal izin berikut, lalu ajukan:
   • qyapi_get_department_member (izin baca anggota departemen Kontak): Mendapatkan detail pengguna departemen untuk mengambil ID pengguna.
   • Pro.AttendanceRecord.Write (izin tulis catatan absen): Mengunggah catatan absen ke aplikasi Absensi DingTalk.

​

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 dalam cache di memori atau Redis, lalu perbarui 5 menit sebelumnya masa berlakunya habis.
• Kontrol konkurensi: Cegah beberapa thread memperbarui token secara bersamaan sehingga menimbulkan konflik. Gunakan distributed lock.
• Coba ulang saat terjadi error: Coba ulang secara otomatis saat jaringan tidak stabil, maksimal 3 kali, dengan interval yang makin panjang (1s → 2s → 4s).

​

Langkah 4: Panggil API inti

1. Dapatkan detail pengguna departemen: Panggil Server API Kontak Dapatkan detail pengguna departemen untuk mengambil ID pengguna setiap karyawan dalam Struktur Organisasi DingTalk.
   public void deptInfo() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/list");
       OapiV2UserListRequest req = new OapiV2UserListRequest();
       req.setDeptId(1L);
       req.setCursor(0L);
       req.setSize(10L);
       req.setOrderField("entry_asc");
       req.setContainAccessLimit(false);
       req.setLanguage("zh_CN");
       OapiV2UserListResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   
2. Unggah catatan absen: Panggil Server API absensi Unggah catatan absen untuk mengunggah tanggal, waktu, dan detail absen karyawan lainnya dari sistem Anda sendiri ke aplikasi Absensi DingTalk. Langkah ini menyinkronkan data absensi.
   public void attendanceRecordUpload() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/record/upload");
       OapiAttendanceRecordUploadRequest req = new OapiAttendanceRecordUploadRequest();
       req.setUserid("01472825524039877041");
       req.setDeviceName("Absensi Gerbang Timur");
       req.setDeviceId("dingTalk_one");
       req.setPhotoUrl("https://xxx.com/xxx.png");
       req.setUserCheckTime(1665363600000L);
       OapiAttendanceRecordUploadResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   

• Kredensial aplikasi (Client ID / Client Secret) sudah didapatkan.
• Izin Kontak dan absensi sudah diberikan.
• access_token sudah didapatkan.
• Panggilan API Dapatkan detail pengguna departemen berhasil dan mengembalikan daftar ID pengguna yang benar.
• Panggilan API Unggah catatan absen berhasil, dan aplikasi Absensi DingTalk menampilkan data absen yang telah tersinkron.

​

FAQ

• Q1: Parameter apa saja yang wajib saat mengunggah catatan absen? A: Parameter wajibnya adalah:
  • userid: ID pengguna karyawan dalam Struktur Organisasi DingTalk
  • userCheckTime: Waktu absen (Unix timestamp, dalam milidetik)
  • deviceId: ID perangkat absensi
  • deviceName: Nama perangkat absensi Parameter opsional mencakup photoUrl (URL gambar yang dilampirkan pada catatan absen, yang harus dapat diakses publik).
• Q2: Apa penyebab umum kegagalan sinkronisasi data absen? A: Penyebab umumnya meliputi:
  • ID pengguna salah (harus milik karyawan dalam Struktur Organisasi DingTalk)
  • Format userCheckTime tidak valid atau waktunya di masa mendatang
  • access_token tidak valid atau sudah kedaluwarsa
  • Aplikasi belum mengajukan izin absensi
  • Permintaan jaringan timeout atau terjadi error server
• Q3: Apa praktik terbaik untuk mengunggah data absen banyak karyawan secara batch? A: Saat ini, API hanya menerima satu catatan absen per panggilan. Untuk mengunggah secara batch, panggil API dalam loop di lapisan bisnis, dan atur frekuensi panggilan agar tidak melampaui batas laju. Anda juga dapat menghubungi dukungan teknis DingTalk untuk menanyakan opsi unggah batch.