CORE API
POS INTEGRATION

Fase 1: Identifikasi Member

POS kasir menginput nomor WhatsApp customer. POS memanggil endpoint GET /v1/members/lookup untuk menarik user_id, sisa saldo Wallet, sisa Poin, dan Tier member. Data ini disimpan sementara di dalam memory POS untuk Bill tersebut.

Fase 2: Proses Pembayaran (Pemotongan)

Jika customer menggunakan saldo Wallet atau Poin sebagai pemotong tagihan, POS WAJIB memanggil endpoint POST /v1/pos/transaction dengan parameter "type": "SPENT". POS harus memverifikasi bahwa respons dari API Raeye adalah sukses sebelum struk dicetak.

Fase 3: Closed Bill & Penambahan Cashback (Wajib)

Setelah pembayaran dilunasi sepenuhnya dan Bill berstatus Closed, POS WAJIB memanggil POST /v1/pos/transaction dengan parameter "type": "EARN". Pada fase ini, POS mengirimkan nominal pembelanjaan (untuk dihitung cashback-nya) sekaligus dapat mengirimkan array items (daftar pesanan menu) dalam satu payload yang sama agar tersimpan di histori member.

Endpoint ini digunakan Quinos untuk memotong saldo Poin Loyalty atau saldo Wallet (Deposit) member saat proses pembayaran di kasir.

TABEL PARAMETER REQUEST (SPENT):

REQUEST PAYLOAD EXAMPLE (POTONG POIN):

Contoh format JSON untuk pemotongan poin member:

{
  "user_id": "UID88",
  "method": "points",
  "type": "SPENT",
  "amount": 50000, // Nominal poin yang ingin dipotong (Maksimal 50% dari subtotal)
  "subtotal": 200000, // Wajib (Khusus Poin): Nilai Sub Bill setelah diskon item, sebelum tax & service
  "receipt_number": "QS-INV-001"
}

RESPONSE SUCCESS EXAMPLE (POTONG POIN):

{
  "status": "success",
  "message": "Transaction Processed Successfully",
  "data": {
    "type": "SPENT",
    "method": "points",
    "value": 50000,
    "receipt": "QS-INV-001",
    "updated_user": {
      "user_id": "UID88",
      "full_name": "ERICK J",
      "tier_name": "SETH",
      "current_points": 1200000,
      "wallet_balance": 5000000
    }
  }
}

REQUEST PAYLOAD EXAMPLE (POTONG WALLET):

Format JSON untuk pemotongan saldo deposit Wallet member (bisa hingga 100% tagihan):

{
  "user_id": "UID88",
  "method": "wallet",
  "type": "SPENT",
  "amount": 250000, // Nominal rupiah saldo wallet yang dipotong
  "receipt_number": "QS-INV-001"
}

RESPONSE SUCCESS EXAMPLE (POTONG WALLET):

{
  "status": "success",
  "message": "Transaction Processed Successfully",
  "data": {
    "type": "SPENT",
    "method": "wallet",
    "value": 250000,
    "receipt": "QS-INV-001",
    "updated_user": {
      "user_id": "UID88",
      "full_name": "ERICK J",
      "tier_name": "SETH",
      "current_points": 1250000,
      "wallet_balance": 4750000
    }
  }
}

Wajib dipanggil saat Bill di Quinos ditutup (Closed). Endpoint ini berfungsi ganda: menghitung cashback secara otomatis berdasarkan subtotal (jika tidak menggunakan wallet), dan (opsional) menerima array items daftar pesanan menu untuk disimpan ke dalam history aplikasi member Raeye.

Fasilitas Khusus: Parameter total_bill bersifat opsional. Jika Quinos tidak mengirimkannya, sistem akan otomatis menyamakannya dengan subtotal agar perhitungan tier member berjalan akurat.

REQUEST PAYLOAD EXAMPLE:

{
  "user_id": "UID88",
  "method": "points",
  "type": "EARN",
  "total_bill": 1110000, // Total tagihan akhir (termasuk tax/service)
  "subtotal": 1000000, // Net sales setelah diskon item, sebelum tax/service
  "points_used": 50000, // Poin yang digunakan memotong bill (isi 0 jika tidak pakai poin)
  "wallet_used": 0, // Saldo wallet yang digunakan (jika > 0, cashback poin otomatis 0)
  "receipt_number": "QS-INV-001",
  "items": [
    {
      "name": "Wagyu Steak",
      "qty": 1,
      "price": 150000
    },
    {
      "name": "Ice Lemon Tea",
      "qty": 2,
      "price": 25000
    }
  ]
}

RESPONSE SUCCESS EXAMPLE:

{
  "status": "success",
  "message": "Transaction Processed Successfully",
  "data": {
    "type": "EARN",
    "method": "points",
    "value": 50000,
    "receipt": "QS-INV-001",
    "updated_user": {
      "user_id": "UID88",
      "full_name": "ERICK J",
      "tier_name": "SETH",
      "current_points": 1250000,
      "max_point_usage": 625000,
      "wallet_balance": 5000000
    }
  }
}
                    

Member Tier: SETH (Cashback 5%)

Subtotal Belanja (Setelah Diskon, Sblm Tax): Rp 1.000.000

Step 1: Tamu potong poin maksimal (Rp 500.000 = 50% dari Subtotal).

Step 2: Tamu bayar sisa Cash Rp 500.000 + Tax.

Step 3: Quinos lapor penambahan poin dengan data: subtotal: 1000000, points_used: 500000, wallet_used: 0.

Hasil Akhir: Poin baru tamu adalah (1.000.000 - 500.000) x 5% = 25.000 Poin.

Member Tier: ANUBIS (Cashback 10%)

Subtotal Belanja (Setelah Diskon, Sblm Tax): Rp 1.000.000

Step 1: Tamu bayar full Cash Rp 1.000.000 + Tax.

Step 2: Quinos lapor penambahan poin dengan data: subtotal: 1000000, points_used: 0, wallet_used: 0.

Hasil Akhir: Poin baru tamu adalah (1.000.000 - 0) x 10% = 100.000 Poin.

Member Tier: HORUS (Cashback 12.5%)

Saldo Wallet: Rp 2.000.000

Subtotal Belanja (Setelah Diskon, Sblm Tax): Rp 1.000.000

Step 1: Tamu bayar full pakai Wallet (bisa cover 100% tagihan beserta tax).

Step 2: Quinos lapor penambahan poin dengan data: subtotal: 1000000, points_used: 0, wallet_used: 1000000.

Hasil Akhir: Sesuai aturan bisnis, transaksi menggunakan saldo Wallet TIDAK MENDAPATKAN CASHBACK POIN (0 Poin). Namun, nominal belanja Rp 1.000.000 TETAP MENAMBAH AKUMULASI SPENDING MEMBER untuk syarat kenaikan tier.

Member Tier: RA (Discount 5%, Cashback 15%)

Subtotal Awal: Rp 1.000.000

Step 1 (POS Side): Quinos memberikan diskon langsung 5% (Rp 50.000).

Step 2 (POS Side): Tamu membayar tagihan berdasarkan subtotal baru: Rp 950.000 + Tax.

Step 3 (API Report): Quinos lapor ke Raeye dengan subtotal: 950000, wallet_used: 0.

Hasil Akhir (Raeye Backend): Member mendapatkan 15% dari 950rb = 142.500 Poin.