RAEYE

CORE API
POS INTEGRATION

Document Version 1.0 • Official Technical Specification

1. Overview

Dokumentasi ini merinci spesifikasi teknis untuk mengintegrasikan sistem Quinos POS dengan backend Raeye. 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 (SETH, ANUBIS, HORUS, AMUN RA, RA).
`discount_rate`	float	Besaran diskon langsung (0.00 - 1.00). Contoh: 0.05 untuk 5% diskon.
`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.
`type`	string	Wajib. Jenis transaksi: `SPENT` (potong saldo), `EARN` (tambah poin), atau `TOPUP` (isi saldo).

4. Loyalty Economy & Tiers

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

CHECKING SYSTEM CONNECTION...

Rank	Discount	Cashback	Calculation
SETH	0%	5%	(Subtotal) x 0.05
ANUBIS	0%	10%	(Subtotal) x 0.10 — Spend ≥ 20 Juta / 3 bulan
HORUS	0%	12.5%	(Subtotal) x 0.125 — Spend ≥ 100 Juta / 6 bulan
AMUN RA	0%	15%	(Subtotal) x 0.15
RA	5%	15%	(Subtotal - 5%) x 0.15

5. SOP / Alur Integrasi (Developer Workflow)

Untuk memberikan kejelasan menyeluruh bagi developer pihak ketiga (Third Party POS), berikut adalah alur kerja mutlak (lifecycle) dari saat Bill dibuka hingga ditutup (Closed Bill).

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.

6. API Endpoints

6.1 Member Handshake

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

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

6.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"
  "type": "SPENT", // Wajib: SPENT untuk memotong saldo
  "amount": 250000,
  "receipt_number": "QS-90"
}

6.3 PENAMBAHAN POIN & PELAPORAN STRUK (Earn Reward)

POST /v1/pos/transaction

Wajib dipanggil saat Bill di Quinos ditutup (Closed). Endpoint ini berfungsi ganda: menghitung cashback secara otomatis berdasarkan subtotal, 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",
  "subtotal": 1000000,
  "points_used": 0,
  "wallet_used": 0,
  "receipt_number": "QS-91",
  "items": [
    {
      "name": "Nasi Goreng",
      "qty": 1,
      "price": 50000
    }
  ]
}

RESPONSE SUCCESS EXAMPLE:

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

7. 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.

8. Case Studies / Simulation Flow

Case A: Pembayaran Gabungan (Cash + Poin)

Member Tier: SETH (Cashback 5%)

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 5% = 25.000 Poin.

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

Member Tier: ANUBIS (Cashback 10%)

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 10% = 100.000 Poin.

Case C: Pembayaran Menggunakan Wallet

Member Tier: HORUS (Cashback 12.5%)

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 12.5% = 0 Poin (Bayar menggunakan Wallet = no point reward).

Case D: VVIP Discount & Cashback Mix

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.

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

9. 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).

10. 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 `/pos/transaction` dengan type `EARN` wajib dipanggil di akhir agar user dapet cashback.
	Bearer Token: Semua header request mengandung `Authorization: Bearer ...`