# API Reference — Hotel POS + Toko

Base URL nanti setelah upload: `https://domainanda.com/api/`

Semua endpoint (kecuali `login.php` dan `setup.php`) butuh header:
```
Authorization: Bearer <token>
```

## Role & Permission
Role: `admin` (akses penuh semua modul), `frontoffice` (Hotel), `store` (Toko).
Aturan single-login (satu akun per role dalam waktu bersamaan) berlaku terpisah untuk
`frontoffice` dan `store` ketika `multi_login_enabled = 0`. Admin selalu bebas login kapan saja.

## Auth & User Management
| Endpoint | Method | Akses | Keterangan |
|---|---|---|---|
| `login.php` | POST | publik | body: `{username, password, device_info}` |
| `logout.php` | POST | login | invalidasi token aktif |
| `users.php` | GET/POST/PUT/DELETE | admin | kelola akun (role: admin/frontoffice/store); DELETE = nonaktifkan (revoke akses) |
| `force_logout.php` | POST | admin | body: `{user_id}` — paksa logout semua sesi aktif user tsb (mis. lupa logout) |

## Modul HOTEL
| Endpoint | Method | Akses | Keterangan |
|---|---|---|---|
| `categories.php` | GET/POST/PUT/DELETE | view: semua login; edit: admin | kategori pendapatan/pengeluaran |
| `subcategories.php` | GET/POST/PUT/DELETE | view: semua login; edit: admin | subkategori & kamar (`is_room`, `room_type_id`) |
| `room_types.php` | GET/POST/PUT/DELETE | view: semua login; edit: admin | tipe kamar: `base_price`, `max_guests`, `extrabed_price` |
| `transactions.php` | GET/POST/PUT/DELETE | lihat+tambah: admin & frontoffice; edit/hapus: admin | tambah transaksi kirim `cash_source` (front_office/kas_ditangan) & `guest_count` (utk hitung extrabed otomatis) |
| `rooms.php` | GET | login | `?summary=1` ringkasan, atau daftar lengkap kamar |
| `checkout.php` | POST | admin & frontoffice | body: `{subcategory_ids:[..]}` |
| `room_transfer.php` | POST | admin & frontoffice | body: `{from_subcategory_id, to_subcategory_id, confirm_extra_charge}`. Jika ada selisih harga, panggilan pertama mengembalikan `requires_confirmation:true` — panggil ulang dengan `confirm_extra_charge:true` untuk lanjut |
| `cash.php` | GET/POST | GET: login; POST (pindah kas): admin & frontoffice | GET = saldo Front Office (hari ini) & Kas Ditangan (akumulatif). POST body: `{amount, notes}` |
| `dashboard.php` | GET | admin & frontoffice | data halaman depan Hotel (termasuk saldo Front Office & Kas Ditangan) |
| `reports.php` | GET | admin | `?mode=compact\|full&start_date=&end_date=` |
| `export_transactions_csv.php` / `export_report_csv.php` | GET | admin | download CSV |
| `settings.php` | GET/POST | GET: login; POST: admin | pengaturan global (multi_login_enabled, price_editable, dst) |

## Modul TOKO
| Endpoint | Method | Akses | Keterangan |
|---|---|---|---|
| `store_categories.php` | GET/POST/PUT/DELETE | view: admin/frontoffice/store; edit: admin/store | kategori pendapatan/pengeluaran toko |
| `store_subcategories.php` | GET/POST/PUT/DELETE | view: admin/frontoffice/store; edit: admin/store | produk/subkategori, `price_umum` & `price_internal` |
| `store_employees.php` | GET/POST/PUT/DELETE | view: semua toko; edit: admin/store | nama karyawan (dipakai di Bon) |
| `store_stock.php` | GET/PUT | admin/store | GET = daftar stok gudang+etalase; PUT = update qty gudang manual |
| `store_stock_move.php` | POST | admin/store | body: `{subcategory_id, qty}` — pindah stok Gudang -> Etalase |
| `store_transactions.php` | GET/POST/PUT/DELETE | lihat+tambah: admin/frontoffice/store; edit/hapus: admin | POST dengan `payment_method:"bon"` pada income TIDAK masuk transaksi, otomatis ke `store_bons` (butuh `employee_id`) |
| `store_bons.php` | GET | admin/frontoffice/store | daftar bon (`?status=outstanding\|partial\|paid`, default: yang belum lunas) |
| `store_bon_pay.php` | POST | admin/frontoffice/store | body: `{bon_id, amount_paid}` — otomatis tercatat sbg Pendapatan Toko kategori "Pembayaran Bon" |
| `store_dashboard.php` | GET | admin/frontoffice/store | saldo kas toko (akumulatif), pendapatan/pengeluaran hari ini, 3 transaksi terakhir |
| `store_reports.php` | GET | admin/store | `?period=monthly\|yearly&year=2020-2045&month=1-12&mode=compact\|full`. Selalu menyertakan `daftar_bon` |
| `store_export_transactions_csv.php` / `store_export_report_csv.php` | GET | admin/store | download CSV (laporan menyertakan Daftar Bon) |

> Export PDF akan disediakan lewat webadmin (TCPDF) & Android (native) di tahap berikutnya.

## Backup & Restore (admin only)
| Endpoint | Method | Keterangan |
|---|---|---|
| `backup.php` | POST | body: `{source:"webadmin"\|"android"}` — buat file backup .sql bertanggal di folder `/backup` (root domain, di luar `/api`) |
| `backup_list.php` | GET | daftar riwayat backup |
| `backup_download.php` | GET | `?filename=...` — download file backup |
| `restore.php` | POST | multipart form, field `backup_file` — restore dari file .sql |

## Notifikasi Admin (push, opsional)
| Endpoint | Method | Keterangan |
|---|---|---|
| `register_device_token.php` | POST | body: `{fcm_token, notif_enabled}` — didaftarkan dari Android saat login/ganti setting notifikasi |

Setiap transaksi baru (Hotel & Toko) otomatis memanggil `notifyAdmins()` yang mengirim push
notification (Kategori, subkategori, jumlah) ke semua admin dengan `notif_enabled = 1`.
Fitur ini **aman meski belum di-setup** — akan diam (no-op) sampai file
`config/firebase-service-account.json` disediakan. Panduan setup Firebase menyusul di dokumen
instalasi Android.

## Offline-Sync (Android)
`transactions.php` dan `store_transactions.php` menerima field opsional **`client_uuid`**
(dibuat di Android saat transaksi diketik, sebelum tahu status internet). Jika `client_uuid`
yang sama dikirim ulang (retry otomatis setelah internet nyambung lagi), server mengenali dan
mengembalikan data yang sudah tersimpan alih-alih membuat duplikat — sehingga transaksi offline
aman untuk disinkronkan otomatis tanpa campur tangan user. Implementasi penyimpanan lokal +
antrian sinkron sepenuhnya di sisi Android (Room database + WorkManager), dibahas di tahap
pembangunan Android.

## Setup awal
1. Import `database/database.sql`, lalu `database/database_v2_additions.sql`, lalu `database/database_v3_additions.sql` (urutan penting).
2. Edit `api/config/database.php` dengan kredensial database Anda.
3. Buka `https://domainanda.com/api/setup.php` sekali untuk membuat akun admin (admin/admin), lalu hapus file tsb.
4. Login sebagai admin, buat akun `frontoffice` dan `store` sesuai kebutuhan lewat `users.php` atau webadmin.
5. Isi Master Data: kategori/subkategori Hotel (termasuk `room_types` & kamar), kategori/subkategori Toko, karyawan toko, stok gudang awal.

Detail step-by-step lengkap (cPanel, Android Studio, koneksi API) menyusul di dokumen instalasi akhir.