Owner login dengan identifier dan password

Autentikasi owner via identifier (email ATAU klay_id) + password. Akun harus sudah di-create oleh admin Skalar saat onboarding. Berhasil = access token di body, refresh token di httpOnly cookie. Response data hanya berisi access_token (tidak ada nested user object).

Request body

{
  "identifier": "string",
  "password": "string"
}

Responses

Owner login dengan Google OAuth (BELUM DIIMPLEMENTASI)

Handler saat ini mengembalikan 501 Not Implemented (auth/handler.go GoogleLogin). Google OAuth login belum di-wire. Entri 200/403 di bawah adalah kontrak yang dimaksudkan tapi belum dibangun: dipanggil NextAuth setelah Google OAuth berhasil, server verifikasi email terdaftar sebagai owner, lalu issue JWT Klay sendiri.

Request body

{
  "email": "owner@klay.id",
  "name": "string"
}

Responses

Refresh access token

Baca refresh token dari httpOnly cookie, issue access token baru.

Responses

Logout

Hapus refresh token dari httpOnly cookie.

Responses

Profil owner yang sedang login

Mengembalikan profil owner beserta data business yang terkait.

Responses

Update profil owner

Owner update nama atau phone. Tidak bisa ubah email (admin Skalar only).

Request body

{
  "full_name": "string",
  "phone": "string"
}

Responses

Detail business owner yang login

Responses

Update info business (terbatas)

Owner hanya bisa ubah field display business. Field plan, features, max_operators, status, xendit_status — admin Skalar only.

Request body

{
  "business_name": "string",
  "phone": "string",
  "address": "string",
  "city": "string",
  "country": "string",
  "qris_string": "string",
  "category": "string"
}

Responses

List operator business

Daftar operator + info kuota. qr_token tidak dikembalikan di list, hanya saat create dan regenerate.

Responses

Tambah operator baru

Owner-only. Cap divalidasi terhadap business.max_operators (default 3, admin update kalo beli add-on, -1 = unlimited). Body hanya berisi name; server generate operator_code (KL-XXXXX), PIN, dan qr_token. operator_code dan credential (qr_token/pin) dikembalikan di response create/regenerate ini saja (one-time).

Request body

{
  "name": "string"
}

Responses

Detail satu operator

Parameters

Responses

Update operator (partial)

Owner update name atau is_active. Reset password dan QR di endpoint terpisah.

Parameters

Request body

{
  "name": "string",
  "is_active": true
}

Responses

Hapus operator (soft delete)

Soft delete — deleted_at di-set, row tetap ada. operator_code TIDAK dibebaskan (tetap tersimpan di row, slot unique index terpakai). Operator tidak bisa login lagi. Slot operator aktif berkurang (COUNT is_active turun). Data historis tetap valid.

Parameters

Responses

Regenerate qr_token operator

Issue qr_token baru. QR lama tidak valid untuk login baru, tapi sesi JWT yang masih aktif tetap berlaku sampai access token expired.

Parameters

Responses

Ambil operator_code + qr_token operator

Owner-only. Mengembalikan operator_code dan qr_token saat ini untuk re-render QR di dashboard tanpa regenerate.

Parameters

Responses

Rotate credential operator

Owner-only. Issue ulang qr_token dan PIN operator. Credential baru dikembalikan satu kali (one-time) di response ini.

Parameters

Responses

Paksa logout operator

Owner-only. Cabut sesi aktif operator (revoke refresh token). Mengembalikan 204 No Content saat sukses.

Parameters

Responses

Operator login dengan credential

Endpoint public. identifier (email atau klay_id business) me-resolve business; operator dicari via operator_code + PIN.

Request body

{
  "identifier": "string",
  "operator_code": "string",
  "pin": "string"
}

Responses

Operator login dengan QR scan

Endpoint public. qr_token statis, regenerate via owner.

Request body

{
  "qr_token": "string"
}

Responses

Profil operator yang sedang login (PWA operator)

Responses

List produk business

Owner & operator (RequireOperator) bisa GET. Handler hanya pakai business_id dari JWT; tidak ada query filter/sort/search yang diproses oleh server.

Responses

Tambah produk (owner only)

RequireOwner. business_id diambil dari JWT, bukan body.

Request body

Responses

Detail produk

Owner & operator (RequireOperator).

Parameters

Responses

Update produk (owner only, partial)

RequireOwner. Partial update — field yang tidak dikirim tidak berubah.

Parameters

Request body

Responses

Hapus produk (owner only)

RequireOwner.

Parameters

Responses

List order milik operator yang login

order.ListMyOrders (RequireOperator). Hanya order milik operator dari JWT. Kalau dipanggil owner (operator_id kosong) mengembalikan array kosong. Response adalah array Transaction langsung di `data`, BUKAN object berpaginasi.

Responses

Buat order baru (status DRAFT)

order.CreateOrder (RequireOperator). Status awal DRAFT. Backend hitung total_amount dari items dan snapshot product_name + unit_price ke order_items. operator_id diambil dari JWT (nullable kalau owner).

Request body

{
  "items": [
    {
      "product_id": "string",
      "quantity": 0
    }
  ],
  "note": "string"
}

Responses

Ganti items order DRAFT

order.UpdateItems (RequireOperator). Hanya valid saat status DRAFT.

Parameters

Request body

{
  "items": [
    {
      "product_id": "string",
      "quantity": 0
    }
  ],
  "note": "string"
}

Responses

Mulai checkout (DRAFT -> PENDING)

order.BeginCheckout (RequireOperator). Stamp checkout_started_at dan pindah status ke PENDING. Tidak ada request body. Wajib dipanggil sebelum confirm — confirm tanpa begin menghasilkan ErrCheckoutNotStarted (400).

Parameters

Responses

Konfirmasi checkout (PENDING -> CONFIRMED)

order.ConfirmCheckout (RequireOperator). Body wajib `payment_method`. Server menolak kalau begin-checkout belum dipanggil (ErrCheckoutNotStarted) atau gesture terlalu cepat <800ms sejak checkout_started_at (ErrGestureTooFast). Stamp confirmed_at + confirmed_by (string), lalu trigger consumption_log dari product.recipe. Response menyertakan qris_string saat payment QRIS_STATIC.

Parameters

Request body

{
  "payment_method": null
}

Responses

Void order (operator)

order.VoidOrder (RequireOperator). Tidak ada request body. Mengembalikan response.NoContent = HTTP 200 dengan body {"success":true} (BUKAN 204).

Parameters

Responses

Void order (owner)

order.VoidOrderByOwner (RequireOwner). Write mutation di domain order tapi di-mount di path /transactions/{id}/void. Body wajib `void_reason`. Owner identity diambil dari user_id JWT. Mengembalikan response.NoContent = HTTP 200 dengan {"success":true} (BUKAN 204).

Parameters

Request body

{
  "void_reason": "string"
}

Responses

List transaksi business (read-only log)

transaction.List (RequireOwner). Read-only history. status query menerima hanya DRAFT/CONFIRMED/VOIDED — PENDING ditolak 400 oleh validasi list-filter.

Parameters

Responses

Detail transaksi

transaction.GetByID (RequireOperator). Mengembalikan OrderWithItems (Transaction + items[]).

Parameters

Responses

List transaksi milik operator yang login

transaction.OperatorList (RequireOperatorOnly). Operator-scoped — hanya transaksi operator dari JWT. Filter: start_date, end_date, page, limit (tidak ada filter status/payment_method/operator_id di endpoint ini).

Parameters

Responses

Ringkasan performa business

Aggregate untuk dashboard. Count hanya status CONFIRMED.

Parameters

Responses

Tren transaksi harian

Parameters

Responses

Produk terlaris

Parameters

Responses

Distribusi jam tersibuk

Parameters

Responses

Analytics overview untuk custom date range

Dipakai di page Analytics, mendukung custom timeframe dan period comparison.

Parameters

Responses

Laporan penjualan harian

Aggregate transaksi CONFIRMED per hari pada tanggal tertentu.

Parameters

Responses

Laporan penjualan bulanan

Parameters

Responses

Laporan pemakaian bahan baku

Aggregate dari consumption_log per ingredient untuk periode. Foundation buat owner restock decision dan AI insight downstream.

Parameters

Responses

Export laporan ke PDF atau CSV

Generate file download. Server return URL temporary atau stream langsung. Type laporan dan periode di-passing via body.

Request body

{
  "type": "daily_sales",
  "format": "pdf",
  "period": {}
}

Responses

List insight cards

Rule-based MVP. Schema sudah siap untuk model_version + confidence kalau nanti switch ke AI engine.

Responses

Admin Skalar login

Request body

{
  "email": "owner@klay.id",
  "password": "string"
}

Responses

Refresh admin access token

Responses

Admin logout

Responses

Profil admin yang sedang login

Responses

List semua owners (cross-merchant)

Admin view. handler.ListOwners — hanya menerima page dan limit. Filter status/plan/q tidak diproses server (admin/handler.go).

Parameters

Responses

Onboard merchant baru

Create Business + User owner sekaligus. Body matches admin/model.go CreateBusinessRequest. business_id digenerate server.

Request body

Responses

Detail owner

Parameters

Responses

Update business info owner (admin-controlled fields)

Matches admin/model.go UpdateBusinessRequest. Field yang tidak dikirim tidak berubah. merchant_status enum: PENDING | REGISTERED | ACTIVE | SUSPENDED.

Parameters

Request body

Responses

Toggle aktif/suspend owner

handler.SetOwnerStatus — boolean toggle. enabled=true mengaktifkan, enabled=false mensuspend. Returns HTTP 200 { success: true } via response.NoContent().

Parameters

Request body

{
  "enabled": true
}

Responses

Set credential login owner (email dan/atau password)

handler.SetOwnerCredential. email opsional (jika dikirim harus valid email). password wajib, min 6 karakter. Returns HTTP 200 { success:true } via response.NoContent().

Parameters

Request body

{
  "email": "owner@klay.id",
  "password": "string"
}

Responses

List produk milik business

handler.ListOwnerProducts. Response membungkus products di dalam object { products: [...] } (bukan array langsung).

Parameters

Responses

Tambah produk untuk business

handler.CreateProduct. Body matches admin/model.go AdminCreateProductRequest. business_id diambil dari path param, bukan body.

Parameters

Request body

Responses

Detail produk (termasuk recipe)

handler.GetProduct. Returns AdminProductDetail yang menyertakan recipe array.

Parameters

Responses

Update produk (partial)

handler.UpdateProduct. Body matches admin/model.go AdminUpdateProductRequest. Semua field optional (pointer) — field tidak dikirim tidak berubah.

Parameters

Request body

Responses

Hapus produk

handler.DeleteProduct. Soft delete kalau produk sudah ada di transaksi historis. Returns HTTP 200 { success:true } via response.NoContent() (BUKAN 204).

Parameters

Responses

Replace recipe produk

handler.UpdateProductRecipe. Mengganti seluruh recipe array (bukan merge). Returns HTTP 200 { success:true } via response.NoContent() (BUKAN 204).

Parameters

Request body

{
  "recipe": [
    null
  ]
}

Responses

Hapus operator atas permintaan merchant

handler.DeleteOperator. Admin hanya bisa REMOVE operator on request. Tidak ada request body — handler tidak membaca body (admin/handler.go). Returns HTTP 200 { success:true } via response.NoContent() (BUKAN 204).

Parameters

Responses

List transaksi cross-merchant

handler.ListTransactions. Filter yang diproses: status (string), business_id (uuid), start_date (YYYY-MM-DD, filter created_at >= start), end_date (YYYY-MM-DD, filter created_at < end+1day), page (default 1), limit (default 20, max 100).

Parameters

Responses

Void transaksi (admin)

handler.VoidTransaction. Tidak ada request body — handler tidak membaca body. Returns HTTP 200 { success:true } via response.NoContent() (BUKAN 204). 409 dikembalikan jika transaksi bukan status PENDING/CONFIRMED (tidak bisa di-void).

Parameters

Responses