Retribusi/api/CORS_SETUP_GUIDE.md

# Panduan Setup CORS untuk API Btekno

## Masalah
Browser tidak dapat mengakses API karena CORS (Cross-Origin Resource Sharing) belum dikonfigurasi.

## Solusi

### Metode 1: CORS Handler di Setiap Endpoint (Recommended)

Tambahkan CORS handler di **AWAL** setiap file endpoint PHP:

```php
<?php
// ==================== CORS HANDLER - HARUS DI AWAL ====================
header("Access-Control-Allow-Origin: *");
header("Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS");
header("Access-Control-Allow-Headers: Content-Type, Authorization, X-API-KEY");
header("Access-Control-Max-Age: 3600");

// Handle preflight OPTIONS request
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(200);
    exit;
}
// ==================== END CORS HANDLER ====================

// Lanjutkan dengan logic endpoint...
```

### Metode 2: CORS Handler di Bootstrap/Autoload

Jika menggunakan framework atau autoloader, tambahkan CORS handler di file bootstrap:

**File: `bootstrap.php` atau `index.php`**
```php
<?php
// CORS Handler
header("Access-Control-Allow-Origin: *");
header("Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS");
header("Access-Control-Allow-Headers: Content-Type, Authorization, X-API-KEY");
header("Access-Control-Max-Age: 3600");

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(200);
    exit;
}

// Lanjutkan dengan routing/autoload...
```

### Metode 3: CORS Handler di .htaccess (Apache)

Jika menggunakan Apache, tambahkan di `.htaccess`:

```apache
# CORS Headers
<IfModule mod_headers.c>
    Header set Access-Control-Allow-Origin "*"
    Header set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
    Header set Access-Control-Allow-Headers "Content-Type, Authorization, X-API-KEY"
    Header set Access-Control-Max-Age "3600"
</IfModule>

# Handle OPTIONS request
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_METHOD} OPTIONS
    RewriteRule ^(.*)$ $1 [R=200,L]
</IfModule>
```

### Metode 4: CORS Handler di Nginx Config

Jika menggunakan Nginx, tambahkan di config:

```nginx
location / {
    # CORS Headers
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization, X-API-KEY' always;
    add_header 'Access-Control-Max-Age' '3600' always;
    
    # Handle OPTIONS request
    if ($request_method = 'OPTIONS') {
        return 204;
    }
    
    # Proxy atau serve PHP
    try_files $uri $uri/ /index.php?$query_string;
}
```

## Endpoint yang Perlu CORS Handler

Pastikan semua endpoint berikut memiliki CORS handler:

1. ✅ `/health` - Health check
2. ✅ `/auth/v1/login` - Login
3. ✅ `/retribusi/v1/dashboard/summary` - Dashboard summary
4. ✅ `/retribusi/v1/summary/hourly` - Hourly summary
5. ✅ `/retribusi/v1/dashboard/daily` - Daily chart
6. ✅ `/retribusi/v1/dashboard/by-category` - By category chart
7. ✅ `/retribusi/v1/realtime/snapshot` - Realtime snapshot
8. ✅ Semua endpoint lainnya

## Testing CORS

### Test dengan curl:
```bash
# Test OPTIONS request (preflight)
curl -X OPTIONS https://api.btekno.cloud/auth/v1/login \
  -H "Origin: http://localhost" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type" \
  -v

# Harus return:
# < HTTP/1.1 200 OK
# < Access-Control-Allow-Origin: *
# < Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
# < Access-Control-Allow-Headers: Content-Type, Authorization, X-API-KEY
```

### Test dengan browser:
1. Buka `dashboard/test-connection.html`
2. Klik "Test Health Check"
3. Buka Developer Tools (F12) → Network tab
4. Cek apakah request OPTIONS return 200 dengan CORS headers

## Troubleshooting

### Masalah: Masih error "Failed to fetch"
- ✅ Pastikan CORS handler di **AWAL** file, sebelum output apapun
- ✅ Pastikan tidak ada output (echo, print, whitespace) sebelum CORS headers
- ✅ Pastikan OPTIONS request return 200, bukan 404 atau 405

### Masalah: CORS headers tidak muncul
- ✅ Cek apakah mod_headers enabled (Apache)
- ✅ Cek apakah PHP output buffering tidak mengganggu
- ✅ Cek apakah ada error PHP sebelum headers dikirim

### Masalah: Preflight OPTIONS gagal
- ✅ Pastikan server menangani method OPTIONS
- ✅ Pastikan return 200 untuk OPTIONS request
- ✅ Jangan proses logic endpoint untuk OPTIONS request

## Security Note

⚠️ **Untuk Production:**
- Ganti `Access-Control-Allow-Origin: *` dengan domain spesifik:
  ```php
  header("Access-Control-Allow-Origin: https://yourdomain.com");
  ```
- Atau gunakan whitelist:
  ```php
  $allowedOrigins = ['https://yourdomain.com', 'https://app.yourdomain.com'];
  $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
  if (in_array($origin, $allowedOrigins)) {
      header("Access-Control-Allow-Origin: $origin");
  }
  ```

## Quick Fix

Copy file `cors-handler.php` dan include di setiap endpoint:

```php
<?php
require_once __DIR__ . '/cors-handler.php';

// Endpoint logic di sini...
```