apskel-pos-backend/docs/integration-enakgame.md

Integrasi EnakGame: Game Client (Phaser)

Untuk: tim game EnakGame (client Phaser) · Base URL: /api/v1 · Per: 9 Okt 2026

Kamu mengerjakan game EnakGame: game web (Phaser) yang dibuka aplikasi customer di dalam webview dari game_url sebuah game. Game inilah yang menjalankan satu kali main dari awal sampai akhir: memulai session (EnakCoin dipotong), menjalankan permainan, mengirim hasil, dan menampilkan hadiah. Jangan mengarang endpoint, field, atau aturan yang tidak tertulis di sini; kalau ada yang kurang jelas, tanyakan ke tim backend.

Pembagian tugas dengan aplikasi customer:

Aplikasi customer (integration-mobile-customer.md)	Game EnakGame (dokumen ini)
Login customer, menyimpan token	Menerima token dari aplikasi lewat bridge (§4); bila tidak ada, meminta customer login (§5)
Daftar game, membuka game_url di webview	Start session, main, complete, tampilkan hadiah
Saldo, riwayat, voucher, PIN	Memberi tahu aplikasi saat saldo berubah atau game ditutup

Alasan di balik aturannya ada di rfc-enakgame.md dan enakgame-prd.md.

---

1. Aturan yang tidak boleh dilanggar

1. Server yang menentukan hadiah. Game hanya mengirim hasil main: score, outcome, dan data. Jangan pernah mengirim jumlah hadiah. Kalaupun terkirim, backend mengabaikannya. Untuk spin, server yang mengundi segmennya.
2. Tampilkan hadiah dari response, bukan dari hitungan sendiri. Angka di layar akhir selalu reward_total dari backend.
3. Satu tap "Main" = satu Idempotency-Key. Retry memakai key yang sama.
4. Token customer adalah rahasia. Hanya didapat dari bridge atau dari login di game, disimpan di memori, tidak pernah ditaruh di URL, localStorage, sessionStorage, cookie, log, atau analytics. Begitu juga password customer. (session_id boleh disimpan di sessionStorage, §6.4.)
5. Tanpa token, jangan panggil API customer. Tampilkan layar login akun customer (§5.2).
6. Semua jumlah bilangan bulat. Tidak ada pecahan EnakCoin.
7. Main game tidak butuh PIN.

---

2. Daftar game

Game bukan daftar tetap di kode. Setiap game adalah data yang dibuat admin di backoffice per organisasi (nama, slug, game_url, biaya main, aturan hadiah) dan dibaca game lewat GET /customer/enakgame/games (§6.1). Satu game_url = satu game.

2.1 Game yang ada sekarang

Game	slug	Jenis hadiah (reward_type)	Body complete	Status
Spin Harian	spin	PROBABILITY: server mengundi segmen roda	{}	Backend siap. Panduan: §9

Runner, Memory, dan Puzzle hanya disebut sebagai contoh di PRD; belum ada spesifikasi, slug, atau aturan hadiahnya. Game baru harus didaftarkan dulu (§2.3) sebelum bisa dimainkan.

2.2 Jenis hadiah menentukan apa yang dikirim game

API customer tidak memberi tahu reward_type. Jenisnya disepakati saat game didaftarkan (§2.3), dan game dibangun untuk jenis itu.

reward_type	Hadiah dihitung dari	Body complete	Bila field-nya tidak dikirim
FIXED	Jumlah tetap per main	{}	–
SCORE_BASED	Rentang skor yang diatur admin	{ "score": 800 }	Hadiah 0
OUTCOME_BASED	Hasil main, mis. PERFECT, GOOD, FAIL	{ "outcome": "PERFECT" }	Hadiah 0. outcome yang tidak terdaftar juga 0
PROBABILITY	Undian server; peluang tidak pernah dikirim ke game	{}	–

Admin bisa mengubah besar hadiah kapan saja tanpa build game baru. Supaya game tetap benar bila admin juga mengganti jenisnya, kirim semua hasil yang dimiliki game: game berbasis skor selalu mengirim score, game berbasis hasil selalu mengirim outcome. Field yang tidak dipakai jenis hadiah aktif diabaikan.

2.3 Mendaftarkan game baru

Sepakati dengan tim backoffice, lalu admin membuatnya (integration-backoffice.md §8):

Yang disepakati	Contoh	Catatan
slug	runner	Huruf kecil, angka, -; unik per organisasi. Game memakainya untuk memeriksa dirinya (§6.1)
game_url	https://…/runner/index.html	URL build game; dibuka aplikasi di webview
version	1.0.0	Versi build
reward_type	SCORE_BASED	§2.2
Daftar outcome	WIN, LOSE	Hanya game OUTCOME_BASED; harus sama persis (huruf besar/kecil)
result_rules	max_score, min_duration_seconds, max_score_per_second	Hasil di luar batas ini mendapat hadiah 0 tanpa pemberitahuan (§6.3). Isi dengan skor dan durasi wajar game-mu
session_ttl_seconds	600	Batas waktu satu main. Harus lebih lama dari durasi main terpanjang, ditambah jeda jaringan
entry_cost	5	Ditentukan bisnis, minimal 1

---

3. Daftar API

Semua endpoint diawali api_base_url (dari init, §4, atau dari config build pada mode mandiri, §5.4), mis. https://api.example.com/api/v1. Selain login, semua wajib memakai header Authorization: Bearer <token>. Request ber-body memakai Content-Type: application/json.

#	Endpoint	Header tambahan	Body	Dipakai saat	Detail
0	POST /customer-auth/login	Tanpa Authorization	{ "phone_number", "password" }	Tidak ada token, atau token ditolak	§5.3
1	GET /customer/enakgame/games	–	–	Setelah ada token: biaya main, event, segmen roda	§6.1
2	POST /customer/enakgame/sessions	Idempotency-Key (wajib)	{ "game_id" }	Customer menekan Main; EnakCoin dipotong	§6.2
3	POST /customer/enakgame/sessions/:id/complete	–	{ "score"?, "outcome"?, "data"? }	Permainan selesai	§6.3
4	GET /customer/enakgame/sessions/:id	–	–	Pemulihan setelah reload, bila session_id tersimpan	§6.4
5	GET /customer/enakgame/sessions?game_id=&status=&page=&limit=	–	–	Pemulihan setelah reload, bila session_id tidak tersimpan	§6.4

Game tidak memanggil endpoint lain. Registrasi, saldo, riwayat, voucher, dan PIN adalah tugas aplikasi customer.

---

4. Bridge dengan aplikasi customer

Usulan. Bentuk bridge di bawah belum diimplementasikan di sisi mana pun. Sepakati dengan tim aplikasi customer sebelum mulai; aplikasi memakai kontrak yang sama (integration-mobile-customer.md §8.3).

Semua pesan berupa JSON string dengan field type.

• Game → aplikasi: window.EnakGameHost.postMessage(JSON.stringify(pesan)) (JavaScript channel webview bernama EnakGameHost).
• Aplikasi → game: aplikasi memanggil window.enakGame.receive(jsonString). Game wajib mendefinisikan fungsi ini sebelum mengirim ready.

Arah	type	Isi	Kapan
game → app	ready	–	Halaman game selesai dimuat
app → game	init	api_base_url, token, game_id	Jawaban atas ready. token boleh kosong bila customer belum login
game → app	balance_changed	coin_balance	Setelah start dan complete berhasil
game → app	close	–	Customer keluar dari game

Contoh init:

{ "type": "init", "api_base_url": "https://api.example.com/api/v1", "token": "eyJ…", "game_id": "8a1f…" }

Di dalam aplikasi, jangan memanggil API apa pun sebelum init diterima. Token yang kosong atau ditolak tidak dikembalikan ke aplikasi: game sendiri yang meminta customer login (§5.2). Tanpa aplikasi (browser biasa), game berjalan dalam mode mandiri (§5.4).

---

5. Koneksi ke API dan token

5.1 Bentuk response dan error

• Sukses: { "success": true, "data": { … }, "errors": null }.
• Gagal: { "success": false, "data": null, "errors": [{ "code", "entity", "cause" }] }. cause berbahasa Inggris; jangan tampilkan mentah ke customer.
• Contoh response di dokumen ini adalah isi data, kecuali yang menampilkan amplop lengkap (§6.4).

errors[0].code	HTTP	Arti	Yang dilakukan game
304 dengan entity auth_handler	400	Token tidak ada atau tidak berlaku	Layar login (§5.2)
304	400	Ditolak aturan bisnis	Lihat tabel per endpoint
303, 310	400	Request salah format	Bug di game; pesan umum
404	404	Game/session tidak ada atau bukan milik customer	Pesan "tidak ditemukan", kembali ke aplikasi
900	500	Error server	Retry (§8)

Backend tidak memakai HTTP 401. Token yang ditolak dijawab HTTP 400 dengan code 304, sama seperti penolakan bisnis; bedakan lewat entity: auth_handler untuk token, enakgame_service untuk aturan EnakGame.

5.2 Token tidak ada atau ditolak: customer login di game

Token didapat dari init (game dibuka dari aplikasi) atau dari login di game. Setiap kali tidak ada token yang berlaku, game menampilkan layar login akun customer (§5.3).

Keadaan	Cara mengenali	Yang dilakukan game
init datang dengan token	token terisi	Pakai token itu, tanpa layar login
init datang tanpa token	token kosong, null, atau tidak ada	Layar login
Dibuka tanpa aplikasi (browser biasa)	window.EnakGameHost tidak ada	Mode mandiri (§5.4), dimulai dari layar login
init tidak datang	Tidak ada init 5 detik setelah ready	Kirim ready sekali lagi. Masih tidak datang dalam 5 detik: mode mandiri (§5.4)
Token ditolak backend	HTTP 400, code 304, entity auth_handler	Layar login dengan pesan "Sesi kamu berakhir, silakan login lagi". Setelah login berhasil, ulangi request yang sama satu kali (body dan Idempotency-Key sama)
Token hasil login langsung ditolak lagi	Penolakan auth_handler kedua untuk request yang sama	Berhenti: "Login bermasalah, coba buka ulang game" dengan tombol Keluar. Jangan menampilkan login berulang-ulang
Customer login dengan akun lain	GET /sessions/:id untuk session tersimpan menjawab 404	Hapus session_id dari sessionStorage, tampilkan layar awal (§6.4)

Token ditolak sebelum apa pun diproses: start yang ditolak tidak memotong EnakCoin, dan complete yang ditolak tidak menyelesaikan session. Jadi aman mengulang request yang sama setelah login. Timer expires_at tetap berjalan selama customer login; complete setelah expires_at ditolak dan entry cost tidak dikembalikan (§7).

Token hasil login di game tidak dikirim ke aplikasi; aplikasi mengurus tokennya sendiri.

cause dari auth_handler hanya untuk debugging, jangan dicocokkan di kode:

cause	Penyebab
Authorization header is required	Header tidak dikirim. Bug di game: memanggil API sebelum ada token
Invalid authorization header format	Header bukan Bearer <token>
Invalid token: …	Token kedaluwarsa, rusak, atau dari environment lain (staging vs. produksi)
Invalid token type	Yang dipakai refresh token, bukan access token
Token is not valid, Customer ID not found in token, Phone number not found in token	Token bukan token customer yang sah

5.3 Layar login — POST /customer-auth/login

Form berisi nomor HP dan password akun customer, sama dengan akun di aplikasi. Endpoint ini tidak memakai header Authorization.

{ "phone_number": "6281234561234", "password": "rahasia123" }

Response lengkap, termasuk amplopnya. Token ada di data.data.access_token:

{
  "success": true,
  "data": {
    "status": "SUCCESS",
    "message": "Login successful.",
    "data": {
      "access_token": "eyJ…",
      "refresh_token": "eyJ…",
      "user": { "id": "…", "name": "Budi", "phone_number": "6281234561234", "birth_date": "2000-01-31" }
    }
  },
  "errors": null
}

• Pakai access_token saja. refresh_token ditolak endpoint customer dan belum ada endpoint refresh; abaikan dan jangan disimpan.
• Token hanya di memori (§1). Halaman dimuat ulang berarti login lagi, kecuali di dalam aplikasi yang mengirim token lewat init.
• Password hanya dipegang selama request login: jangan disimpan, di-log, atau dikirim ke analytics.
• user.name boleh ditampilkan, mis. "Main sebagai Budi", dengan tombol "Ganti akun" yang menghapus token dari memori lalu menampilkan login lagi.
• Nomor HP boleh ditulis 0812…, +62 812…, 62812…, atau 812… (spasi dan - boleh). Backend mengubahnya menjadi format baku 62812…, dan format itu juga yang dikembalikan di user.phone_number. Hanya nomor HP Indonesia (628…) yang diterima; selain itu ditolak invalid phone number format.
• Registrasi tidak ada di game. Tampilkan "Belum punya akun atau pendaftaran belum selesai? Lanjutkan di aplikasi."

code	entity	HTTP	Arti (cause)	Tampilan
304	customer_auth_service	400	Nomor HP tidak terdaftar atau password salah (invalid phone number or password), atau pendaftaran belum selesai (customer not properly registered)	"Nomor HP atau password salah."
304	request	400	Format salah: invalid phone number format, phone number is required, password is required	"Periksa nomor HP dan password." Cek juga di game sebelum mengirim
303	request	400	Body tidak lengkap	Bug di game
429	customer_auth_service	429	Terlalu banyak percobaan login untuk nomor ini; data.locked_until (RFC3339 UTC)	"Terlalu banyak percobaan. Coba lagi pukul {jam}." Nonaktifkan tombol Masuk sampai locked_until
900	–	500	Error server	"Gagal login, coba lagi."

Login yang gagal jangan diulang otomatis. Setiap nomor HP hanya boleh mencoba login 5 kali dalam 15 menit, berhasil maupun gagal; login yang berhasil memulai hitungan dari nol. Percobaan ke-6 ditolak 429 sampai 15 menit itu habis, juga bila password-nya benar. Batas ini berlaku untuk nomor HP, bukan perangkat, dan sama untuk aplikasi customer.

5.4 Mode mandiri (tanpa aplikasi)

Dipakai saat game dibuka di browser biasa, atau saat aplikasi tidak mengirim init (§5.2). Juga dipakai untuk development dengan config staging.

1. api_base_url diambil dari config build per environment (staging, produksi), bukan dari URL atau input customer.
2. Tampilkan layar login (§5.3).
3. Panggil GET /customer/enakgame/games dan ambil game dengan slug milik build ini; id-nya menjadi game_id. Tidak ada → "Game tidak tersedia untuk akun ini."
4. Lanjutkan seperti biasa: pemulihan session (§6.4), lalu layar awal.

Tanpa aplikasi tidak ada bridge: balance_changed dan close tidak dikirim, dan tombol Keluar kembali ke layar awal game.

5.5 Contoh helper API

Helper ini menangani token dari init, layar login, dan token yang ditolak:

let apiBaseUrl = CONFIG.apiBaseUrl; // config build per environment; init menimpanya
let gameId = null;                  // dari init; mode mandiri: dicari lewat slug (§5.4)
let token = null;                   // hanya di memori
let loginWaiters = [];              // request yang menunggu customer login

const hasHost = () => typeof window.EnakGameHost !== 'undefined';
const toHost = (msg) => hasHost() && window.EnakGameHost.postMessage(JSON.stringify(msg));

window.enakGame = {
  receive(raw) {
    const msg = JSON.parse(raw);
    if (msg.type !== 'init') return;
    apiBaseUrl = msg.api_base_url;
    gameId = msg.game_id;
    token = msg.token || null;      // kosong → layar login saat request pertama
    onInit();                       // pemulihan session (§6.4), lalu layar awal
  },
};

// Menampilkan layar login; selesai setelah customer berhasil login.
function waitForLogin(message) {
  return new Promise((resolve) => {
    if (loginWaiters.length === 0) showLoginScreen(message);
    loginWaiters.push(resolve);
  });
}

// Dipanggil tombol Masuk. Error dilempar ke layar login dan ditampilkan sesuai §5.3.
async function login(phoneNumber, password) {
  const res = await fetch(apiBaseUrl + '/customer-auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ phone_number: phoneNumber, password }),
  });
  const json = await res.json().catch(() => null);
  if (!json?.success) throw json?.errors?.[0] ?? { code: String(res.status) };
  token = json.data.data.access_token;
  hideLoginScreen();
  loginWaiters.splice(0).forEach((resolve) => resolve());
}

// Mengembalikan isi `data`, atau melempar errors[0]. Error jaringan ikut dilempar,
// lalu ditangani pemanggil sesuai §8.
async function api(method, path, { body, idempotencyKey } = {}) {
  for (let attempt = 0; ; attempt++) {
    if (!token) await waitForLogin(attempt === 0 ? null : 'Sesi kamu berakhir, silakan login lagi.');
    const headers = { Authorization: `Bearer ${token}` };
    if (body !== undefined) headers['Content-Type'] = 'application/json';
    if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
    const res = await fetch(apiBaseUrl + path, {
      method,
      headers,
      body: body === undefined ? undefined : JSON.stringify(body),
    });
    const json = await res.json().catch(() => null);
    if (json?.success) return json.data;
    const err = json?.errors?.[0] ?? { code: String(res.status) };
    if (err.entity === 'auth_handler' && attempt === 0) {
      token = null;                 // login lagi, lalu ulangi request yang sama sekali
      continue;
    }
    throw err;
  }
}

---

6. Alur satu kali main

init ─► token ada? tidak: login (§5.2) ─► cek session yang masih berjalan (§6.4)
     ─► GET /customer/enakgame/games ─► tampilkan biaya (dan roda, untuk spin)
     ─► tap Main ─► POST /customer/enakgame/sessions      (EnakCoin dipotong)
     ─► permainan berjalan (batas waktu: expires_at)
     ─► POST /customer/enakgame/sessions/:id/complete     (server menghitung hadiah)
     ─► tampilkan hadiah ─► main lagi atau close

6.1 Data game — GET /customer/enakgame/games

Mengembalikan semua game aktif organisasi customer. Ambil yang id-nya sama dengan game_id dari init; pada mode mandiri, yang slug-nya milik build ini (§5.4).

[
  {
    "id": "8a1f…",
    "slug": "spin",
    "name": "Spin Harian",
    "description": null,
    "thumbnail_url": "https://…/spin.png",
    "game_url": "https://…/spin/index.html",
    "version": "1.2.0",
    "entry_cost": 5,
    "session_ttl_seconds": 600,
    "events": [
      { "id": "…", "name": "Ramadan 2x", "banner_url": "https://…", "multiplier": 2, "bonus": null, "end_at": "2026-10-31T16:59:59Z" }
    ],
    "prizes": [
      { "entry": 1, "label": "Zonk", "amount": 0 },
      { "entry": 2, "label": "3 Coin", "amount": 3 },
      { "entry": 3, "label": "10 Coin", "amount": 10 },
      { "entry": 4, "label": "Jackpot", "amount": 50 }
    ]
  }
]

• entry_cost: EnakCoin per main. Tampilkan di tombol Main ("Main · 5 EnakCoin").
• events: event yang sedang berlaku, prioritas tertinggi dulu. Tampilkan sebagai label, mis. "2x hadiah sampai 31 Okt". multiplier 2 berarti hadiah dasar ditambah sekali lagi; bonus menambah sejumlah EnakCoin.
• prizes: hanya ada untuk game ber-reward PROBABILITY (spin). Urutan = urutan segmen roda. label bisa null. Bobot peluang tidak pernah dikirim.
• Game tidak ada di daftar → game sudah dinonaktifkan; tampilkan pesan dan close.
• slug bukan yang dibangun untuk build ini (mis. build spin menerima game runner) → game_url salah dipasang admin. Tampilkan "Game sedang tidak tersedia", close, dan laporkan ke tim backoffice.

6.2 Mulai — POST /customer/enakgame/sessions

Header Idempotency-Key wajib (maks. 50 karakter, mis. UUID v4). Buat key baru saat customer menekan Main; pakai key yang sama bila request diulang karena jaringan atau karena customer login ulang (§5.2).

{ "game_id": "8a1f…" }

{
  "session_id": "c0d3…",
  "game_id": "8a1f…",
  "entry_cost": 5,
  "expires_at": "2026-10-08T05:10:00Z",
  "coin_balance": 15,
  "replayed": false
}

• EnakCoin sudah terpotong. Kirim balance_changed dengan coin_balance.
• replayed: true: request ini mengulang start yang sudah berhasil; pakai session yang sama, EnakCoin tidak terpotong dua kali.
• expires_at: batas waktu mengirim hasil (default 10 menit sejak start, diatur per game). Tampilkan timer bila permainan bisa lama.

Penolakan 304 (cause)	Tampilan
not enough EnakCoin	"EnakCoin kamu kurang." Tombol kembali ke aplikasi
the game is not available	"Game sedang tidak tersedia."
the game has no active reward configuration	"Game sedang tidak tersedia."
no EnakGame budget is set for this period	"Game sedang tidak tersedia."
the customer is not active	"Akun tidak aktif."
this Idempotency-Key was already used to start another game	Bug di game: key dipakai ulang untuk game lain
the Idempotency-Key header is required / … at most 50 characters	Bug di game

6.3 Kirim hasil — POST /customer/enakgame/sessions/:id/complete

Kirim sekali saat permainan selesai, sebelum expires_at. Body berisi hasil saja, sesuai jenis hadiah game (§2.2):

Field	Tipe	Untuk
score	integer ≥ 0, opsional	Game berbasis skor
outcome	string, opsional	Game berbasis hasil, mis. "WIN", "PERFECT"
data	objek JSON, opsional, maks. 16 KB	Data tambahan untuk audit (durasi per level, dsb.)

Spin cukup mengirim {}. Game skor: { "score": 800 }. Game hasil: { "outcome": "WIN" }. Nilai outcome yang diterima ditentukan admin per game (§2.3).

{
  "session_id": "c0d3…",
  "status": "COMPLETED",
  "reward_total": 10,
  "reward": { "base": 5, "event": 5 },
  "coin_balance": 25,
  "limited_by": ["USER_DAILY"],
  "prize": { "entry": 2, "label": "3 Coin", "amount": 3 }
}

Field	Arti	Tampilan
reward_total	EnakCoin yang benar-benar masuk	Angka utama di layar hadiah
reward.base / reward.event	Hadiah dasar dan tambahan event	"5 + 5 bonus event"
coin_balance	Saldo EnakCoin setelah hadiah	Kirim balance_changed
limited_by	Batas harian yang memotong hadiah: USER_DAILY, GAME_DAILY, GLOBAL_DAILY	"Hadiah hari ini sudah mencapai batas"
prize	Untuk spin: segmen hasil undian. amount = hadiah dasar segmen, sebelum event dan batas	Hentikan roda di prize.entry
status	COMPLETED, atau REFUNDED bila game dinonaktifkan selama dimainkan	Lihat di bawah

• status: "REFUNDED" (refund_reason: "GAME_DEACTIVATED"): entry cost dikembalikan dan tidak ada hadiah. Tampilkan "Game sedang dihentikan, EnakCoin kamu dikembalikan."
• reward_total 0 bisa terjadi: hadiahnya memang 0 (mis. segmen Zonk), batas harian sudah habis, field yang dibutuhkan jenis hadiahnya tidak dikirim (§2.2), atau hasilnya tidak lolos validasi server (skor di atas batas, terlalu cepat selesai, outcome tidak dikenal). Server tidak memberi tahu alasan validasi; tampilkan hasil apa adanya.
• Mengirim ulang aman. Complete untuk session yang sudah selesai mengembalikan jawaban yang sama, tanpa hadiah dua kali. Tidak perlu Idempotency-Key.

Penolakan	Arti	Tampilan
304 the session has expired	Lewat expires_at	"Waktu bermain habis." (lihat §7)
304 data must be …	data bukan JSON atau lebih dari 16 KB	Bug di game
310	score bukan bilangan bulat atau outcome bukan string	Bug di game
404	Session tidak ada / milik customer lain	Pesan umum

6.4 Pemulihan setelah reload

Webview bisa memuat ulang halaman game (aplikasi ke background, memori habis, crash) saat customer sedang main. EnakCoin sudah terpotong, jadi game wajib menemukan lagi session-nya. Dua endpoint dipakai:

Satu session — GET /customer/enakgame/sessions/:id

{
  "id": "c0d3…", "game_id": "8a1f…", "status": "STARTED", "entry_cost": 5, "reward_total": 0,
  "started_at": "…", "expires_at": "…", "ended_at": null, "refund_reason": null
}

status: STARTED, COMPLETED, REFUNDED, atau EXPIRED. Response ini tidak memuat prize atau rincian hadiah; untuk itu kirim ulang complete (lihat di bawah).

Mencari session — GET /customer/enakgame/sessions?game_id=8a1f…&status=STARTED&limit=1

Response lengkap, termasuk amplopnya. Daftar session ada di data.data, terbaru di atas:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "c0d3…", "game_id": "8a1f…", "status": "STARTED", "entry_cost": 5, "reward_total": 0,
        "started_at": "…", "expires_at": "…", "ended_at": null, "refund_reason": null
      }
    ],
    "pagination": { "page": 1, "limit": 1, "total_count": 1, "total_pages": 1 }
  },
  "errors": null
}

Tidak ada session yang cocok: data.data berupa array kosong [] (tidak pernah null). Bentuk lain berarti error, bukan "tidak ada session". Semua query opsional: game_id, status (STARTED, COMPLETED, REFUNDED, EXPIRED), page, limit. status atau game_id yang tidak valid ditolak 304.

Bila pengecekan ini gagal (jaringan, 5xx), jangan menganggap tidak ada session: customer bisa terpotong EnakCoin dua kali. Tampilkan "Coba lagi" sampai berhasil.

Alurnya, setiap kali menerima init:

1. Simpan session_id di sessionStorage setiap kali start berhasil, dan hapus setelah hasilnya ditampilkan. session_id bukan rahasia; token tetap hanya di memori (§1).
2. Bila ada session_id tersimpan, panggil GET /sessions/:id. Bila tidak ada (mis. webview dibuka ulang dari awal), panggil GET /sessions?game_id=<game_id>&status=STARTED&limit=1.
3. Tindak lanjuti sesuai status:

Keadaan	Yang dilakukan game
STARTED, sekarang sebelum expires_at	Lanjutkan session itu: jangan start baru (EnakCoin akan terpotong lagi). Spin: langsung kirim complete {} dan tampilkan hasilnya. Game lain: progres main hilang, jadi mulai ulang permainan di session yang sama dengan timer sampai expires_at, lalu kirim complete. Complete setelah expires_at ditolak, jadi akhiri ronde otomatis dan kirim skor saat itu beberapa detik sebelum expires_at (mis. 5 detik, untuk jeda jaringan dan selisih jam perangkat)
STARTED, expires_at sudah lewat	Anggap selesai. Server mengubahnya menjadi EXPIRED (atau merefund bila complete sebelumnya gagal karena error server) dalam ±1 menit. Tampilkan "Waktu bermain habis", lalu customer boleh start baru
COMPLETED	Hasil sudah dihitung tapi mungkin belum ditampilkan. Kirim ulang POST /sessions/:id/complete dengan body apa saja ({}): server mengembalikan jawaban yang sama persis, termasuk prize, tanpa hadiah dobel. Tampilkan hasilnya
REFUNDED	"EnakCoin kamu dikembalikan."
EXPIRED	"Waktu bermain habis."
404 untuk session_id tersimpan	Session milik akun lain (customer berganti akun). Hapus session_id, lanjut seperti tidak ada session
Tidak ada session	Tampilkan layar awal seperti biasa

Riwayat main lengkap (tanpa filter) dipakai aplikasi customer, bukan game.

---

7. Batas waktu dan refund

Keadaan	Yang terjadi pada EnakCoin
Hasil dikirim sebelum expires_at	Entry cost terpakai, hadiah masuk
Customer menutup game / game crash, hasil tidak pernah dikirim	Session menjadi EXPIRED setelah expires_at. Entry cost tidak dikembalikan
Complete tertahan karena customer harus login ulang sampai expires_at lewat	Sama dengan di atas: EXPIRED, entry cost tidak dikembalikan
Complete gagal karena error server (5xx) dan tidak berhasil sampai expires_at	Session direfund otomatis (refund_reason: "SYSTEM_ERROR") dalam ±1 menit setelah expires_at
Game dinonaktifkan admin saat dimainkan	Session direfund (GAME_DEACTIVATED)

Karena itu kirim hasil segera setelah permainan selesai, sebelum animasi panjang. Saat customer menekan keluar di tengah permainan, tampilkan konfirmasi "EnakCoin yang sudah dipakai tidak kembali".

---

8. Retry dan jaringan

Request	Gagal karena jaringan / 5xx	Aturan
Start	Ulangi dengan Idempotency-Key yang sama	Key baru = potong EnakCoin lagi
Complete	Ulangi dengan body yang sama sampai berhasil atau expires_at lewat	Aman diulang
Token ditolak (entity auth_handler)	Bukan error jaringan; layar login (§5.2)	Setelah login, ulangi sekali
Login gagal	Tampilkan pesan (§5.3)	Jangan diulang otomatis

Gunakan backoff (mis. 1 s, 2 s, 4 s) dan tampilkan indikator "Menyimpan hasil…" selama complete diulang.

---

9. Spin

1. Gambar roda dari prizes (§6.1): satu segmen per entri, urut, dengan label (atau amount bila label null).
2. Tap Putar → start session (§6.2).
3. Mulai animasi berputar, lalu langsung kirim complete dengan {}.
4. Dari response, hentikan roda di segmen prize.entry, lalu tampilkan reward_total.

Jangan menentukan segmen sendiri lalu "mencocokkan" dengan server. Bila prize tidak ada di response, hasil tidak bisa ditampilkan sebagai roda; tampilkan reward_total saja.

---

10. Checklist

• Game baru sudah didaftarkan bersama tim backoffice (§2.3); slug diperiksa saat init (§6.1).
• Body complete sesuai jenis hadiah game (§2.2).
• Bridge sesuai kontrak §4 yang sudah disepakati dengan tim aplikasi.
• Token hanya di memori; tidak ada di URL, storage, log, atau analytics.
• Tanpa token tidak ada request; token kosong atau ditolak → layar login → ulangi request sekali (§5.2).
• Login memakai access_token; password tidak disimpan; nomor HP/password salah tampil sebagai pesan yang jelas (§5.3).
• Mode mandiri (§5.4): dibuka di browser atau init tidak datang → login, game_id dicari lewat slug.
• Pemulihan setelah reload (§6.4): session STARTED dilanjutkan, bukan start baru; COMPLETED ditampilkan lewat complete ulang.
• Biaya main dan label event tampil sebelum main.
• Satu Idempotency-Key per tap Main, dipakai ulang saat retry.
• Complete hanya mengirim score / outcome / data, tidak pernah hadiah.
• Hadiah di layar dari reward_total; limited_by dan REFUNDED ditangani.
• Spin berhenti di prize.entry.
• Complete diulang dengan aman saat gagal; timeout expires_at ditangani.
• balance_changed dikirim setelah start dan complete; close saat keluar.