Dokumentasi API Absensindo

Dokumentasi API untuk integrasi perangkat Absensindo dan mesin absensi RFID secara langsung ke server, backend, aplikasi, atau dashboard perusahaan Anda.

Dokumentasi ini menetapkan "kontrak" (API Contract) yang harus dipenuhi oleh server Anda agar mesin dapat berkomunikasi dengan benar. Mesin Absensindo bertindak sebagai klien yang akan mengirimkan request HTTP POST ke server Anda.

Konsep Utama

Arah Komunikasi: Mesin absensi → API Server Anda → Database.
Keamanan: Menggunakan Bearer Token setelah proses aktivasi.
Format Data: Wajib menerima dan mengembalikan format JSON yang ketat.

Base URL Configuration

Pada antarmuka pengaturan WiFi di Mesin absensi, Anda akan diminta memasukkan Server URL.

Perhatian Penting: Isikan hanya URL dasar (Base URL) dari API Anda. Jangan tambahkan rute spesifik seperti /activate atau awalan /api/device/ di mesin.

Misalnya, jika Anda mengisi Server URL di mesin dengan:

https://api.perusahaananda.com

Maka secara otomatis, firmware mesin akan menambahkan path dan memanggil URL berikut:

https://api.perusahaananda.com/api/device/activate
https://api.perusahaananda.com/api/device/cek
https://api.perusahaananda.com/api/device/attendance
https://api.perusahaananda.com/api/device/heartbeat

Authentication Scheme

Untuk mengamankan endpoint dari akses ilegal, sistem menggunakan skema Bearer Token standar.

Mesin pertama kali menyala dan memanggil endpoint /activate. Endpoint ini tidak memerlukan token.
Server memverifikasi data mesin, lalu merespons dengan JSON yang berisi token.
Mesin menyimpan token tersebut di memorinya (EEPROM/Flash).
Untuk setiap request selanjutnya (seperti absensi atau cek status), mesin akan menyertakan token tersebut di HTTP Headers.

Format HTTP Header yang dikirim mesin:

Headers

Authorization: Bearer <TOKEN_YANG_DIBERIKAN_SERVER>
Content-Type: application/json
Accept: application/json

Standard Response Structure (Envelope)

Hal yang paling krusial dalam integrasi ini adalah struktur JSON balasan dari server Anda. Mesin absensi tidak hanya membaca kode status HTTP (seperti 200 atau 404), tetapi secara aktif mem-parsing isi JSON.

Server Anda wajib mengembalikan struktur envelope (pembungkus) seperti di bawah ini untuk semua endpoint API mesin.

Response Fields

Field	Type	Description
`success`	`boolean`	Bernilai `true` jika request berhasil diproses secara logika bisnis, `false` jika gagal/ditolak.
`code`	`integer`	Kode HTTP numerik yang mencerminkan status (contoh: 200, 401, 409).
`message`	`string`	Pesan yang ditujukan untuk log developer (tidak akan ditampilkan di layar mesin).
`data`	`object`	Objek yang memuat payload. Wajib mengandung minimal key `reason`.
`data.reason`	`string`	Kata kunci (enum) penentu tindakan firmware. Lihat bagian Reason Codes.

JSON Response Template

{
  "success": true,
  "code": 200,
  "message": "Human readable message",
  "data": {
    "reason": "status_code_string"
    /* optional fields go here */
  }
}

POST /api/device/activate

Mendaftarkan mesin dan memberikan token akses.

Dipanggil oleh mesin secara otomatis saat baru terhubung ke jaringan dan tidak memiliki token di memorinya. Server harus menghasilkan token baru, menyimpannya di database terkait mesin ini, dan mengembalikannya dalam response.

Request Parameters (Body)

Parameter	Type	Description
`serial_number`	`string`	Serial number fisik mesin (unik).
`mac_address`	`string`	MAC Address WiFi mesin.
`firmware_version`	`string`	Versi software saat ini.

Response Data Fields

Selain struktur envelope standar, isi data harus memuat:

Field	Description
`reason`	Harus bernilai `"device_activated"` jika sukses.
`token`	String token acak (JWT atau string hash).
`token_type`	Harus bernilai `"Bearer"`.
`expires_in`	Waktu kedaluwarsa token dalam detik. Direkomendasikan angka besar (misal setahun).

Request Body

{
  "serial_number": "ABS-DEV-001",
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "firmware_version": "1.9.5"
}

Success Response

{
  "success": true,
  "code": 200,
  "message": "Aktivasi sukses",
  "data": {
    "reason": "device_activated",
    "token": "your_generated_token_here",
    "token_type": "Bearer",
    "expires_in": 31536000
  }
}

POST /api/device/cek

Requires Bearer Token

Verifikasi validitas token dan status mesin.

Dipanggil secara periodik atau setelah mesin restart (jika sudah punya token). Server harus memeriksa apakah token valid, dan apakah mesin ini tidak dinonaktifkan di dashboard admin.

Request Parameters (Body)

Sama persis dengan parameter pada endpoint /activate.

Response Data Fields

Field	Description
`reason`	Harus bernilai `"device_verified"` jika sukses. Jika token salah/mesin diblokir, kembalikan reason error yang sesuai (lihat bagian bawah).

Request Body

{
  "serial_number": "ABS-DEV-001",
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "firmware_version": "1.9.5"
}

Success Response

{
  "success": true,
  "code": 200,
  "message": "Verifikasi OK",
  "data": {
    "reason": "device_verified"
  }
}

POST /api/device/attendance

Core Feature

Menerima data ketukan kartu RFID (Tap In/Out).

Ini adalah endpoint inti. Dipanggil seketika saat kartu RFID didekatkan ke sensor mesin. Waktu respons server menentukan seberapa cepat layar mesin bereaksi.

Request Parameters (Body)

Parameter	Type	Description
`uid`	`string`	ID unik kartu RFID (hexadecimal uppercase).
`scanned_at`	`string`	Waktu scan tercatat di mesin (format: `YYYY-MM-DD HH:MM:SS`).

Response Data Fields (Optional for LCD display)

Selain reason, tambahkan data berikut agar layar mesin menampilkan nama user yang absen dengan baik.

Field	Description
`reason`	`"checkin_on_time"`, `"checkin_late"`, dll. Menentukan ikon/suara di mesin.
`student_name`	Nama untuk ditampilkan (Max 20 char).
`status_label`	Teks bebas penanda status (Misal: "Terlambat").
`time`	Waktu yang ditampilkan di layar (Misal: "07:15").

Request Body

{
  "uid": "04A1B2C3D4",
  "scanned_at": "2026-03-11 07:15:12"
}

Success Response

{
  "success": true,
  "code": 200,
  "message": "Absensi dicatat",
  "data": {
    "reason": "checkin_on_time",
    "uid": "04A1B2C3D4",
    "student_name": "Budi Santoso",
    "status_label": "Tepat Waktu",
    "time": "07:15"
  }
}

POST /api/device/heartbeat

Sinyal penanda mesin sedang online.

Dikirim berkala oleh mesin (biasanya setiap menit). Anda bisa menggunakan endpoint ini untuk meng-update tabel database last_seen mesin, sehingga di dashboard Anda bisa tahu apakah mesin dalam keadaan hidup atau mati.

Request

{
  "uptime": 3600 // detik
}

Response (Minimal)

{
  "success": true,
  "code": 200,
  "data": { "reason": "ok" }
}

Reason Codes Dictionary

Properti reason adalah nyawa dari interaksi layar mesin. Apa pun kata yang Anda kirim pada string ini, akan memicu reaksi visual (tulisan di layar, ikon sukses/gagal) dan suara (nada berhasil, gagal, error) pada perangkat fisik.

1. Status Koneksi & Autentikasi

Code String	Suggested HTTP	Makna & Efek di Mesin
`device_activated`	200	Aktivasi sukses, mesin mulai menyimpan token dan masuk mode standby.
`device_verified`	200	Token divalidasi dengan sukses saat ping rutin.
`invalid_token`	401	Token ditolak server. Mesin akan mereset memorinya dan mengulang proses aktivasi.
`device_inactive`	403	Mesin diblokir dari dashboard. Mesin akan menampilkan layar terblokir.

2. Hasil Scan Absensi (Endpoint /attendance)

Code String	Suggested HTTP	Efek Layar LCD Mesin
`checkin_on_time`	200	Tampil nama besar, centang HIJAU besar, suara "Terima kasih".
`checkin_late`	200	Tampil nama besar, peringatan KUNING, suara peringatan.
`checkout_on_time`	200	Tampil pesan pulang, centang HIJAU.
`new_card_detected`	409	Layar merah: "Kartu Belum Terdaftar". Idealnya server menyimpan UID ini di tabel "kartu menunggu diregistrasi".
`already_checked_in`	422	Layar kuning: "Sudah Absen Masuk" (mencegah double-tap).
`outside_checkin_window`	422	Layar merah: "Di luar jam absensi".
`holiday`	422	Layar menampilkan informasi bahwa hari ini libur.

Architecture: Adapter Pattern

Jika aplikasi internal Anda sudah menggunakan API absensi pihak ketiga atau formatnya sangat berbeda, jangan mengubah inti aplikasi Anda.

Buatlah sebuah script sederhana (sebagai Middleware atau Adapter) yang berada di antara Mesin absensi dan Sistem Anda. Tugasnya:

Menerima request JSON format mesin.
Menerjemahkan request tersebut dan memanggil API/fungsi sistem internal Anda (contoh: `insert_attendance()`).
Mengevaluasi hasil dari sistem Anda (sukses/gagal/terlambat).
Mengembalikan response ke mesin dengan format JSON `Envelope` dan `reason` yang sesuai.

REQUEST FLOW

Mesin absensi

API Adapter

Database Anda

Quick Test (cURL)

Sebelum menguji langsung dengan mesin fisik, pastikan endpoint Anda bisa membalas perintah cURL ini dari terminal lokal Anda dengan benar (format JSON standar).

Gunakan contoh di sebelah kanan pada terminal/command prompt Anda. Ganti URL `https://api.perusahaananda.com` dengan URL environment lokal atau staging Anda (misal `http://localhost:8000`).

Terminal (Test Activate)

curl -X POST "https://api.perusahaananda.com/api/device/activate" \
  -H "Content-Type: application/json" \
  -d '{"serial_number":"ABS-DEV-001","mac_address":"aa:bb:cc:dd:ee:ff","firmware_version":"1.9.5"}'

Terminal (Test Attendance)

curl -X POST "https://api.perusahaananda.com/api/device/attendance" \
  -H "Authorization: Bearer YOUR_GENERATED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uid":"04A1B2C3D4","scanned_at":"2026-03-11 07:15:12"}'

Dokumentasi API Absensindo

Konsep Utama

Base URL Configuration

Authentication Scheme

Format HTTP Header yang dikirim mesin:

Standard Response Structure (Envelope)

Response Fields

API Reference

Request Parameters (Body)

Response Data Fields

Request Parameters (Body)

Response Data Fields

Request Parameters (Body)

Response Data Fields (Optional for LCD display)

Reason Codes Dictionary

1. Status Koneksi & Autentikasi

2. Hasil Scan Absensi (Endpoint /attendance)

Architecture: Adapter Pattern

Quick Test (cURL)