# Dokumentasi API & Rute Sistem MUAMAR

Sistem MUAMAR menyediakan antarmuka Web Responsive berbasis Blade dan endpoint RESTful API terproteksi.

---

## 1. Konvensi & Keamanan Rute
- **Mata Uang**: Semua nominal harga dan deposit menggunakan bilangan bulat IDR integer (contoh: `Rp 250.000` disimpan dan dikirim sebagai `250000`).
- **Waktu**: Semua parameter booking/sewa dikirim dalam format ISO 8601 atau `YYYY-MM-DD HH:mm:ss` dan dinormalisasi ke UTC di database.
- **CSRF Token**: Wajib disertakan pada semua form `POST`, `PUT`, `PATCH`, `DELETE` web (`_token`).
- **Rate Limiting**:
  - Auth: `6` percobaan per menit.
  - Search / Catalog: `60` request per menit.
  - Checkout & Booking: `10` request per menit.
  - Chat: `30` pesan per menit.
  - Reviews: `15` request per menit.
  - Webhook: `120` request per menit.

---

## 2. Katalog & Pencarian Publik
### `GET /catalog`
Mengambil daftar produk fisik, jasa MUA, dan rental tenda/alat.
- **Query Parameters**:
  - `q`: string (kata kunci pencarian)
  - `type`: `all` | `physical` | `service` | `rental`
  - `category`: string (slug kategori)
  - `min_price`: int
  - `max_price`: int
  - `sort`: `latest` | `price_asc` | `price_desc`

### `GET /catalog/{slug}`
Menampilkan detail produk/jasa/rental beserta variasi, slot ketersediaan (untuk MUA), atau kapasitas unit (untuk rental) dan ulasan pembeli.

### `GET /providers/map`
Menampilkan peta interaktif Leaflet untuk studio/toko MUA terdaftar yang mengaktifkan `is_location_public = true`.

---

## 3. Autentikasi & Onboarding
- `POST /register`: Pendaftaran customer baru (`name`, `email`, `phone`, `password`, `password_confirmation`).
- `POST /login`: Masuk ke akun (`email`, `password`, `remember`).
- `POST /logout`: Keluar dari sesi.
- `GET /provider/onboard`: Form pendaftaran menjadi vendor/MUA.
- `POST /provider/onboard`: Submit pendaftaran studio/bisnis MUA (`business_name`, `description`, `address`, `city`, `province`, `postal_code`, `latitude`, `longitude`, `is_location_public`, `phone`, `qris_active`, `cod_active`).

---

## 4. Keranjang & Checkout
- `GET /cart`: Menampilkan isi keranjang belanja yang dikelompokkan berdasarkan vendor.
- `POST /cart/add`:
  - Body:
    ```json
    {
      "product_id": 1,
      "product_variant_id": 2, // Opsional jika produk memiliki varian
      "quantity": 1,
      "booking_start": "2026-11-10 08:00:00", // Wajib untuk jasa/rental
      "booking_end": "2026-11-10 11:00:00"     // Wajib untuk rental
    }
    ```
- `PATCH /cart/{id}`: Memperbarui jumlah item dalam keranjang (`quantity`).
- `DELETE /cart/{id}`: Hapus item dari keranjang.
- `POST /checkout`:
  - Mengunci stok/slot secara atomik (`SELECT FOR UPDATE`).
  - Menghasilkan record `orders` dan memecah menjadi `vendor_orders` per studio.
  - Mengambil snapshot harga, nama item, varian, dan alamat pengiriman.
- `GET /orders/{orderNumber}/invoice`: Faktur pesanan interaktif.
- `GET /orders/{orderNumber}/print`: Format cetak/PDF nota resmi.

---

## 5. Booking Layanan & Scheduler Anti-Bentrok
- `GET /api/services/{id}/availability?date=YYYY-MM-DD&time=HH:mm`:
  - Mengembalikan status boolean ketersediaan slot spesifik.
- `GET /api/services/{id}/slots?date=YYYY-MM-DD`:
  - Mengembalikan daftar seluruh slot jam yang tersedia (memperhitungkan jam kerja, hari libur tentatif, durasi, buffer antar klien, dan hold aktif 10 menit).
- `GET /api/rentals/{id}/capacity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD`:
  - Mengembalikan kapasitas total, kapasitas sisa, dan status ketersediaan unit rental pada interval overlap.
- `PATCH /provider/bookings/{id}/complete`:
  - Provider menandai layanan rias telah selesai dilaksanakan.
- `PATCH /provider/rentals/{id}/pickup`:
  - Provider menandai perlengkapan telah diambil/diantar ke penyewa (`in_use`).
- `PATCH /provider/rentals/{id}/return`:
  - Provider menandai perlengkapan telah dikembalikan utuh (`returned`).

---

## 6. Payment Webhook Interface & COD
### `POST /api/payments/webhook`
Endpoint penerimaan status notifikasi pembayaran dari payment gateway resmi.
- **Headers**:
  - `Content-Type`: `application/json`
- **Request Payload**:
  ```json
  {
    "order_number": "MUAMAR-20261029-ABCD",
    "status_code": "200",
    "gross_amount": 750000,
    "transaction_status": "settlement",
    "signature_key": "SHA256(order_number + status_code + gross_amount + server_key)"
  }
  ```
- **Konfirmasi & Tolak COD**:
  - `PATCH /provider/orders/{vendorOrderId}/confirm-cod`: Konfirmasi terima uang tunai fisik.
  - `PATCH /provider/orders/{vendorOrderId}/reject-cod`: Tolak pesanan COD dan lepaskan inventaris/slot.

---

## 7. Messaging (Chat Antara Customer & Provider)
- `GET /conversations`: Daftar percakapan aktif pengguna.
- `GET /conversations/{id}`: Thread obrolan terisolasi (hanya customer & provider pemilik studio).
- `POST /conversations/start`: Inisiasi chat dari halaman detail produk/provider.
- `POST /conversations/{id}/messages`: Kirim pesan konsultasi.

---

## 8. Pengiriman & Fulfillment Vendor
- `PATCH /provider/orders/{vendorOrderId}/ship`:
  - Mengubah status ke `shipped`, mengisi `shipping_carrier` dan `tracking_number` (resi manual).
- `POST /provider/orders/{vendorOrderId}/tracking-update`:
  - Menambahkan catatan milestone posisi pengiriman ke `shipping_histories`.

---

## 9. Reviews & Ratings
- `POST /reviews`:
  - Syarat: Order item berstatus `completed` dan belum pernah diulas pembeli.
- `POST /reviews/{id}/reply`:
  - Provider pemilik studio membalas ulasan konsumen.

---

## 10. In-App Notifications
- `GET /notifications`: Daftar notifikasi pengguna (pesanan baru, update resi, chat, ulasan).
- `POST /notifications/{id}/read`: Tandai notifikasi spesifik telah dibaca.
- `POST /notifications/read-all`: Tandai seluruh notifikasi telah dibaca.

---

## 11. Administrasi & Moderasi Platform
- `GET /admin/dashboard`: Dashboard pengawasan GMV, statistik, dan transaksi seluruh vendor.
- `PATCH /admin/providers/{providerId}/verify`: Verifikasi resmi studio MUA.
- `PATCH /admin/providers/{providerId}/toggle-suspension`: Menangguhkan / mengaktifkan status studio.
- `PATCH /admin/products/{productId}/toggle`: Menangguhkan / mengaktifkan listing produk & jasa.
- `PATCH /admin/reviews/{reviewId}/toggle`: Menyembunyikan / menampilkan ulasan konsumen (moderasi).
- `POST /admin/categories`: Menambahkan kategori bertingkat.
- `DELETE /admin/categories/{categoryId}`: Menghapus kategori kosong.
- Semua aksi dicatat ke tabel `admin_audit_logs`.