# Devra Reload — REST API (agen)

Versi: **v1**  
Format: **JSON**  
Encoding: **UTF-8**

`<BASE>` = URL publik modul reload (tanpa slash di akhir). Produksi: `https://devra.my.id/reload` — samakan dengan `app.base_url` di `config.php`.

---

## Otentikasi

Setiap permintaan (kecuali OPTIONS) wajib menyertakan header:

| Header | Deskripsi |
|--------|-----------|
| `X-Api-Key` | Public API key agen (diberikan admin saat pembuatan akun) |
| `X-Api-Secret` | Secret agen (hanya ditampilkan sekali saat akun dibuat) |

Secret disimpan di server sebagai hash SHA-256; kirim nilai secret **plain text** di header (bukan hash).

Contoh:

```http
GET <BASE>/api/v1/balance.php HTTP/1.1
Host: devra.my.id
X-Api-Key: a1b2c3d4e5f6...
X-Api-Secret: f6e5d4c3b2a1...
```

Respons jika gagal autentikasi:

```json
{"success": false, "message": "unauthorized"}
```

HTTP status: **401**

---

## Ringkasan endpoint

| Metode | Path (relatif `<BASE>/api/v1/`) | Fungsi |
|--------|----------------------------------|--------|
| GET | `balance.php` | Saldo agen |
| GET | `products.php` | Daftar produk & harga jual (setelah markup Anda) |
| POST | `transaction.php` | Order prabayar (topup) |
| GET / POST | `status.php` | Cek ulang status transaksi **pending** (prabayar: ulang topup dengan ref sama ke Digiflazz — lihat catatan) |

---

## GET `/api/v1/balance.php`

**Respons sukses**

```json
{
  "success": true,
  "data": {
    "agent_code": "AG001",
    "balance": 150000.5
  }
}
```

---

## GET `/api/v1/products.php`

Mengembalikan produk aktif beserta **harga jual** yang berlaku untuk agen (termasuk override per agen jika diatur di database).

**Respons sukses**

```json
{
  "success": true,
  "data": [
    {
      "buyer_sku_code": "xld25",
      "product_name": "XL Data 25k",
      "category": "Data",
      "buyer_price": 24000,
      "sell_price": 26500
    }
  ]
}
```

| Field | Arti |
|-------|------|
| `buyer_price` | Referensi harga beli (sinkron dari Digiflazz / isi manual) |
| `sell_price` | **Harga yang dipakai untuk memotong saldo agen** |

---

## POST `/api/v1/transaction.php`

Body JSON:

| Field | Tipe | Wajib | Deskripsi |
|-------|------|-------|-----------|
| `ref_id` | string | Ya | ID unik dari sistem agen; untuk **idempotensi** — permintaan ulang dengan `ref_id` sama mengembalikan transaksi yang sama |
| `buyer_sku_code` | string | Ya | Kode produk (`buyer_sku_code` Digiflazz) |
| `customer_no` | string | Ya | Nomor tujuan (MSISDN / pelanggan) |

**Contoh**

```json
{
  "ref_id": "INV-2026-00001",
  "buyer_sku_code": "xld25",
  "customer_no": "081234567890"
}
```

**Respons sukses**

```json
{
  "success": true,
  "data": {
    "agent_ref_id": "INV-2026-00001",
    "devra_ref_id": "DVR...",
    "buyer_sku_code": "xld25",
    "customer_no": "081234567890",
    "price_sell": 26500,
    "price_buy": 25000,
    "status": "success",
    "rc": "00",
    "message": "Transaksi Sukses",
    "sn": "..."
  }
}
```

| `status` | Arti |
|----------|------|
| `pending` | Masih diproses di penyedia |
| `success` | Berhasil |
| `failed` | Gagal (saldo agen dikembalikan jika sudah terpotong) |

**Kesalahan umum**

| HTTP | `message` (contoh) |
|------|---------------------|
| 400 | `saldo tidak mencukupi` |
| 404 | `produk tidak tersedia atau nonaktif` |
| 422 | `ref_id, buyer_sku_code, customer_no wajib` |

Jika koneksi ke Digiflazz gagal, saldo akan dikembalikan dan `success` false dengan pesan error.

---

## POST `/api/v1/inquiry_pasca.php`

Cek tagihan pascabayar (`inq-pasca`) — dipakai panel saat `panel_proxy` mengarah ke API production. Body JSON:

| Field | Tipe | Wajib | Deskripsi |
|-------|------|-------|-----------|
| `buyer_sku_code` | string | Ya | SKU Digiflazz |
| `customer_no` | string | Ya | ID / nomor pelanggan |
| `ref_id` | string | Tidak | Dibuat otomatis jika kosong |
| `testing` | bool | Tidak | Mode testing Digiflazz |

Respons: `success` + `data` seperti response inquiry upstream; error `400` dengan `message` + `raw` opsional.

---

## GET atau POST `/api/v1/status.php`

Untuk transaksi dengan status **pending**, Anda dapat memanggil ulang (sesuai kebijakan Digiflazz untuk prabayar: **topup ulang dengan `ref_id` yang sama** — di sisi Devra ini dilakukan dengan mengirim ulang permintaan ke Digiflazz menggunakan referensi internal yang sama).

**GET**

```
<BASE>/api/v1/status.php?ref_id=INV-2026-00001
```

**POST** body JSON:

```json
{ "ref_id": "INV-2026-00001" }
```

`ref_id` di sini adalah **`agent_ref_id`** (bukan `devra_ref_id`).

---

## CORS

Endpoint mengizinkan header `X-Api-Key`, `X-Api-Secret`, `Content-Type` dan method **OPTIONS** untuk preflight.

---

## Keamanan

- Gunakan **HTTPS**.
- Jangan menyimpan API Secret di frontend atau repositori publik.
- Batasi IP agen (firewall / WAF) jika memungkina

---

## Webhook Digiflazz (server Devra)

**Panduan upstream Digiflazz:** [Webhooks — Dokumentasi Teknis Digiflazz](https://developer.digiflazz.com/api/buyer/webhook/) (header pengiriman, contoh payload prabayar/pascabayar, ping).

Agar status **pending** terbarui realtime (seperti di panel Digiflazz), daftarkan URL webhook di **Atur koneksi → API → Webhook** pada akun Digiflazz Anda:

```text
<BASE>/api/webhook/digiflazz.php
```

Contoh: `https://devra.my.id/reload/api/webhook/digiflazz.php`

- Isi **secret** webhook di panel Digiflazz, lalu isi field yang sama di `config.php`: `digiflazz.webhook_secret`. Header `X-Hub-Signature` akan diverifikasi (`sha1=` + HMAC-SHA1 dari body), sama seperti di dokumentasi Digiflazz.
- Event **ping** dari Digiflazz dijawab `200` dengan JSON `{"ok":true}`.
- Payload prabayar memuat `data.ref_id` yang sama dengan **`devra_ref_id`** (referensi ke Digiflazz). Transaksi yang dikenali akan diperbarui; jika status berubah dari **pending** ke **gagal**, saldo agen dikembalikan otomatis.

Detail tambahan (create/update event, User-Agent prepaid vs postpaid) mengikuti dokumentasi Digiflazz di tautan di atas; salinan HTML lokal ada di folder `DIGIFLAZZ/` proyek ini.

---

## Referensi Digiflazz

Detail teknis upstream (signature, webhook, kode RC): lihat file HTML di folder sibling **`DIGIFLAZZ/`** pada project ini.