Panduan Integrasi API

Manual Book - Tim IT Internal

Panduan Integrasi API Penerima Data

Dokumen ini ditujukan untuk Programmer/Tim IT Internal yang akan membuat API untuk menerima data secara otomatis dari Aplikasi Desktop (di cabang/dealer) ke Server Internal Perusahaan.

1 Konsep & Alur Kerja (Workflow)

Aplikasi Desktop bertindak sebagai API Client yang akan melakukan HTTP POST Request untuk "mendorong" (push) data ke URL Server Internal Perusahaan Anda setiap kali tombol Sync ditekan.

User di cabang menekan tombol "Sync to Server" di Aplikasi Desktop.
Desktop mengirim request POST /api.php?action=get_last_sync_time ke server Anda.
Server Anda merespon: 2024-06-15 08:30:00 (Waktu sinkronisasi terakhir).
Desktop mencari log absensi di database lokalnya yang lebih baru dari waktu tersebut.
Desktop membungkus data Karyawan dan data Absensi baru menjadi JSON.
Desktop mengirim request POST /api.php?action=sync_all membawa payload JSON tersebut.
Server Anda menerima JSON, memasukkan datanya ke database internal, dan membalas status: success.

2 Struktur Tabel Database (Rekomendasi)

Untuk menampung data yang dikirim, Anda perlu menyiapkan setidaknya 2 tabel di database server internal Anda.

Tabel `employees`

Kolom	Tipe	Keterangan
id	VARCHAR(50)	Primary Key
employee_no	VARCHAR(50)	ID di mesin finger
name	VARCHAR(255)	Nama Karyawan
nip	VARCHAR(100)	NIP (Optional)
dealer_code	VARCHAR(50)	Kode Cabang/Dealer
dealer_name	VARCHAR(255)	Nama Cabang/Dealer
created_at	DATETIME	Waktu Dibuat

Tips: Buat UNIQUE KEY untuk kombinasi employee_no + dealer_code.

Tabel `attendance_logs`

Kolom	Tipe	Keterangan
id	VARCHAR(50)	Primary Key
employee_no	VARCHAR(50)	ID Karyawan absen
timestamp	DATETIME	Waktu absen (YYYY-MM-DD HH:MM:SS)
status	VARCHAR(50)	Contoh: Check In / Check Out
dealer_code	VARCHAR(50)	Kode Cabang/Dealer
dealer_name	VARCHAR(255)	Nama Cabang/Dealer
device_id	VARCHAR(100)	NIP Mesin Fingerprint

Tips: Buat UNIQUE KEY untuk kombinasi employee_no + timestamp + dealer_code agar terhindar dari data duplikat.

3 Spesifikasi Endpoint API yang Harus Dibuat

Anda bebas menggunakan bahasa pemrograman/framework apapun (PHP, Laravel, Node.js, dll). Cukup pastikan server Anda bisa merespon HTTP POST Request JSON di bawah ini.

POST /api.php?action=get_last_sync_time

Tujuan: Aplikasi desktop menanyakan kapan terakhir kali log absensi dari cabang ini masuk ke server, agar desktop hanya mengirim data baru (Incremental Sync).

Request dari Desktop:

{
  "kode_dealer": "DLR-001"
}

Response dari Server Anda:

{
  "status": "success",
  "last_sync_time": "2024-06-15 08:30:00"
}

* Jika belum ada data sama sekali untuk dealer tsb, kembalikan null.

POST /api.php?action=sync_all

Tujuan: Menerima array data karyawan dan absensi. Server Anda harus melooping array ini dan menyimpannya ke database.

Request dari Desktop (JSON):

{
  "kode_dealer": "DLR-001",
  "nama_dealer": "Alfa Motor Jakarta",
  "employees": [
    {
      "employee_no": "1001",
      "name": "Budi Santoso",
      "nip": "12345678",
      "created_at": "2024-01-15 10:00:00"
    }
  ],
  "attendance_logs": [
    {
      "employee_no": "1001",
      "timestamp": "2024-06-15 08:45:00",
      "status": "Check In",
      "device_id": "DS-K1T804"
    }
  ]
}