Integrasi Produk Baru

Prinsip integrasi

Produk baru di ekosistem Maubisa sebaiknya tidak membangun login, checkout, harga, invoice, dan aktivasi akses sendiri. Gunakan Pusat Akun untuk identitas dan pembayaran, Directus untuk konten publik yang perlu diedit, CDN untuk aset publik, dan produk masing-masing untuk logika domain.

Tujuannya adalah menjaga pengalaman pengguna konsisten dan mengurangi risiko duplikasi sistem kritis. Produk boleh berbeda stack, tetapi kontrak integrasi harus seragam.

Komponen integrasi

SSO handoff

Produk yang berada di bawah .maubisa.id harus mengarahkan pengguna ke Pusat Akun ketika sesi tidak ditemukan. Setelah login berhasil, pengguna dikembalikan ke produk melalui return path yang disepakati.

Pengguna membuka produk
  |
  v
Produk cek sesi
  |
  +-> sesi ada: tampilkan dashboard produk
  |
  +-> sesi tidak ada: redirect ke Pusat Akun dengan returnTo
                         |
                         v
                    login atau daftar
                         |
                         v
                    kembali ke produk

Return path harus berasal dari daftar domain yang dipercaya atau dibangun server-side. Jangan membuat open redirect dari query pengguna tanpa validasi. Pusat Akun hanya menerima tujuan kembali berupa path internal atau URL absolut dari origin ekosistem yang terdaftar.

Handoff pembayaran

Untuk produk berbayar, produk membuat tombol beli yang mengarah ke Pusat Akun dengan konteks. Konteks berupa kode produk atau kode acara, ditambah judul dan tujuan kembali bila perlu. Harga final tetap diambil oleh Pusat Akun dari database atau konfigurasi server.

Ada dua pintu masuk dengan parameter yang sama:

Parameter query yang dikenali:

Contoh konseptual:

const buyUrl = new URL("https://bayar.maubisa.id/beli");
buyUrl.searchParams.set("event", "kode-acara-berbayar");
buyUrl.searchParams.set("judul", "Judul Acara");
buyUrl.searchParams.set("redirect", "/terima-kasih");

window.location.href = buyUrl.toString();

Nama parameter mengikuti kontrak Pusat Akun yang berjalan. Contoh di atas menunjukkan pola, bukan izin untuk membuat endpoint baru tanpa kontrak.

Guest checkout acara

Situs Utama memakai guest checkout untuk acara berbayar anonim ketika href kosong dan integrasi akun aktif. Browser mengirim konteks event, lalu Pusat Akun mengambil harga dan memproses pembayaran. Jika pengguna sudah punya akun, Pusat Akun dapat mengaitkan pembelian sesuai alur yang tersedia.

Untuk editor atau partner acara, ini berarti href tidak wajib diisi. Hanya isi href jika acara memang memakai ticketing eksternal atau landing page partner yang sudah disetujui.

Acara juga bisa mendapat tautan pendek (format /e/<id>) yang otomatis mengarahkan ke halaman pendaftaran atau checkout yang benar. Tautan pendek ini lebih aman dibagikan lewat WhatsApp broadcast, bio Instagram, atau poster berisi QR code dibanding tautan panjang berisi parameter query, yang berisiko ter-encode ulang oleh aplikasi pihak ketiga.

Provisioning akses

Setelah pembayaran berhasil, aktivasi akses dilakukan dari server. Pusat Akun menerima webhook Midtrans, memvalidasi signature, status, order, dan amount, lalu menulis entitlement atau memanggil produk terkait.

Provisioning harus idempoten. Jika webhook atau request provisioning dikirim ulang, produk tidak boleh membuat akses ganda, invoice ganda, atau jadwal ganda. Simpan orderId, transactionId, atau entitlementId sebagai kunci idempotensi sesuai kontrak.

Midtrans webhook
  |
  v
Pusat Akun validasi order
  |
  +-> status tidak valid: abaikan atau tandai
  |
  +-> status valid: aktifkan entitlement
                      |
                      v
                 produk menerima akses

Integrasi Directus

Gunakan Directus untuk konten publik dan metadata yang perlu dikelola editor, misalnya halaman marketing, artikel, event, FAQ, atau media. Jangan memakai Directus sebagai jalur rahasia untuk menyimpan secret aplikasi, kredensial payment, atau token integrasi sensitif.

Produk dapat membaca konten dari Directus jika:

1. kontrak field sudah jelas,
2. token hanya memiliki izin yang diperlukan,
3. error CMS memiliki fallback aman,
4. konten HTML disanitasi sebelum dirender,
5. perubahan skema dikoordinasikan dengan editor dan developer.

Integrasi CDN dan file privat

Aset publik sebaiknya disajikan lewat cdn.maubisa.id. Jika produk menerima UUID file dari Directus, produk perlu memetakan file ke URL CDN sesuai kontrak yang ada, atau menggunakan helper yang disediakan di aplikasi terkait. Jangan menyusun URL media dengan menebak lokasi penyimpanan.

Skema jalur di CDN:

Aturan untuk file publik:

• Respons /media/* di-cache selama satu tahun dan ditandai immutable. Menimpa file dengan key yang sama tidak akan terlihat oleh pengguna yang sudah memiliki salinan lama.
• Untuk mengganti isi sebuah media, unggah sebagai file baru dengan UUID baru lalu perbarui rujukannya. Gunakan invalidasi cache CDN hanya bila penimpaan tidak bisa dihindari.

Aturan untuk file privat:

• Jalur /portal/* dan /private/* hanya melayani permintaan yang membawa waktu kedaluwarsa dan tanda tangan HMAC yang cocok. Tanpa itu, hasilnya 403.
• Tautan bertanda tangan dibuat di server aplikasi pemilik file, memakai helper yang disediakan aplikasi terkait. Rahasia penandatanganan tidak boleh sampai ke browser atau ke repository.
• Periksa hak akses pengguna saat tautan dibuat. Beri masa berlaku pendek (di Maubisa Lulus, 30 menit secara default), dan buat tautan baru tiap kali pengguna membuka dokumen, bukan menyimpan tautan lama.
• CV, dokumen akademik, invoice, dan file pribadi lain tidak boleh ditaruh di jalur publik.

Aplikasi mengunggah file langsung ke penyimpanan, bukan lewat CDN. CDN hanya dipakai untuk membaca.

Integrasi Maubisa Lulus

thesis.maubisa.id adalah produk Maubisa Lulus. Produk ini menerima identitas dan entitlement dari Pusat Akun sesuai kontrak. Untuk kebutuhan sesi online, jadwal, dan Google Meet, sumber kebenaran jadwal harus berada di server produk atau sistem operasional, bukan di payload browser.

Karena bimbingan skripsi berbasis konsultasi, alur pembelian dan aktivasinya seperti berikut:

1. Calon klien berkonsultasi dengan tim Maubisa.
2. Admin membuat tautan pembayaran untuk paket yang disepakati.
3. Pembayaran tervalidasi lewat webhook.
4. Entitlement dibuat dan akses diteruskan ke Maubisa Lulus.
5. Admin menugaskan tutor.
6. Klien masuk ke dashboard Lulus, dan jadwal serta sesi diatur di produk Lulus.
7. Saat admin menyelesaikan bimbingan, Pusat Akun mencatat komisi tutor.

Komisi dan payout (untuk mentor dan tutor)

Pencatatan komisi dan penarikan dana untuk mentor dan tutor terpusat di Pusat Akun (core), bukan di aplikasi spoke. Ini mengikuti prinsip "uang di core" (ADR-011 dan ADR-012): produk fokus pada pengalaman, sementara uang dikelola di satu tempat.

Sebutan peran mengikuti lini: tutor untuk lini Thesis (Maubisa Lulus) dan mentor untuk lini MBG+ (Maubisa Berkembang).

Sumber komisi dan aturan payout per lini

Saldo dihitung per lini dan tidak pernah digabung. Satu pengajuan penarikan berlaku untuk satu lini, dan tiap lini punya batas minimum serta syaratnya sendiri.

Alur pencatatan komisi

Komisi thesis dicatat langsung oleh Pusat Akun, bukan dikirim oleh aplikasi thesis.

Admin menyelesaikan bimbingan di panel Pusat Akun
  |
  v
Pusat Akun memanggil API admin thesis (tandai selesai)
  |
  v
Pusat Akun mencatat komisi 70% ke ledger
(satu baris per transaksi, aman dari pencatatan ganda)
  |
  v
Saldo tutor di lini Thesis bertambah

Komisi tidak dicatat saat sebuah sesi ditandai selesai. Pencatatan hanya terjadi sekali, ketika admin menyelesaikan bimbingan secara keseluruhan.

Alur penarikan (payout)

Mentor atau tutor buka /payouts di Pusat Akun
  |
  v
Lihat saldo per lini (Thesis dan MBG+ tidak digabung)
  |
  v
Simpan rekening bank (BCA, Mandiri, BRI, BNI)
  |
  v
Pilih lini lalu ajukan penarikan
(minimum sesuai lini, CAPTCHA bila diaktifkan)
  |
  v
Status "Menunggu", pemohon masih bisa membatalkan
  |
  v
Admin transfer manual, lalu tandai "Lunas" dan unggah bukti transfer,
atau tandai "Ditolak"

Penarikan dicairkan manual oleh admin lewat transfer bank, tidak ada pencairan otomatis. Pengajuan yang ditolak atau dibatalkan mengembalikan saldo ke lini yang bersangkutan.

Kontrak untuk produk spoke

• Produk spoke tidak menyimpan uang. Tidak ada tabel komisi atau payout di aplikasi produk.
• Produk spoke tidak mengirim event komisi ke Pusat Akun. Endpoint lama POST /api/commissions sudah dipensiunkan dan membalas 410 Gone secara permanen, jadi jangan dipakai.
• Untuk komisi thesis, API admin thesis cukup menyediakan daftar bimbingan berjalan yang memuat email klien dan tutor_core_user_id (referensi identitas tutor di hub), serta aksi tandai selesai yang idempoten. Tidak ada data finansial yang dikirim spoke.
• Jika suatu saat spoke perlu menulis ke hub, jalurnya harus lewat verifikasi token federasi (scope default-deny, issuer tepercaya, anti-replay), bukan shared secret statis.
• Mentor dan tutor melihat saldo dan mengajukan penarikan hanya di Pusat Akun. Produk spoke boleh menjelaskan model penghasilan dan menautkan ke Pusat Akun, tetapi tidak menampilkan saldo sendiri.

Urutan aksi lintas produk

Contoh aksi lintas produk untuk pembelian acara berbayar lewat guest checkout:

Pengguna di maubisa.id
  |
  | klik tombol beli acara
  v
bayar.maubisa.id/beli?event=...
  |
  | isi data diri dan pilih metode bayar
  v
Midtrans
  |
  | pembayaran berhasil
  v
Pusat Akun
  |
  | validasi webhook dan amount
  v
Pendaftaran atau entitlement dibuat
  |
  v
Email konfirmasi lewat hub notifikasi

Untuk bimbingan skripsi, urutannya berbeda karena tidak ada checkout mandiri:

Calon klien di maubisa.id
  |
  | konsultasi (WhatsApp)
  v
Admin membuat payment link
  |
  v
Midtrans
  |
  | pembayaran berhasil
  v
Pusat Akun
  |
  | validasi webhook dan amount, entitlement dibuat
  v
thesis.maubisa.id
  |
  | akses dashboard, tutor ditugaskan admin
  v
Klien mulai bimbingan

Yang dianjurkan dan dihindari

Checklist sebelum go-live

Langkah selanjutnya