# Tutorial Koneksi API Database Sekolah

Panduan menghubungkan web CMS lain ke database aplikasi Report (DAMARIS) untuk mengambil **dropdown nama sekolah**.

---

## 1. Yang Dibutuhkan

| Kebutuhan | Contoh | Keterangan |
|---|---|---|
| **Alamat API** | `https://report.8mataair.my.id/api/external.php` | Lokal: `http://localhost/report/api/external.php` |
| **Kode API** | `DMA-68DC8058A37CA307` | Dibuat/diubah lewat aplikasi (lihat bagian 2) |

> API bersifat **read-only** — pihak ketiga hanya bisa membaca daftar sekolah, tidak bisa mengubah/menghapus data.

---

## 2. Cara Mendapatkan / Mengganti Kode API

1. Login ke aplikasi Report sebagai **Super Admin**.
2. Buka menu **Konfigurasi Sistem** → tab **Sistem**.
3. Cari kartu **"Kode API Eksternal"**.
4. Klik **Generate Kode** untuk membuat kode baru (kode lama otomatis nonaktif), lalu klik **Salin**.
5. Bagikan kode ini ke pihak yang akan mengintegrasikan web-nya.

> **Keamanan:** kode ini adalah satu-satunya kunci akses. Hanya berikan ke orang yang dipercaya. Jika bocor → langsung **Generate Kode** ulang.

---

## 3. Endpoint API

| Action | Fungsi |
|---|---|
| `ping` | Tes koneksi + validasi kode (mengecek apakah terkoneksi) |
| `schools` | Mengambil daftar nama sekolah untuk dropdown |

### 3.1. Tes Koneksi (`ping`)

```http
GET /api/external.php?action=ping&api_key=KODE_API
```

**Response sukses:**
```json
{
  "ok": true,
  "connected": true,
  "api": "external",
  "version": "v1",
  "db": "db_report",
  "server_time": "2026-09-07 17:41:55",
  "school_count": 12966,
  "message": "Koneksi berhasil. Kode API valid."
}
```

### 3.2. Ambil Daftar Sekolah (`schools`)

```http
GET /api/external.php?action=schools&api_key=KODE_API
```

**Parameter opsional:**

| Parameter | Tipe | Default | Keterangan |
|---|---|---|---|
| `q` | string | *(kosong)* | Pencarian nama / ID / kecamatan (LIKE) |
| `limit` | int | `500` | Maksimum jumlah data (1–1000) |

Contoh pencarian:
```http
GET /api/external.php?action=schools&q=sma&limit=10&api_key=KODE_API
```

**Response sukses:**
```json
{
  "ok": true,
  "count": 3,
  "schools": [
    {
      "school_id": "28980189",
      "name": "BIMBA ABC SMART_CIRACAS",
      "marketing": "DEPI RAHMAWATI",
      "kecamatan": "Ciracas",
      "kota_kab": "Jakarta Timur - Kota",
      "provinsi": "DKI JAKARTA"
    }
  ]
}
```

> Sekolah ber-status *blacklist* tidak ikut dikirim.

---

## 4. Cara Mengirim Kode API

Kode wajib dikirim di **setiap request**, salah satu cara:

| Metode | Cara |
|---|---|
| **GET (query string)** | `?api_key=KODE_API` |
| **Header HTTP** | `X-API-Key: KODE_API` |
| **Body JSON (POST)** | `{ "action": "schools", "api_key": "KODE_API" }` |

---

## 5. Contoh Implementasi

### 5.1. JavaScript (fetch) — isi dropdown nama sekolah

```html
<select id="sekolah"></select>

<script>
const API_URL = 'https://report.8mataair.my.id/api/external.php';
const API_KEY = 'DMA-68DC8058A37CA307';

async function loadSekolah() {
  const res = await fetch(API_URL + '?action=schools&api_key=' + API_KEY);
  const data = await res.json();

  if (!data.ok) {
    alert('Gagal terhubung: ' + data.error);
    return;
  }

  const sel = document.getElementById('sekolah');
  sel.innerHTML = '<option value="">— Pilih Nama Sekolah —</option>';

  data.schools.forEach(s => {
    const opt = document.createElement('option');
    opt.value = s.school_id;
    opt.textContent = s.name + (s.kecamatan ? ' — ' + s.kecamatan : '');
    sel.appendChild(opt);
  });
}

loadSekolah();
</script>
```

### 5.2. JavaScript (fetch) — dengan pencarian

```html
<input type="text" id="cari" placeholder="Ketik nama sekolah..." oninput="cariSekolah(this.value)">

<script>
async function cariSekolah(q) {
  const url = API_URL + '?action=schools&q=' + encodeURIComponent(q) + '&limit=20&api_key=' + API_KEY;
  const data = await (await fetch(url)).json();
  // ...isi dropdown seperti contoh 5.1
}
</script>
```

### 5.3. cURL

```bash
# Tes koneksi
curl -s "https://report.8mataair.my.id/api/external.php?action=ping&api_key=DMA-68DC8058A37CA307"

# Ambil daftar sekolah + cari "sma"
curl -s "https://report.8mataair.my.id/api/external.php?action=schools&q=sma&limit=10&api_key=DMA-68DC8058A37CA307"

# Pakai header
curl -s -H "X-API-Key: DMA-68DC8058A37CA307" "https://report.8mataair.my.id/api/external.php?action=schools"
```

### 5.4. PHP (cURL)

```php
<?php
$apiKey = 'DMA-68DC8058A37CA307';
$url = 'https://report.8mataair.my.id/api/external.php?action=schools&q=sma&api_key=' . urlencode($apiKey);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . $apiKey]);
$res = curl_exec($ch);
curl_close($ch);

$data = json_decode($res, true);
if (!empty($data['ok'])) {
  foreach ($data['schools'] as $s) {
    echo $s['school_id'] . ' - ' . $s['name'] . "\n";
  }
}
```

---

## 6. Alur yang Disarankan di Web Pihak Ketiga

1. **Boot** → panggil `action=ping` → cek `data.ok === true`.
2. Kalau **gagal**: tampilkan pesan error (`data.error`) dan `data.hint`, jangan lanjut.
3. Kalau **berhasil**: panggil `action=schools` → isi dropdown → simpan hasil di cache (agar tidak panggil API terus-menerus).
4. Panggil ulang `schools` saat halaman dibuka / tombol refresh dropdown diklik.

---

## 7. Daftar Error Response

| Kode HTTP | `error` | Penyebab |
|---|---|---|
| 401 | `Kode API belum dikonfigurasi.` | Kode belum dibuat (Generate dulu di aplikasi) |
| 401 | `Kode API salah. Periksa kembali kode yang Anda gunakan.` | Kode kosong / salah / sudah diganti |
| 400 | `Action tidak valid.` | Nama action salah |

> Selalu cek `data.ok` (bukan hanya status HTTP) karena response error juga dikirim dengan format JSON.

---

## 8. CORS (Akses Lintas Domain)

API sudah mengirim `Access-Control-Allow-Origin: *`, sehingga web di **domain mana pun** bisa memanggil API ini langsung dari browser (tidak ada blokir CORS). Request `OPTIONS` (preflight) juga sudah ditangani.

---

## 9. FAQ

**Q: Bisakah pihak ketiga mengubah / menghapus data sekolah?**
Tidak. API `external.php` hanya menyediakan `ping` dan `schools`; semua read-only.

**Q: Bagaimana jika kode API bocor?**
Generate ulang kode di **Konfigurasi Sistem → Sistem → Kode API Eksternal**. Kode lama langsung tidak berlaku.

**Q: Ada berapa maksimal data yang diambil?**
Default 500, maksimum 1000 per panggilan (atur lewat `limit`). Untuk data lebih banyak gunakan pencarian (`q`) atau `limit=1000`.

**Q: Bisa dipanggil dari PHP/Android tanpa browser?**
Bisa. PHP (cURL) contoh di bagian 5.4; dari Android cukup kirim GET biasa ke URL dengan `api_key`.

**Q: Cara cek cepat di browser?**
Buka saja: `https://report.8mataair.my.id/api/external.php?action=ping&api_key=KODE_API`