# 📚 Panduan Penggunaan API Key: Sistem API Absensi Terpusat

Selamat datang di Dokumentasi Integrasi API Absensi! Panduan ini akan membantu Anda memahami cara melakukan autentikasi dengan aman menggunakan **API Key** agar Anda bisa segera menarik dan menyinkronkan data absensi mesin dengan mudah.

---

## 1. 💡 Ringkasan Singkat
**API Key** bertindak sebagai "paspor digital" aplikasi Anda. Key ini berfungsi untuk mengidentifikasi siapa yang melakukan *request* sekaligus memastikan bahwa Anda memiliki izin yang sah untuk mengakses endpoint kami. 

> ⚠️ **PENTING:** API Key Anda memiliki hak akses penuh ke data sensitif perusahaan. Perlakukan API Key layaknya *password* m-banking Anda—**jangan pernah membagikan atau mempublikasikannya secara terbuka.**

---

## 2. 🔑 Cara Mendapatkan API Key
Untuk mulai berintegrasi, Anda memerlukan *API Key* aktif. Ikuti 4 langkah mudah berikut:
1. Login ke **Dashboard Admin Absen** (menggunakan akun Superadmin/Developer).
2. Navigasi ke menu **Pengaturan** > **Manajemen API** (*API Settings*).
3. Klik tombol **"Generate New Key"** dan berikan label (contoh: *Integrasi Cabang Jakarta*).
4. Salin (Copy) string *API Key* yang muncul. (Perlu diingat: Key ini hanya ditampilkan satu kali saja demi keamanan).

---

## 3. 🛡️ Cara Autentikasi
Sistem kami mengharuskan penyertaan API Key pada setiap *request* yang Anda kirimkan. Pengiriman key tidak dilakukan melalui URL (demi mencegah kebocoran pada log server), melainkan wajib disisipkan ke dalam **HTTP Header**.

- **Key Header:** `X-API-Key`
- **Value:** `<API_KEY_ANDA>`

**Format Penulisan Header:**
```http
GET /absen/json HTTP/1.1
Host: api.absen-pusat.com
X-API-Key: SYAFANA_KEY_123
Accept: application/json
```

---

## 4. 💻 Contoh Request Sederhana
- **Base URL Endpoint:** `https://api.absen-pusat.com/v1` (Production) atau `http://localhost:3000` (Local/Dev)
- **Endpoint Uji Coba:** `/absen/json`

Berikut adalah contoh implementasinya di berbagai bahasa pemrograman favorit Anda:

### 🔹 cURL
```bash
curl -X GET "http://localhost:3000/absen/json" \
     -H "X-API-Key: SYAFANA_KEY_123" \
     -H "Accept: application/json"
```

### 🔹 PHP (menggunakan cURL)
```php
<?php
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "http://localhost:3000/absen/json",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: SYAFANA_KEY_123",
        "Accept: application/json"
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
```

### 🔹 Python (menggunakan library `requests`)
```python
import requests

url = "http://localhost:3000/absen/json"
headers = {
    "X-API-Key": "SYAFANA_KEY_123",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())
```

### 🔹 JavaScript / Node.js (menggunakan `fetch`)
```javascript
const url = 'http://localhost:3000/absen/json';
const options = {
  method: 'GET',
  headers: {
    'X-API-Key': 'SYAFANA_KEY_123',
    'Accept': 'application/json'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));
```

---

## 5. 🚨 Penanganan Error (Error Handling)
Jika autentikasi gagal atau Anda melebihi limit, API kami akan mengembalikan standar HTTP Status Codes. Gunakan panduan di bawah ini untuk *debugging*:

| HTTP Code | Status | Penyebab Masalah | Solusi |
| :--- | :--- | :--- | :--- |
| **401** | `Unauthorized` | API Key tidak dikirimkan, salah ketik, atau menggunakan key yang sudah tidak aktif (revoked). | Periksa kembali apakah header `X-API-Key` terisi dengan benar. Pastikan API key belum dihapus di Dashboard. |
| **403** | `Forbidden` | API Key valid, namun tidak memiliki hak akses (*permission*) ke endpoint yang dituju. | Hubungi Administrator untuk memastikan role/scope API Key Anda mencakup endpoint tersebut. |
| **429** | `Too Many Requests` | Aplikasi Anda melakukan panggilan (*hit*) terlalu banyak dalam waktu singkat (Rate Limiting). | Perlambat frekuensi request Anda (gunakan mekanisme *delay* / *exponential backoff*). |

---

## 6. 🔒 Praktik Keamanan Terbaik (Best Practices)
Sebagai pengembang, menjaga integritas sistem adalah tugas bersama. Pastikan Anda menerapkan protokol berikut:

- ✅ **Gunakan Environment Variables (`.env`):** Simpan API Key Anda di dalam file `.env` di lokal server Anda. Jangan pernah menuliskannya secara *hardcode* di dalam *source code*.
- ✅ **Abaikan dari Version Control:** Pastikan file `.env` sudah masuk ke dalam `.gitignore`. Jangan pernah meng-*commit* atau mem-push API Key ke repository publik seperti GitHub.
- ✅ **Terapkan IP Whitelisting:** Di halaman dashboard, batasi penggunaan API Key hanya untuk IP Server Statis Anda. Ini mencegah hacker menggunakan key Anda dari komputer lain meskipun key tersebut bocor.
- ✅ **Lakukan Rotasi Rutin:** Ganti (Regenerate) API Key Anda secara berkala (misal: setiap 3-6 bulan sekali) untuk meminimalisir dampak kerentanan keamanan jangka panjang.

***

*Mengalami kendala saat integrasi? Jangan ragu untuk menghubungi Tim Dukungan Developer kami! Selamat mengoding! 🚀*