# BE Promo Simple Scan Flow

Tanggal: 2026-03-11

## Endpoint Tersedia

### 1) Simpan bundling sederhana

- `POST /api/v1/promos/bundling`
- Auth: `admin/superadmin`
- Payload:
  - `trigger_product_id` (required)
  - `min_qty` (required)
  - `reward_product_id` (required)
  - `reward_qty` (required)
  - `is_active` (optional, default `false`)
  - `start_at`, `end_at` (RFC3339, required)
  - `outlet_scope` (optional)
  - `priority` (optional, default `100`)
  - `is_stackable` (optional, default `false`)

### 2) List bundling

- `GET /api/v1/promos/bundling?trigger_product_id=&is_active=`
- Auth: `admin/superadmin`
- Query:
  - `trigger_product_id` (optional)
  - `is_active` (optional: `true/false/1/0`)
- Response item minimum:
  - `id`
  - `trigger_product_id`, `trigger_name`
  - `min_qty`
  - `reward_product_id`, `reward_name`
  - `reward_qty`
  - `status` (`active|inactive|expired`)

### 3) Cek promo saat scan

- Opsi A (aktif): metadata promo di produk
  - `GET /api/v1/products?search=...`
  - Tambahan field:
    - `has_promo`
    - `promo_name`
    - `promo_type` (`BUNDLING` untuk `BUY_X_GET_Y`)

- Opsi B (aktif): endpoint match bundling
  - `GET /api/v1/promos/bundling/match?product_id=&qty=&outlet_id=`
  - Auth: user login
  - Mengembalikan tier yang cocok terbaik berdasarkan `min_qty` tertinggi yang memenuhi.

### 4) Auto apply transaksi

- `POST /api/v1/pos/cart/price-preview`
- `POST /api/v1/pos/checkout`
- Rule tier bundling konsisten:
  - Untuk trigger yang sama, promo non-stackable memilih tier paling spesifik (`min_qty` tertinggi), tie-break `priority` lebih kecil.
  - Untuk promo `is_stackable = true`, rule boleh ter-apply lebih dari satu sesuai policy BE.

## Penegasan Multi-Tier

Untuk trigger product yang sama, BE mendukung banyak tier:

- Tier 1: `min_qty=1` -> reward B
- Tier 2: `min_qty=2` -> reward C
- Tier 3: `min_qty=3` -> reward D

Perilaku default:

- `is_stackable=false` -> ambil tier tertinggi yang terpenuhi.
- Jika tier sama (misalnya duplikat rule `min_qty=2`) -> ambil `priority` paling kecil.

## Catatan FE

- Saat scan item trigger, FE bisa langsung baca `has_promo` dari endpoint products.
- Saat qty berubah, FE bisa panggil endpoint `match` untuk prediksi tier cepat.
- Source of truth final tetap response `price-preview` dan `checkout`.

## Hasil Uji Live (2026-03-11)

- Qty trigger `1` -> reward tier min qty 1 (bonus B) ter-apply.
- Qty trigger `2` -> reward tier min qty 2 (bonus C) ter-apply (bukan tier min qty 1).
- Nilai transaksi di `price-preview` dan `checkout` identik (subtotal, discount total, grand total).