🏪 Mirel Tower — Otak AI untuk Bisnis Anda

> Mirel Tower adalah platform API Services yang menyediakan kecerdasan buatan (AI) untuk aplikasi kasir, ERP, dan sistem bisnis Anda. Terpisah dari Mirel ERP & POS — bisa dipasang ke sistem apapun.

Base URL API: https://mirel.my.id/api

SDK GitHub: github.com/phyranyansen/Mirel-API-Services

Instalasi Composer: composer require mirel/tower-sdk

SDK Download: MirelTowerClient.php · mirel-tower-client.js

---

📋 Daftar Isi

1. 🏪 Pengenalan Solusi Mirel
2. 🤖 Layanan API Services — Katalog Fitur AI
3. 🚀 Panduan Integrasi Cepat — 3 Langkah Instan

---

🏪 Pengenalan Solusi Mirel

Mirel adalah ekosistem aplikasi bisnis pintar yang menggabungkan kasir modern, manajemen stok, akuntansi otomatis, dan kecerdasan buatan (AI) dalam satu platform terpadu.

Aplikasi Unggulan

| Produk | Fungsi |

| Mirel ERP & POS | Aplikasi kasir + manajemen toko lengkap dengan AI |

| Mirel Tower | API Services AI — otak AI yang bisa dipasang ke aplikasi manapun |

> Butuh aplikasi kasir lengkap? Lihat Mirel ERP & POS — sistem kasir pintar dengan modul pembelian, penjualan, stok, akuntansi, dan laporan keuangan siap pakai.

Yang Membedakan Mirel

• ✅ AI Bawaan — Scan faktur otomatis, deteksi kecurangan, proyeksi arus kas
• ✅ Mobile & Desktop — Bisa dipakai di Android, Windows, dan web
• ✅ API Terbuka — Integrasikan AI ke sistem eksisting Anda via REST API
• ✅ Offline-capable — Tetap jalan meski tanpa koneksi internet
• ✅ Multi-toko — Pantau semua cabang dari satu dashboard

---

🤖 Layanan API Services — Katalog Fitur AI

Mirel Tower menyediakan 18+ layanan AI yang bisa langsung dipanggil via REST API. Pilih sesuai kebutuhan bisnis Anda:

🌟 Untuk Semua Paket (Standard)

| Fitur AI | Fungsi |

| 🔍 Scan Faktur (OCR) | Membaca faktur & struk dari foto → JSON otomatis |

| 📦 Inisialisasi Bisnis | Setel data bisnis & produk baru sekali klik |

| 💬 AI Assistant | Tanya jawab seputar fitur Mirel (GRATIS, tanpa potong token) |

| 📊 Cek Saldo Token | Lihat sisa token AI kapan saja |

| 💰 Top-Up Token | Isi ulang token untuk pemakaian AI |

⚡ Untuk Paket Pro

| Fitur AI | Fungsi |

| 📒 Jurnal Akuntansi Otomatis | Buat jurnal dari transaksi harian — siap tutup buku |

| 🏦 Rekonsiliasi Bank | Cocokkan mutasi bank dengan invoice otomatis |

| 🔗 Pencocokan Transaksi | Temukan pasangan transaksi pembayaran & tagihan |

| 🗺️ Mapping COA | Petakan Chart of Accounts secara otomatis |

| 🚨 Deteksi Anomali Kasir | Temukan transaksi mencurigakan — cegah kecurangan |

| 🧮 Hitung Pajak | Hitung PPN & PPh otomatis dari transaksi |

| 💬 Query Data (NL) | Tanya data bisnis pakai bahasa sehari-hari (natural language) |

🚀 Untuk Paket Enterprise

| Fitur AI | Fungsi |

| 📈 Prediksi Permintaan Stok | Forecast kebutuhan stok 6 bulan ke depan |

| 📋 Wawasan Keuangan | Analisis profit, tren, dan kesehatan finansial |

| 📄 OCR / Parse Dokumen | Baca dokumen AP, AR, kontrak — jadi data terstruktur |

| 💵 Proyeksi Arus Kas | Simulasi arus kas toko untuk pengambilan keputusan |

| 😊 Analisis Sentimen | Ukur kepuasan pelanggan dari ulasan & feedback |

| 🛒 Rekomendasi Pembelian Cerdas | Saran pembelian stok berdasarkan data historis & tren |

> 💡 Tip: Baru mau coba? Semua fitur di atas bisa kamu tes di Mode Sandbox — GRATIS 100%, data simulasi, tanpa potong token. Lanjut ke Panduan Integrasi di bawah!

---

🚀 Panduan Integrasi Cepat — 3 Langkah Instan

> SDK kini tersedia via Composer dari GitHub — install, autoload, dan panggil.

---

Langkah 1: Install SDK

🔹 PHP — Via Composer (Rekomendasi)

`bash

composer require mirel/tower-sdk

Atau clone langsung dari GitHub:

```bash
git clone https://github.com/phyranyansen/Mirel-API-Services.git

Lalu di composer.json:

`json

{

"autoload": {

"psr-4": {

"Mirel\\TowerSdk\\": "path/to/Mirel-API-Services/src/"

}

}

}

Jalankan: `composer dump-autoload`

**🔹 PHP — Single File (Tanpa Composer)**

Download [`MirelTowerClient.php`](https://mirel.my.id/sdk/MirelTowerClient.php) langsung:

```php
<?php
require_once 'path/to/MirelTowerClient.php';

🔹 JavaScript / Node.js

Download mirel-tower-client.js:

`javascript

// Node.js — ES Module

import { MirelTowerClient } from "./mirel-tower-client.js";

// atau CommonJS

const { MirelTowerClient } = require("./mirel-tower-client.js");

```html
<!-- Browser — tinggal pake script tag -->
<script src="path/to/mirel-tower-client.js"></script>

---

Langkah 2: Inisialisasi & Pilih Mode

🔧 Mode Sandbox = Gratis 100% — semua response data simulasi, tidak memotong saldo. Cocok buat testing.

`php

<?php

require_once 'vendor/autoload.php'; // Composer autoload

use Mirel\TowerSdk\MirelTowerClient;

$client = new MirelTowerClient(

licenseKey: 'YOUR_LICENSE_KEY', // Bisa diisi apa saja untuk sandbox

apiKey: 'mirel_sandbox_dev_key', // ← "Saklar" Sandbox: awali dengan mirel_sandbox_

isSandbox: true

);

// Test koneksi

$usage = $client->validateAiUsage();

echo "Status: " . ($usage['mode'] ?? 'sandbox') . " — Siap!";

```javascript
const client = new MirelTowerClient({
  licenseKey: "YOUR_LICENSE_KEY",
  apiKey: "mirel_sandbox_dev_key", // ← Mode sandbox
  isSandbox: true,
});

const usage = await client.validateAiUsage();
console.log("Status:", usage.mode, "— Siap!");

🚀 Mode Production — Ganti API Key jadi mirel_live_* untuk AI beneran.

`php

$client = new MirelTowerClient(

licenseKey: 'LICENSE_KEY_ASLI',

apiKey: 'mirel_live_kunci_produksi_xyz', // ← Production

isSandbox: false

);

> **💡 Response `"mode": "sandbox"`** menandakan koneksi berhasil! Lanjut ke Langkah 3.

---

### Langkah 3: Panggil Fitur AI

Setelah terhubung, panggil method SDK sesuai kebutuhan. Ini 3 fitur andalan:

#### 🔍 Scan Faktur (OCR) — `analyzeFaktur()`

Otomatis baca faktur dari foto — output JSON siap pakai.

```php
<?php
$result = $client->analyzeFaktur('/path/to/invoice.jpg');

print_r($result['data']);
// {
//   "no_faktur": "INV-20260710-001",
//   "nama_supplier_mentah": "UD Sumber Makmur",
//   "total_nominal": 1575000,
//   "items": [
//     { "nama_barang_mentah": "Beras Ramos 5kg", "qty": 10 },
//     { "nama_barang_mentah": "Minyak Goreng 2L", "qty": 24 }
//   ]
// }

`javascript

// Browser: upload dari <input type="file">

const file = document.getElementById("invoiceUpload").files[0];

const result = await client.analyzeFaktur(file);

// Node.js: kirim path file

const result = await client.analyzeFaktur("/path/to/invoice.jpg");

#### 🚨 Deteksi Anomali Kasir — `detectAnomaly()`

Cegah kecurangan dengan AI yang mendeteksi transaksi mencurigakan.

```php
<?php
$result = $client->detectAnomaly([
    'transactions' => [...],
    'reference_period' => '2026-06-01 to 2026-06-30'
]);

echo "Anomali: " . $result['data']['anomalies_found'];

`javascript

const result = await client.detectAnomaly({

transactions: [...],

reference_period: "2026-06-01 to 2026-06-30",

});

console.log("Skor risiko:", result.data.risk_score);

#### 💵 Proyeksi Arus Kas Toko — `cashflowForecast()`

Prediksi arus kas & stok 6 bulan ke depan.

```php
<?php
$result = $client->cashflowForecast([
    'product_id' => 'PROD-001',
    'sales_history' => [
        ['date' => '2026-07-01', 'qty' => 15],
        ['date' => '2026-07-02', 'qty' => 12],
    ],
    'current_stock' => 50,
]);

echo "Stok aman: {$result['data']['safety_stock']}";
echo "Reorder point: {$result['data']['reorder_point']}";

`javascript

const result = await client.cashflowForecast({

product_id: "PROD-001",

sales_history: [{ date: "2026-07-01", qty: 15 }],

current_stock: 50,

});

console.log("Urgensi restock:", result.data.urgency);

---

### 🎯 Referensi Cepat

#### Kirim License Key

| Cara                           | Contoh                                  |
| ------------------------------ | --------------------------------------- |
| `X-License-Key` header         | `X-License-Key: KJ8F2M...abc123`        |
| `Authorization: Bearer` header | `Authorization: Bearer KJ8F2M...abc123` |
| JSON body                      | `{"license_key": "KJ8F2M...abc123"}`    |

> ⚠️ **Case-sensitive!** `KJ8F2M` ≠ `kj8f2m`.

#### Saklar Sandbox / Production

| `X-Mirel-API-Key` | Mode        | Biaya       |
| ----------------- | ----------- | ----------- |
| `mirel_sandbox_*` | **Sandbox** | ✅ Gratis   |
| `mirel_live_*`    | **Live**    | Pakai token |

#### Rate Limit (per 60 detik)

| Paket      | Batas Request |
| ---------- | ------------- |
| Standard   | 10            |
| Pro        | 20            |
| Enterprise | 60            |

> Kena **HTTP 429**? Tenang — tunggu beberapa detik, ulangi.

#### Error yang Sering Muncul

| Kode    | Artinya                | Solusi                         |
| ------- | ---------------------- | ------------------------------ |
| **401** | License key salah      | Cek key di dashboard           |
| **402** | Token habis            | Top-up atau tunggu reset bulan |
| **403** | Paket kurang memadai   | Upgrade paket                  |
| **429** | Terlalu banyak request | Tunggu bentar, ulangi          |

---

### ❓ FAQ

**"Gimana cara dapetin License Key?"**
Registrasi di portal klien Mirel. Dapatkan key setelah berlangganan paket.

**"Sandbox dan Production bedanya apa?"**
**Sandbox** = Gratis, data simulasi, buat testing. **Production** = AI beneran, potong saldo.

**"Token habis, gimana?"**
Fitur non-AI tetap jalan. Tinggal top-up atau tunggu reset bulanan.

**"SDK-nya support browser?"**
Ya! JS SDK support browser & Node.js.

**"Error 28 (Connection timeout)?"**
Pastikan server Anda bisa mengakses `https://mirel.my.id`. Cek firewall atau `ping mirel.my.id`.

---

> **Mirel Tower** — API Services AI untuk bisnis Anda.
>
> Terpisah dari Mirel ERP & POS. Bisa diintegrasikan ke sistem apapun.
>
> © 2026 Mirel Tower. All rights reserved.

      "coa_code": "4-1000",
      "coa_name": "Pendapatan",
      "debit": 0,
      "credit": 5000000
    },
    { "coa_code": "1-1000", "coa_name": "Kas", "debit": 5000000, "credit": 0 }

]
}

````

**Response (200):**

```json
{
  "status": "success",
  "message": "Jurnal berhasil diproses oleh Tower AI.",
  "data": {
    "journal_id": 42,
    "reference_no": "INV-20260710-001",
    "approval_status": "PENDING_APPROVAL",
    "is_ai_generated": 1
  }
}
````

### 6.2 Accounting Endpoints (`/api/v1/accounting`)

| Endpoint             | Method | Min. Tier | Deskripsi                 |
| -------------------- | ------ | --------- | ------------------------- |
| `process-journal`    | POST   | Pro       | Buat jurnal akuntansi     |
| `cleanup-duplicates` | POST   | Pro       | Bersihkan jurnal duplikat |

### 6.3 Guide Endpoints (`/api/v1/guide`)

| Endpoint         | Method | Min. Tier | Deskripsi                         |
| ---------------- | ------ | --------- | --------------------------------- |
| `sync`           | POST   | Standard  | Sinkronisasi fitur knowledge base |
| `stats`          | GET    | Standard  | Statistik penggunaan Guide        |
| `features`       | GET    | Standard  | Daftar fitur yang tersedia        |
| `update-feature` | POST   | Standard  | Update data fitur tertentu        |

### 6.4 System & Utility Endpoints

| Endpoint                        | Method   | Auth        | Deskripsi                                  |
| ------------------------------- | -------- | ----------- | ------------------------------------------ |
| `/api/v1/system-health/receive` | POST     | `X-API-Key` | Terima laporan kesehatan sistem dari klien |
| `/api/v1/bug-receiver`          | POST     | `X-API-Key` | Terima laporan bug dari aplikasi klien     |
| `/api/v1/rules/sync`            | GET/POST | License key | Sinkronisasi aturan tier & points          |

---

## 7. Rate Limiting & Kuota

### 7.1 Rate Limit per Paket

Rate limit diterapkan per **license key** dan diskalakan sesuai paket:

| Paket      | Request / 60 detik | Rekomendasi Delay      |
| ---------- | ------------------ | ---------------------- |
| Standard   | 10 request         | ~6 detik antar request |
| Pro        | 20 request         | ~3 detik antar request |
| Enterprise | 60 request         | ~1 detik antar request |

Saat limit terlampaui, API mengembalikan HTTP **429** dengan body:

```json
{
  "status": "error",
  "message": "Too many requests. Please wait.",
  "retry_after": 5
}

7.2 Token Quota

• Setiap panggilan AI mengurangi saldo token
• Biaya token per call: 1 token (konfigurasi AI_TOKEN_COST)
• Cek saldo via validate-ai-usage
• Top-up token via portal klien atau endpoint topup-confirm
• Saat saldo habis, API mengembalikan HTTP 402
• Untuk detail penanganan, lihat Circuit Breaker Pattern

---

8. Idempotensi

Kirim header X-Idempotency-Key untuk mencegah pemrosesan duplikat:

X-Idempotency-Key: stable-unique-string-anda

• Key yang sama + license + endpoint dalam 24 jam → response di-replay dari cache
• Tidak ada double token charge
• Cocok untuk retry saat network error

---

9. Error Handling

9.1 Envelope Error

Semua error mengembalikan format JSON konsisten:

`json

{

"status": "error",

"code": "ERROR_CODE",

"message": "Deskripsi error yang jelas."

}

### 9.2 Kode Error

| HTTP Code | Kode               | Arti                                | Solusi                     |
| --------- | ------------------ | ----------------------------------- | -------------------------- |
| **400**   | `BAD_REQUEST`      | Request tidak valid                 | Periksa parameter request  |
| **401**   | `INVALID_LICENSE`  | License key tidak valid/tidak aktif | Periksa license key        |
| **402**   | `TOKEN_EXHAUSTED`  | Kuota token habis                   | Lakukan top-up token       |
| **403**   | `UPGRADE_REQUIRED` | Paket tidak mencukupi               | Upgrade paket              |
| **403**   | `DOMAIN_MISMATCH`  | Domain tidak cocok                  | Daftarkan domain           |
| **404**   | `NOT_FOUND`        | Endpoint tidak ditemukan            | Periksa URL                |
| **409**   | `DUPLICATE_ENTRY`  | Data duplikat (idempotensi)         | Gunakan idempotency key    |
| **429**   | `RATE_LIMITED`     | Rate limit terlampaui               | Tunggu `retry_after` detik |
| **500**   | `INTERNAL_ERROR`   | Error server                        | Hubungi admin Tower        |

### 9.3 Pola Penanganan (Best Practice)

```php
// PHP
try {
    $result = $client->processJournal($data);
} catch (RuntimeException $e) {
    $message = $e->getMessage();

    if (str_contains($message, '402')) {
        // Token habis — aktifkan circuit breaker
        $this->circuitBreaker->open();
    } elseif (str_contains($message, '429')) {
        // Rate limit — tunggu dan retry
        sleep(6);
        $result = $client->processJournal($data);
    } else {
        // Error lain — log dan notifikasi
        log_message('error', 'API Tower Error: ' . $message);
    }
}

---

10. Circuit Breaker Pattern

Aplikasi klien (seperti Mirel ERP POS) HARUS menerapkan Circuit Breaker untuk menangani HTTP 402 (token habis) dari Tower.

State Machine

CLOSED (normal) → OPEN (token habis) → HALF_OPEN (coba lagi) → CLOSED

Logika Dasar

`php

// Pseudocode — Circuit Breaker

class AiCircuitBreaker {

private string $state = 'CLOSED'; // CLOSED | OPEN | HALF_OPEN

private int $failureCount = 0;

private int $threshold = 3; // Gagal 3 kali → OPEN

private ?int $lastFailureTime = null;

private int $timeout = 300; // 5 menit sebelum HALF_OPEN

public function canCall(): bool {

if ($this->state === 'OPEN') {

if (time() - $this->lastFailureTime > $this->timeout) {

$this->state = 'HALF_OPEN';

return true; // Izinkan 1 request percobaan

}

return false; // Blokir request

}

return true;

}

public function recordSuccess(): void {

$this->state = 'CLOSED';

$this->failureCount = 0;

}

public function recordFailure(): void {

$this->failureCount++;

$this->lastFailureTime = time();

if ($this->failureCount >= $this->threshold) {

$this->state = 'OPEN'; // Circuit terbuka

}

}

}

### Yang Harus Dilakukan Saat Circuit OPEN

- ⛔ **Blokir SEMUA panggilan API AI** (jangan hitung token lokal)
- ✅ **Fitur non-AI tetap berjalan normal** (POS, Gudang, Pembelian, dll.)
- 🔄 Tampilkan pesan: _"Fitur AI sedang tidak tersedia. Silakan lakukan top-up token."_
- ⏱ Coba lagi setelah interval tertentu (HALF_OPEN)

---

## 11. FAQ & Troubleshooting

### Q: Bagaimana cara mendapatkan license key?

Hubungi admin Mirel Tower atau registrasi di portal klien `https://tower.mirel.my.id/client/login`.

### Q: Apa bedanya Sandbox dan Production?

Sandbox mengembalikan data mock tanpa memanggil AI dan tanpa biaya. Production menggunakan AI sungguhan dan memotong token.

### Q: Berapa biaya per panggilan API?

1 token per panggilan AI. Token bisa dibeli melalui halaman top-up di portal publik.

### Q: Bagaimana jika token habis?

API mengembalikan HTTP 402. Implementasikan Circuit Breaker di sisi klien agar sistem tetap berjalan. Lakukan top-up token.

### Q: Apakah ada limit jumlah request?

Ya — lihat tabel Rate Limit di atas. Limit di-reset setiap 60 detik.

### Q: Domain saya tidak terdaftar, bagaimana?

Hubungi admin untuk mendaftarkan domain Anda. Pastikan license key dibuat dengan domain yang benar.

### Q: Apakah SDK mendukung browser?

Ya, JavaScript SDK mendukung browser (mengirim File/Blob untuk `analyzeFaktur`) dan Node.js (mengirim path file).

### Q: Error "cURL error 28" — Connection timeout?

Pastikan firewall tidak memblokir koneksi ke `https://mirel.my.id`. Coba perbesar nilai `CURLOPT_TIMEOUT` di SDK.

---

## Lampiran: Daftar File Referensi

| File                          | Lokasi        | Deskripsi                     |
| ----------------------------- | ------------- | ----------------------------- |
| `MirelTowerClient.php`        | `public/sdk/` | PHP SDK Client                |
| `mirel-tower-client.js`       | `public/sdk/` | JavaScript/Node.js SDK Client |
| `API.md`                      | `docs/`       | API Reference (versi ringkas) |
| `DEPLOYMENT_DUAL_MODE.md`     | `docs/`       | Panduan deployment dual-mode  |
| `AI_CIRCUIT_BREAKER_GUIDE.md` | `docs/`       | Panduan circuit breaker AI    |

---

> **Mirel Tower API Services** — Platform AI Microservices terintegrasi untuk finance, accounting, dan bisnis.
>
> Terpisah dari Mirel ERP & POS. API Services berdiri sendiri sebagai layanan REST API.
>
> © 2026 Mirel Tower. All rights reserved.