RAEYE VIP

CORE API
POS INTEGRATION

Document Version 2.0 • Official Technical Specification

1. Overview

Dokumentasi ini merinci spesifikasi teknis untuk mengintegrasikan sistem Quinos POS dengan backend Raeye VIP. Data dalam dokumen ini adalah spesifikasi final yang sudah diimplementasikan pada server produksi.

2. Security Framework

Semua request wajib menggunakan protokol keamanan Bearer Token. Tanpa header ini, permintaan akan ditolak dengan status 401 Unauthorized.

Authorization: Bearer RAEYE_MAPI_2526

3. Field Dictionary

Parameter	Type	Description
`user_id`	string	Unique UID dari Firebase.
`wallet_balance`	int	Saldo utama uang elektronik (IDR). Dapat digunakan pembayaran penuh.
`points_balance`	int	Saldo Reward Poin (pts). Maksimal penggunaan 50% per transaksi.
`tier_name`	string	Nama level (ANUBIS, AEOLUS, MEDUSA, MEDUSA GOLD, AMUN RA, RA BIRD).
`total_bill`	int	Total belanja (termasuk tax/service).
`wallet_spent / wallet_used`	int	Nominal yang dipotong dari Wallet member. Pembayaran via Wallet (100% allowed) tidak akan mendapatkan Poin.
`points_spent`	int	Nominal (IDR) yang dipotong dari Poin member.

4. Loyalty Economy & Tiers

Cashback poin dihitung otomatis berdasarkan Bill Total (Closed Bill) sesuai Tier Member:

Rank	Cashback	Calculation
ANUBIS	5%	(Subtotal - Poin Dipakai - Wallet Dipakai) x 0.05
AEOLUS	10%	(Subtotal - Poin Dipakai - Wallet Dipakai) x 0.10
MEDUSA	15%	(Subtotal - Poin Dipakai - Wallet Dipakai) x 0.15
MEDUSA GOLD	15%	(Subtotal - Poin Dipakai - Wallet Dipakai) x 0.15
AMUN RA	15%	(Subtotal - Poin Dipakai - Wallet Dipakai) x 0.15
RA BIRD (VVIP)	20%	(Subtotal - Poin Dipakai - Wallet Dipakai) x 0.20

5. API Endpoints

5.1 Member Handshake

GET /v1/members/lookup?phone={no_wa}

{
  "status": "success",
  "data": {
    "user_id": "UID88",
    "full_name": "ERICK J",
    "tier_name": "RA BIRD",
    "wallet_balance": 5000000,
    "current_points": 1200000,
    "max_point_usage": 600000,
    "cashback_rate": 0.20
  }
}

5.2 PEMOTONGAN SALDO (Redeem / Burn)

POST /v1/pos/transaction

Endpoint ini digunakan Quinos untuk memotong saldo Wallet atau Poin member sebagai metode pembayaran.

{
  "user_id": "UID88",
  "method": "wallet", // or "points"
  "amount": 250000,
  "receipt_number": "QS-90"
}

5.3 PENAMBAHAN POIN (Earn Reward) & Pelaporan Struk

POST /v1/orders/history

Wajib dipanggil saat Bill di Quinos ditutup (Closed). Backend Raeye akan otomatis menghitung dan menambahkan poin reward ke akun member secara otomatis berdasarkan net subtotal.

{
  "user_id": "UID88",
  "method": "points",
  "type": "EARN",
  "subtotal": 1000000,
  "points_used": 0,
  "wallet_used": 0,
  "receipt_number": "QS-91"
}

6. Redemption Business Logic

Category	Rule	POS Implementation
Wallet Spending	Full Usage (100% incl. Tax)	Boleh dipotong sampai saldo Wallet Rp 0. Porsi yang dibayar menggunakan Wallet TIDAK MENDAPATKAN Poin.
Points Spending	Limit Usage (50%)	Maksimal potong poin adalah 50% dari total saldo point member.
Wallet Top-Up	Admin Only	POS dilarang melakukan penambahan saldo Wallet secara mandiri.

7. Case Studies / Simulation Flow

Case A: Pembayaran Sebagian Pakai Poin

Member Tier: MEDUSA (Cashback 15%)

Saldo Poin: 1.000.000 (Max potong 500.000)

Subtotal Belanja (Sblm Tax): Rp 1.000.000

Step 1: Tamu potong poin maksimal (Rp 500.000).

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

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

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

Case B: Pembayaran Full Cash / Kartu (Tanpa Poin)

Member Tier: MEDUSA (Cashback 15%)

Subtotal Belanja (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.

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

Case C: Pembayaran Menggunakan Wallet

Member Tier: MEDUSA (Cashback 15%)

Saldo Wallet: Rp 2.000.000

Subtotal Belanja (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: Poin baru tamu adalah (1.000.000 - 0 - 1.000.000) x 15% = 0 Poin (Bayar menggunakan Wallet = no point reward).

8. Error Codes Dictionary

Sistem akan mengembalikan pesan error dalam JSON saat gagal. Berikut kodenya:

HTTP Status	Kategori	Penjelasan Umum
`400 Bad Request`	Transaction Error	Poin melebihi limit 50%, saldo Wallet/Poin tidak cukup, atau parameter kurang (misal subtotal kosong).
`401 Unauthorized`	Security	Header `Authorization: Bearer` kosong atau salah/expired.
`404 Not Found`	Data Missing	Nomor HP tidak ditemukan atau user_id tidak valid di database.
`500 Internal Server Error`	System Crash	Kesalahan sistem di Backend Raeye (wajib lapor ke tim Raeye VIP).

9. Integration Success Checklist

Daftar periksa teknis untuk memastikan integrasi berjalan sempurna sebelum Go-Live:

	Handshake Success: Bisa narik data member via nomor WhatsApp di awal transaksi.
	Safety Validation: Sistem POS memblokir jika input pemotongan Poin > 50% dari saldo.
	Double-Debit Prevention: Request pemotongan hanya dikirim 1x per Bill.
	Final Report: Endpoint `/orders/history` wajib dipanggil di akhir agar user dapet cashback.
	Bearer Token: Semua header request mengandung `Authorization: Bearer ...`