# Panduan Lengkap: Integrasi & Penggunaan Roamercheck API

Dokumen ini berisi panduan lengkap cara menjalankan dashboard playground, penjelasan arsitektur file, serta contoh kode penggunaan SDK Client (PHP & JavaScript) untuk layanan **Roamercheck Premium API**.

---

## 1. Struktur Project

Project Anda tersusun dari struktur folder berikut:
```
roamercheck-api/
├── src/
│   ├── RoamerCheckClient.php   <-- SDK PHP Client Library (Backend)
│   └── RoamerCheckClient.js    <-- SDK JS/Node Client Library (Frontend / Backend JS)
├── public/
│   ├── index.php               <-- UI Playground Dashboard Utama (Frontend HTML)
│   ├── index.css               <-- CSS Styling Premium (Glassmorphism Dark-Mode)
│   └── api-bridge.php          <-- API Bridge PHP (Penghubung Aman backend-ke-backend)
└── TUTORIAL.md                 <-- File Panduan ini
```

---

## 2. Cara Menjalankan Dashboard Playground

Dashboard Playground dibuat untuk mempermudah pengetesan endpoint secara visual. Untuk menjalankannya:

### Opsi A: Menggunakan CLI PHP (Direkomendasikan & Cepat)
Jika Anda memiliki PHP terinstal di terminal sistem, jalankan perintah berikut:
1. Buka terminal atau PowerShell.
2. Arahkan ke folder project `roamercheck-api`.
3. Jalankan perintah server internal PHP:
   ```powershell
   php -S localhost:8000 -t public
   ```
4. Buka browser Anda dan akses: `http://localhost:8000`

### Opsi B: Menggunakan XAMPP / Laragon / IIS
Jika Anda menggunakan web server lokal seperti XAMPP atau Laragon:
1. Salin atau pindahkan seluruh folder `roamercheck-api` ke direktori web root Anda (misalnya `C:\xampp\htdocs` untuk XAMPP).
2. Akses melalui browser sesuai konfigurasi folder Anda, contoh: `http://localhost/roamercheck-api/public`

---

## 3. Dokumentasi Penggunaan PHP SDK Client (`src/RoamerCheckClient.php`)

Kelas [RoamerCheckClient](file:///C:/Users/Administrator/.gemini/antigravity/scratch/roamercheck-api/src/RoamerCheckClient.php) membungkus request API menggunakan PHP cURL secara aman.

### Langkah Integrasi Dasar

```php
<?php
// Impor berkas library
require_once 'src/RoamerCheckClient.php';

// Inisialisasi Client
$apiKey = 'API_KEY_ANDA';
$username = 'USERNAME_ANDA';
$client = new RoamerCheckClient($apiKey, $username);
```

### Contoh Pemanggilan Endpoint

#### A. Cek Saldo & Detail Tarif Layanan
```php
try {
    $response = $client->getBalance();
    if ($response['status'] === true) {
        $credits = $response['data']['credits'];
        echo "Sisa Saldo: Rp. " . number_format($credits, 0, ',', '.');
    } else {
        echo "Error: " . $response['message'];
    }
} catch (Exception $e) {
    echo "Sistem Error: " . $e->getMessage();
}
```

#### B. Cek Status Bea Cukai (IMEI)
Mengecek apakah IMEI terdaftar secara resmi di bea cukai nasional.
```php
$imeis = ['358806098871906'];
$response = $client->checkBeaCukai($imeis);

if ($response['status'] === true) {
    $result = $response['data']['result'];
    print_r($result);
}
```

#### C. Cek Status IMEI (Roamer, DigiPOS, Smartfren)
```php
$imeis = ['358806098871906', '353016113443195'];

// 1. Cek status Roamer
$roamer = $client->checkRoamerStatus($imeis);

// 2. Cek status DigiPOS
$digipos = $client->checkDigiPosStatus($imeis);

// 3. Cek status Smartfren
$smartfren = $client->checkSmartfrenStatus($imeis);
```

#### D. Pembuatan Barcode MEID iPhone
Membutuhkan tepat **2 IMEI** di dalam array parameter.
```php
try {
    $imeis = ['358806098871906', '353016113443195'];
    $response = $client->generateBarcode($imeis, 'dark'); // Mode: 'white' atau 'dark'
    
    if ($response['status'] === true) {
        $base64Image = $response['result']['base64_image'];
        // Tampilkan langsung di HTML
        echo '<img src="' . $base64Image . '" alt="MEID Barcode" />';
    }
} catch (InvalidArgumentException $e) {
    echo "Validasi Gagal: " . $e->getMessage();
}
```

---

## 4. Dokumentasi Penggunaan JavaScript SDK Client (`src/RoamerCheckClient.js`)

SDK JavaScript mendukung pemanggilan non-blocking secara asinkron (`Promise`/`async-await`).

### Penggunaan di Sisi Node.js
```javascript
const RoamerCheckClient = require('./src/RoamerCheckClient');

const client = new RoamerCheckClient('API_KEY_ANDA', 'USERNAME_ANDA');

async function run() {
    const balance = await client.getBalance();
    console.log(balance);
}
run();
```

### Penggunaan di Sisi Browser (Frontend)
> [!WARNING]
> Memanggil API langsung dari browser dapat memicu masalah kebijakan keamanan CORS dari browser. Oleh karena itu, gunakan `public/api-bridge.php` sebagai proxy jembatan penghubung aman seperti yang diimplementasikan pada file playground.

---

## 5. Integrasi ke Aplikasi `checkroamer` Utama

Untuk mengintegrasikan API ini ke aplikasi utama Anda (`checkroamer`):
1. Salin berkas [RoamerCheckClient.php](file:///C:/Users/Administrator/.gemini/antigravity/scratch/roamercheck-api/src/RoamerCheckClient.php) ke dalam folder `checkroamer/system/` atau `checkroamer/includes/`.
2. Buat service baru di menu Admin panel Checkroamer.
3. Hubungkan logika order IMEI di `cron_helper.php` dengan cara menginisialisasi kelas `RoamerCheckClient` dan memanggil method cek status atau cek Bea Cukai secara dinamis.