Developer Documentation Read-Only Reference

API Reference

Referensi endpoint, skema, dan status implementasi SEMESTA ISLAM. Halaman ini mendokumentasikan sistem yang benar-benar ada, bukan kontrak yang diharapkan ada. Tidak ada eksekusi request, API key, autentikasi, atau integrasi cloud.

App v0.1.0Next.js ^15.1.3React ^19.0.0TypeScript ^5.7.2Prisma 6.2.1Zod ^3.24.1

Overview

Semua route API dibangun di atas /app/api/v1/** dengan validasi Zod dan ditulis ke PostgreSQL 16 (Prisma 6) dalam transaksi, termasuk jejak audit (audit_logs).

  • Status VERIFIED = endpoint terverifikasi secara empiris pada audit terakhir terhadap fresh database (lihat docs/implementation/POST_EXECUTION_VERIFICATION.md).
  • Status selain VERIFIED menunjukkan endpoint yang terdokumentasi namun tidak berfungsi sebagai route API saat ini (deferred / aspirasional).
  • Klaim autentikasi (Supabase Auth RBAC) dan rate limit (Upstash) pada docs/07_API_ENDPOINTS.md bersifat aspirasional; terblokir kredensial cloud. Identity saat ini diresolusi server-side (demo).

Drift kontrak yang tercatat:

  • Envelope sukses tidak memuat `meta` (07 §1.1).
  • Error envelope 400 memuat `details[]`; error bisnis hanya `{ success, statusCode, message }` (07 §1.2).
  • `X-Verifier-Role` header (OpenAPI) vs `verifierRoles` payload (runtime) — kontradiksi tercatat di docs/audit/CONTRACT_DRIFT_REPORT.md §2.3.
  • `qiraahType` semantic drift (Quran-anchored) — DECISION REQUIRED Founder.
  • Auth Supabase + Upstash rate limit = aspirasional (cloud block).
  • BookingInquirySchema.preferredSchedule: runtime min 3 (07 §3.2 menuliskan min 5).

API Reference

36 endpoints

Educators

3 endpoint

Direktori pendidik, profil & sanad.

GET/api/v1/educatorsDEFERRED

Direktori Pendidik

Pencarian & filter presisi direktori pendidik (dokumentasi 07 §2.3).

Akses / Role: Public (Upstash cached — klaim, belum ada)
Implementation Notes
  • Belum ada route API. Fungsi setara disajikan sebagai halaman server-rendered `/directory` yang dibackend Postgres (terverifikasi).
  • Klaim cache Upstash pada 07 bersifat aspirasional.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.3docs/implementation/POST_EXECUTION_VERIFICATION.md §1 (V6)
GET/api/v1/educators/:idDEFERRED

Detail Pendidik

Detail profil pendidik, silsilah sanad, & ulasan (dokumentasi 07 §2.3).

Akses / Role: Public
Implementation Notes
  • Belum ada route API. Fungsi setara disajikan sebagai halaman server-rendered `/educator/[id]` (DB-backed); ID tidak valid -> 404 via notFound().
Source / Evidence
docs/07_API_ENDPOINTS.md §2.3docs/implementation/POST_EXECUTION_VERIFICATION.md §1 (V6)
GET/api/v1/educators/:id/reviewsDEFERRED

Ulasan Pendidik

Daftar ulasan terverifikasi (dokumentasi 07 §2.3).

Akses / Role: Public
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.3docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)

Verification

5 endpoint

Pipeline verifikasi kredensial & sanad 4-lapis.

POST/api/v1/verification/submitVERIFIED

Submit Verifikasi Kredensial

Mengajukan verifikasi kredensial & sanad pendidik ke antrean Lajnah (status -> SUBMITTED).

Akses / Role: Authenticated Educator (identity demo diresolusi server-side hingga auth nyata ada)
RequestZod: VerificationSubmitSchema

Request Body

FieldTypeWajibDeskripsi
educatorIduuidYaID pendidik
ktpNumberstring (16 digit)YaNomor KTP
ktpDocumentUrlurlYaURL dokumen KTP (Lapisan 1)
ijazahDocumentUrlurlYaURL dokumen Ijazah (Lapisan 2)
ijazahSha256Hashstring (64 hex)YaFingerprint SHA-256 dokumen Ijazah
recommenderEmailemailYaEmail ulama/penyandang rekomendasi (Lapisan 3)
recommenderInstitutionstring (min 3)YaLembaga pemberi rekomendasi
qiraahSanadNamestringOpsionalNama sanad qiraah (opsional)
Response — 201

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
verificationRequestIduuidYaID permohonan baru
educatorIduuidYaID pendidik
status"SUBMITTED"YaStatus awal antrean
ijazahSha256Hashstring (64 hex)YaFingerprint tersimpan
recommenderEmailemailYaEmail rekomendasi
auditLoggedbooleanYaSelalu true; audit ditulis di transaksi
submittedAtISO 8601YaWaktu pengajuan
Known Status / Error Codes
400 VALIDATIONPayload tidak lolos VerificationSubmitSchema, atau format SHA-256 tidak valid (isValidSha256).
404 EDUCATOR_NOT_FOUNDeducatorId tidak ditemukan di educator_profiles.
409 ACTIVE_REQUEST_EXISTSSudah ada permohonan berstatus SUBMITTED / UNDER_REVIEW_LAJNAH untuk pendidik ini.
500 INTERNALInternal server error.
Implementation Notes
  • Security: `ijazahSha256Hash` diperiksa ulang format 64-hex sebelum diproses.
  • Menulis `verification_requests`, memperbarui `educator_profiles.verifiedStatus`, dan menulis `audit_logs` (VERIFICATION_SUBMITTED) dalam satu transaksi.
Source / Evidence
docs/implementation/POST_EXECUTION_VERIFICATION.md §1 (V7-V13) — diverifikasi ulang pada fresh database.src/app/api/v1/verification/submit/route.tssrc/lib/verification/service.ts
GET/api/v1/verification/statusVERIFIED

Status Verifikasi Pendidik

Membaca status antrean verifikasi terbaru untuk seorang pendidik.

Akses / Role: Educator / Founder (read-only)
RequestZod: VerificationStatusQuery

Query Parameters

FieldTypeWajibDeskripsi
educatorIduuidYaQuery parameter; ID pendidik
Response — 200

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
requestIduuidYaID permohonan
educatorIduuidYaID pendidik
statusenum(VerificationStatus)YaStatus terkini
layer1KtpUrlurl | nullYaURL dokumen KTP
layer2IjazahUrlurl | nullYaURL dokumen Ijazah
layer2Sha256Hashstring | nullYaFingerprint SHA-256
recommenderEmailemail | nullYaEmail rekomendasi
reviewNotesstring | nullYaCatatan telaah Lajnah
ethicsScorenumberYaSkor etika Lapisan 4
createdAtISO 8601YaWaktu dibuat
updatedAtISO 8601YaWaktu diperbarui
Known Status / Error Codes
400 VALIDATION`educatorId` bukan UUID valid.
404 NOT_FOUNDBelum ada permohonan verifikasi untuk pendidik ini.
500 INTERNALInternal server error.
Implementation Notes
  • Mengembalikan permohonan terbaru (`updatedAt` desc) untuk educatorId.
Source / Evidence
docs/implementation/POST_EXECUTION_VERIFICATION.md §1 (V7-V13) — diverifikasi ulang pada fresh database.src/app/api/v1/verification/status/route.tssrc/lib/verification/service.ts
POST/api/v1/verification/reviewVERIFIED

Telaah Lajnah

Transisi status verifikasi oleh Lajnah (guard role + state machine + stale-check currentStatus terhadap DB).

Akses / Role: LAJNAH_VERIFIER atau FOUNDER_ADMIN (identity diresolusi server-side dari session)
RequestZod: LajnahReviewSchema

Request Body

FieldTypeWajibDeskripsi
verificationRequestIdstring (min 1)YaID permohonan verifikasi
currentStatusenum(VerificationStatus)YaStatus yang diklaim klien (stale-check terhadap DB)
targetStatusenum(VerificationStatus)YaStatus tujuan
reviewNotesstring (min 5)YaCatatan telaah
ethicsScorenumber (0-100)OpsionalSkor etika, default 100
Response — 200

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
verificationRequestIduuidYaID permohonan
verifierUserIduuidYaID verifikator
previousStatusenum(VerificationStatus)YaStatus sebelum transisi
newStatusenum(VerificationStatus)YaStatus setelah transisi
reviewNotesstringYaCatatan telaah
ethicsScorenumberYaSkor etika
auditLoggedbooleanYaSelalu true
reviewedAtISO 8601YaWaktu telaah
Known Status / Error Codes
400 VALIDATIONPayload tidak lolos LajnahReviewSchema (mis. reviewNotes < 5 karakter).
403 FORBIDDENRole session server-side bukan LAJNAH_VERIFIER / FOUNDER_ADMIN.
404 NOT_FOUNDPermohonan verifikasi tidak ditemukan.
409 CONFLICTTransisi tidak valid menurut state machine, ATAU currentStatus basi (tidak cocok dengan status di DB).
500 INTERNALInternal server error.
Implementation Notes
  • State machine: DRAFT -> [SUBMITTED] · SUBMITTED -> [UNDER_REVIEW_LAJNAH, REJECTED] · UNDER_REVIEW_LAJNAH -> [VERIFIED, REJECTED] · VERIFIED -> [REVOKED] · REJECTED -> [SUBMITTED] · REVOKED -> [SUBMITTED]
  • Stale-check: DB adalah sumber kebenaran; `currentStatus` klien yang basi ditolak 409.
  • Menulis `verification_requests`, `educator_profiles.verifiedStatus`, dan `audit_logs` (VERIFICATION_REVIEWED) dalam satu transaksi.
Source / Evidence
docs/implementation/POST_EXECUTION_VERIFICATION.md §1 (V7-V13) — diverifikasi ulang pada fresh database.src/app/api/v1/verification/review/route.tssrc/lib/verification/service.tssrc/lib/verification/stateMachine.ts
POST/api/v1/verification/resubmitVERIFIED

Resubmit Verifikasi

Mengajukan ulang verifikasi setelah ditolak (REJECTED -> SUBMITTED).

Akses / Role: Authenticated Educator (identity demo diresolusi server-side)
RequestZod: VerificationSubmitSchema (+ verificationRequestId, currentStatus)

Request Body

FieldTypeWajibDeskripsi
verificationRequestIduuidYaID permohonan yang akan diajukan ulang
currentStatusenum(VerificationStatus)OpsionalStatus yang diklaim; default "REJECTED"
educatorIduuidYaID pendidik
ktpNumberstring (16 digit)YaNomor KTP
ktpDocumentUrlurlYaURL dokumen KTP (Lapisan 1)
ijazahDocumentUrlurlYaURL dokumen Ijazah (Lapisan 2)
ijazahSha256Hashstring (64 hex)YaFingerprint SHA-256 dokumen Ijazah
recommenderEmailemailYaEmail ulama/penyandang rekomendasi (Lapisan 3)
recommenderInstitutionstring (min 3)YaLembaga pemberi rekomendasi
qiraahSanadNamestringOpsionalNama sanad qiraah (opsional)
Response — 200

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
verificationRequestIduuidYaID permohonan
status"SUBMITTED"YaStatus setelah resubmit
ijazahSha256Hashstring (64 hex)YaFingerprint baru
resubmittedAtISO 8601YaWaktu resubmit
Known Status / Error Codes
400 VALIDATION`verificationRequestId` hilang atau payload submit tidak valid.
404 NOT_FOUNDPermohonan verifikasi tidak ditemukan.
409 CONFLICTStatus di DB tidak cocok dengan currentStatus, atau transisi dari status tersebut ke SUBMITTED tidak valid.
500 INTERNALInternal server error.
Implementation Notes
  • Hanya REJECTED -> SUBMITTED dan REVOKED -> SUBMITTED yang valid untuk resubmit (state machine).
  • Menulis audit VERIFICATION_RESUBMITTED.
Source / Evidence
docs/implementation/POST_EXECUTION_VERIFICATION.md §1 (V7-V13) — diverifikasi ulang pada fresh database.src/app/api/v1/verification/resubmit/route.tssrc/lib/verification/service.ts
POST/api/v1/verification/confirm-tokenDEFERRED

Konfirmasi Token Rekomendasi

Verifikasi token rekomendasi ulama via email (dokumentasi 07 §2.5).

Akses / Role: Public (Token-bound)
Implementation Notes
  • Belum ada kode. Membutuhkan infrastruktur email/token yang belum tersedia; ditunda pasca-MVP.
  • Tidak direpresentasikan sebagai berfungsi.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.5docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)

Bookings

3 endpoint

Booking inquiry & konfirmasi (virtual ledger).

POST/api/v1/bookings/inquireVERIFIED

Inquiry Booking

Pengajuan multi-step booking inquiry + alokasi poin virtual ledger.

Akses / Role: Authenticated Learner (identity demo: seeded learner `10000000-...-0001`, diresolusi server-side)
RequestZod: BookingInquirySchema

Request Body

FieldTypeWajibDeskripsi
educatorIduuidYaID pendidik tujuan
courseIduuidOpsionalID program (opsional)
scheduleIduuidOpsionalID jadwal (opsional)
learningMethodenum(ONLINE_ZOOM | PRIVATE_HOME | GROUP_MAJELIS)YaMetode belajar
preferredSchedulestring (min 3)YaPreferensi jadwal
learnerNamestring (min 2)YaNama pembelajar
contactPhonestring (regex ^(\+62|08)[0-9]{8,12}$)YaNomor WhatsApp/HP Indonesia
notesstring (max 500)OpsionalCatatan tambahan
Response — 201

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
bookingIduuidYaID booking baru
learnerNamestringYaNama pembelajar
learningMethodenum(LearningMethod)YaMetode belajar
preferredSchedulestringYaPreferensi jadwal
ledgerPointsEarnednumberYaPoin yang dialokasikan (50)
invoiceStatusstringYaStatus invoice dari MockPaymentGatewayAdapter ("PAID")
Known Status / Error Codes
400 VALIDATIONPayload tidak lolos BookingInquirySchema (mis. contactPhone format +62/08).
404 EDUCATOR_NOT_FOUNDeducatorId tidak ditemukan di educator_profiles.
500 INTERNALInternal server error.
Implementation Notes
  • Menulis `booking_requests` (status PENDING), `economic_ledgers` (LEARNER_POINT 50), dan `audit_logs` (BOOKING_INQUIRED) dalam satu transaksi.
  • Invoice dibuat via MockPaymentGatewayAdapter (pratekonfigurasi per docs); status "PAID".
  • learnerUserId tidak dikirim klien; diresolusi server-side (DEMO_LEARNER_USER_ID) hingga auth nyata ada.
Source / Evidence
docs/implementation/POST_EXECUTION_VERIFICATION.md §1 (V7-V13) — diverifikasi ulang pada fresh database.src/app/api/v1/bookings/inquire/route.tssrc/lib/bookings/service.ts
POST/api/v1/bookings/confirmVERIFIED

Konfirmasi Booking

Konfirmasi booking PENDING oleh pendidik pemilik atau founder (PENDING -> CONFIRMED).

Akses / Role: Owning EDUCATOR atau FOUNDER_ADMIN
RequestZod: BookingConfirmSchema

Request Body

FieldTypeWajibDeskripsi
bookingIduuidYaID booking
Response — 200

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
bookingIduuidYaID booking
status"CONFIRMED"YaStatus baru
confirmedAtISO 8601YaWaktu konfirmasi
Known Status / Error Codes
400 VALIDATIONPayload tidak lolos BookingConfirmSchema.
403 FORBIDDENAktor bukan pendidik pemilik booking dan bukan FOUNDER_ADMIN.
404 BOOKING_NOT_FOUNDBooking tidak ditemukan.
409 CONFLICTBooking tidak berstatus PENDING (tidak dapat dikonfirmasi).
500 INTERNALInternal server error.
Implementation Notes
  • Domain event `booking.confirmed` (PRD §450, WEBHOOK_CONTRACT).
  • Guard: hanya pemilik EDUCATOR (booking.educator.userId === actorUserId, dari session server-side — bukan dari klien) atau FOUNDER_ADMIN.
  • Menulis status CONFIRMED + audit BOOKING_CONFIRMED.
Source / Evidence
docs/implementation/POST_EXECUTION_VERIFICATION.md §1 (V7-V13) — diverifikasi ulang pada fresh database.src/app/api/v1/bookings/confirm/route.tssrc/lib/bookings/service.ts
GET/api/v1/bookings/ledgerDEFERRED

Riwayat Ledger

Riwayat pencatatan buku besar internal (dokumentasi 07 §2.6).

Akses / Role: Authenticated Learner
Implementation Notes
  • Belum ada kode; bagian dari scope member/founder pasca-MVP.
  • Tidak direpresentasikan sebagai berfungsi.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.6docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)

Authentication

3 endpoint

Auth & sesi (aspirational — Supabase terblokir).

POST/api/v1/auth/magic-linkASPIRATIONAL

Magic Link

Mengirimkan Magic Link via Supabase Auth (dokumentasi 07 §2.1).

Akses / Role: Public
Implementation Notes
  • Belum ada kode; terblokir kredensial cloud Supabase. Identity demo diresolusi server-side.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.1docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N2)
POST/api/v1/auth/verify-sessionASPIRATIONAL

Verifikasi Sesi

Verifikasi token sesi & mengambil data role (dokumentasi 07 §2.1).

Akses / Role: Authenticated
Implementation Notes
  • Belum ada kode; terblokir kredensial cloud Supabase.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.1docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N2)
POST/api/v1/auth/logoutASPIRATIONAL

Logout

Mengakhiri sesi pengguna (dokumentasi 07 §2.1).

Akses / Role: Authenticated
Implementation Notes
  • Belum ada kode; terblokir kredensial cloud Supabase.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.1docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N2)

Member

2 endpoint

Dashboard & laporan anggota.

GET/api/v1/member/dashboardDEFERRED

Dashboard Anggota

Data agregat (jadwal, point ledger, referral) — dokumentasi 07 §2.2.

Akses / Role: Authenticated (Learner/Edu/Inst)
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.2docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
GET/api/v1/member/progress-reportsDEFERRED

Laporan Perkembangan

Laporan perkembangan Rabbani anak (dokumentasi 07 §2.2).

Akses / Role: Authenticated (Learner/Guardian)
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.2docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)

Courses / LMS

5 endpoint

Katalog program & modul LMS.

GET/api/v1/coursesDEFERRED

Katalog Program

Katalog program belajar & kurikulum (dokumentasi 07 §2.4).

Akses / Role: Public
Implementation Notes
  • Belum ada route API. `course_catalogs` (9 entri) sudah tersedia di database via seed.
  • Fungsi katalog saat ini disajikan via halaman landing (`/`), bukan API.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.4docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
POST/api/v1/coursesDEFERRED

Buat Program

Membuat kurikulum/modul materi baru (dokumentasi 07 §2.4).

Akses / Role: Educator / Institution
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.4docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
POST/api/v1/lms/attendanceDEFERRED

Presensi Sesi

Catat presensi sesi mengajar (dokumentasi 07 §2.4).

Akses / Role: Educator
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.4docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
POST/api/v1/lms/progress-reportDEFERRED

Laporan Perkembangan

Laporan perkembangan hafalan/talaqqi (dokumentasi 07 §2.4).

Akses / Role: Educator
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.4docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
GET/api/v1/lms/external-ssoDEFERRED

SSO LMS Eksternal

SSO Token ke LearnHouse / Moodle LMS (dokumentasi 07 §2.4).

Akses / Role: Authenticated Member
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.4docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)

Referrals

3 endpoint

Kode referral, statistik & leaderboard.

POST/api/v1/referrals/generate-codeDEFERRED

Generate Kode Referral

Membuat kode/link referral baru (dokumentasi 07 §2.7).

Akses / Role: Authenticated Member
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.7docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
GET/api/v1/referrals/statsDEFERRED

Statistik Referral

Statistik klik, konversi, & komisi virtual (dokumentasi 07 §2.7).

Akses / Role: Authenticated Member
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.7docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
GET/api/v1/referrals/leaderboardDEFERRED

Leaderboard Ambassador

Papan peringkat ambassador terbanyak (dokumentasi 07 §2.7).

Akses / Role: Public
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.7docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)

Management

8 endpoint

CMS, ERP, RBAC, taksonomi & queue.

GET/api/v1/management/cms/articlesDEFERRED

Manajemen CMS

Manajemen konten artikel & landing page (dokumentasi 07 §2.8).

Akses / Role: Founder / CMS Admin
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.8docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
GET/api/v1/management/erp/ledger-summaryDEFERRED

Ringkasan Ledger ERP

Pengawasan pembukuan ledger & fee platform (dokumentasi 07 §2.8).

Akses / Role: Founder / Finance
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.8docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
GET/api/v1/management/rbac/rolesDEFERRED

Matriks RBAC

Manajemen matriks hak akses user (dokumentasi 07 §2.8).

Akses / Role: Founder Admin
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.8docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
GET/api/v1/management/verification/queueDEFERRED

Queue Verifikasi (API)

Queue audit 4-lapis Lajnah & approval badge (dokumentasi 07 §2.8).

Akses / Role: Lajnah Verifier / Founder
Implementation Notes
  • Belum ada route API. Fungsi setara disajikan sebagai halaman server-rendered `/management/lajnah` (listVerificationQueue, DB-backed; terverifikasi).
Source / Evidence
docs/07_API_ENDPOINTS.md §2.8docs/implementation/POST_EXECUTION_VERIFICATION.md §1 (V12)
GET/api/v1/management/taxonomyDEFERRED

Tata Kelola Taksonomi

Hirarki kategori, Mazhab, Sanad Tree (dokumentasi 07 §2.8).

Akses / Role: Founder / Admin
Implementation Notes
  • Belum ada kode; pasca-MVP.
Source / Evidence
docs/07_API_ENDPOINTS.md §2.8docs/implementation/POST_EXECUTION_VERIFICATION.md §2 (N4)
GET/api/v1/management/economy/overviewVERIFIED

Overview Ekonomi (Founder)

Monitoring Founder: total transaksi, ledger, poin beredar, payment health, komisi.

Akses / Role: Founder (economy.transaction.view)
Response — 200

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
overview.transactionCountintYaTotal transaksi
overview.totalPointsInCirculationintYaPoin beredar (proyeksi)
payment.modestringYa'SIMULATED_INTERNAL'
Known Status / Error Codes
403 FORBIDDENTidak memiliki economy.transaction.view.
Implementation Notes
  • Runtime: founder 200, staff 403.
Source / Evidence
src/app/api/v1/management/economy/overview/route.ts
POST/api/v1/management/economy/adjustmentsVERIFIED

Penyesuaian Ekonomi (Founder)

ADJUSTMENT founder dengan reason wajib + authorization + audit (economy.adjust).

Akses / Role: Founder-only (economy.adjust)
RequestZod: AdjustmentSchema

Request Body

FieldTypeWajibDeskripsi
accountOwnerIduuidYaTarget akun
amountintYaJumlah (signed, integer)
reasonstringYaAlasan wajib
Response — 201

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
transactionIduuidYaADJUSTMENT transaction
statusstringYa'COMPLETED'
duplicatebooleanYaIdempotency indicator
Known Status / Error Codes
403 FORBIDDENeconomy.adjust founder-only.
Implementation Notes
  • Runtime: founder 201 COMPLETED, staff 403. Idempotent per key.
Source / Evidence
src/app/api/v1/management/economy/adjustments/route.tssrc/lib/economy/service.ts
POST/api/v1/management/economy/reversalsVERIFIED

Reversal Transaksi (Founder)

REVERSAL transaksi COMPLETED dengan reason wajib + audit (economy.reversal).

Akses / Role: Founder-only (economy.reversal)
RequestZod: ReversalSchema

Request Body

FieldTypeWajibDeskripsi
transactionIduuidYaTransaksi target (COMPLETED)
reasonstringYaAlasan wajib
Response — 201

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
transactionIduuidYaTransaksi asli (REVERSED)
reversalTransactionIduuidYaTransaksi REVERSAL baru
statusstringYa'REVERSED'
Known Status / Error Codes
403 FORBIDDENeconomy.reversal founder-only.
Implementation Notes
  • Runtime: founder 201 REVERSED, duplicate deterministic reject, staff 403.
Source / Evidence
src/app/api/v1/management/economy/reversals/route.tssrc/lib/economy/service.ts

Economy

3 endpoint

Internal economy: balance, transaksi, ledger.

GET/api/v1/economy/balanceVERIFIED

Balance Proyeksi (Poin Saya)

Proyeksi saldo Poin dari ledger append-only (SELF-scoped).

Akses / Role: Member (SELF)
Response — 200

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
accountOwnerIduuidYaAkun yang diproyeksikan
currencystringYa'POINT'
balance.totalPointsintYaSaldo Poin (proyeksi ledger)

Menyertakan disclaimer: Poin internal platform — non-tunai dan tidak dapat ditarik.

Known Status / Error Codes
401 AUTHTidak ada identity server.
Implementation Notes
  • Ledger adalah sumber kebenaran; saldo adalah proyeksi. Runtime: learner 200, unauth 401.
Source / Evidence
src/app/api/v1/economy/balance/route.tssrc/lib/ledger/service.ts
GET/api/v1/economy/transactionsVERIFIED

Transaksi Ekonomi

Riwayat transaksi (SELF default; ?organizationId org-scoped untuk ORG_OWNER/ADMIN).

Akses / Role: Member (SELF) / ORG_OWNER, ORG_ADMIN (org)
Request

Query Parameters

FieldTypeWajibDeskripsi
organizationIduuidOpsionalScope organisasi (org-scoped read)
Response — 200

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
scopestringYa'SELF' | 'ORGANIZATION'
transactionsarrayYaDaftar EconomicTransaction
Known Status / Error Codes
403 FORBIDDENCross-org / bukan member aktif.
Implementation Notes
  • Runtime: learner SELF 200, cross-org 403, org admin org-scoped 200.
Source / Evidence
src/app/api/v1/economy/transactions/route.tssrc/lib/economy/service.ts
GET/api/v1/economy/ledgerVERIFIED

Entri Ledger (SELF)

Entri ledger append-only milik member yang terautentikasi.

Akses / Role: Member (SELF)
Response — 200

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
accountOwnerIduuidYaPemilik ledger
entriesarrayYaEntri append-only
Known Status / Error Codes
401 AUTHTidak ada identity server.
Implementation Notes
  • Runtime: learner 200 (2 entries).
Source / Evidence
src/app/api/v1/economy/ledger/route.ts

Payments

1 endpoint

External payment boundary (webhook mock).

POST/api/v1/payments/webhookVERIFIED

Webhook Pembayaran (Mock)

Webhook provider mock: verifikasi HMAC signature + idempotent; PAID → domain transaction.

Akses / Role: Provider (signature header x-mock-signature)
RequestZod: WebhookPayload

Request Body

FieldTypeWajibDeskripsi
eventIdstringYaID event unik (idempotency)
bookingIduuidYaBooking terkait
amountintYaJumlah
statusstringYa'PAID' | 'REFUNDED' | 'EXPIRED' | 'FAILED'
Response — 200

Envelope sukses runtime: `{ "success": true, "statusCode": <code>, "message": "...", "data": { ... } }`. Field `meta` (07_API_ENDPOINTS.md §1.1) tidak dikeluarkan oleh runtime saat ini (drift tercatat).

FieldTypeWajibDeskripsi
paymentIduuidYaPayment boundary record
paymentStatusstringYa'PAID'
transactionIduuid | nullYaDomain transaction (PAID only)
duplicatebooleanYaDuplicate webhook indicator
modestringYa'SIMULATED_INTERNAL'
Known Status / Error Codes
401 SIGNATUREHMAC signature tidak valid.
400 VALIDATIONPayload/status tidak valid.
503 DISABLEDMock webhook dinonaktifkan di production tanpa PAYMENT_MOCK_SECRET eksplisit.
Implementation Notes
  • Runtime: valid 200, duplicate dup:true (satu efek), forged 401, tanpa persistensi.
Source / Evidence
src/app/api/v1/payments/webhook/route.tssrc/lib/payment/service.tssrc/lib/payment/mockAdapter.ts

Schemas

Zod Validation Schemas

BookingInquirySchema

src/lib/validations/index.ts
FieldTypeWajibDeskripsi
educatorIduuidYaID pendidik tujuan
courseIduuidOpsionalID program (opsional)
scheduleIduuidOpsionalID jadwal (opsional)
learningMethodenum(ONLINE_ZOOM | PRIVATE_HOME | GROUP_MAJELIS)YaMetode belajar
preferredSchedulestring (min 3)YaPreferensi jadwal
learnerNamestring (min 2)YaNama pembelajar
contactPhonestring (regex ^(\+62|08)[0-9]{8,12}$)YaNomor WhatsApp/HP Indonesia
notesstring (max 500)OpsionalCatatan tambahan

VerificationSubmitSchema

src/lib/validations/index.ts
FieldTypeWajibDeskripsi
educatorIduuidYaID pendidik
ktpNumberstring (16 digit)YaNomor KTP
ktpDocumentUrlurlYaURL dokumen KTP (Lapisan 1)
ijazahDocumentUrlurlYaURL dokumen Ijazah (Lapisan 2)
ijazahSha256Hashstring (64 hex)YaFingerprint SHA-256 dokumen Ijazah
recommenderEmailemailYaEmail ulama/penyandang rekomendasi (Lapisan 3)
recommenderInstitutionstring (min 3)YaLembaga pemberi rekomendasi
qiraahSanadNamestringOpsionalNama sanad qiraah (opsional)

LajnahReviewSchema

src/app/api/v1/verification/review/route.ts (inline)
FieldTypeWajibDeskripsi
verificationRequestIdstring (min 1)YaID permohonan verifikasi
currentStatusenum(VerificationStatus)YaStatus yang diklaim klien (stale-check terhadap DB)
targetStatusenum(VerificationStatus)YaStatus tujuan
reviewNotesstring (min 5)YaCatatan telaah
ethicsScorenumber (0-100)OpsionalSkor etika, default 100

Identity verifikator (verifierUserId & verifierRoles) TIDAK dikirim klien; diresolusi server-side dari session (DECISION-07) dan diperiksa role LAJNAH_VERIFIER/FOUNDER_ADMIN.

BookingConfirmSchema

src/app/api/v1/bookings/confirm/route.ts (inline)
FieldTypeWajibDeskripsi
bookingIduuidYaID booking

Identity aktor (actorUserId & actorRoles) TIDAK dikirim klien; diresolusi server-side dari session (DECISION-07). Konfirmasi hanya untuk pendidik pemilik booking atau FOUNDER_ADMIN.

VerificationStatusQuery

src/app/api/v1/verification/status/route.ts (inline)
FieldTypeWajibDeskripsi
educatorIduuidYaQuery parameter; ID pendidik

State Machine — Verification

DRAFT → [SUBMITTED]SUBMITTED → [UNDER_REVIEW_LAJNAH, REJECTED]UNDER_REVIEW_LAJNAH → [VERIFIED, REJECTED]VERIFIED → [REVOKED]REJECTED → [SUBMITTED]REVOKED → [SUBMITTED]

Domain Enums

UserRole

LEARNERGUARDIANEDUCATORINSTITUTION_ADMINLAJNAH_VERIFIERFOUNDER_ADMIN

VerificationStatus

DRAFTSUBMITTEDUNDER_REVIEW_LAJNAHVERIFIEDREJECTEDREVOKED

LearningMethod

ONLINE_ZOOMPRIVATE_HOMEGROUP_MAJELIS

BookingStatus

PENDINGCONFIRMEDIN_PROGRESSCOMPLETEDCANCELLED

LedgerEntryType

LEARNER_POINTVOUCHER_CREDITFEE_COLLECTIONCOMMISSION_ACCRUALREWARD_TOKEN

Implementation Status

Status Legend

VERIFIED

Endpoint ada di kode dan terverifikasi secara empiris pada audit terbaru (E2E, fresh database).

IMPLEMENTED

Endpoint ada di kode, terverifikasi dari sumber; belum masuk daftar verifikasi E2E terakhir.

DEFERRED

Terdokumentasi di 07_API_ENDPOINTS.md, sengaja ditunda pasca-MVP; belum ada kode.

ASPIRATIONAL

Kapabilitas yang diharapkan kontrak (contoh: Supabase Auth, Upstash rate limit) — terblokir kredensial cloud, belum ada kode.

NOT_IMPLEMENTED

Terdokumentasi, belum ada kode, dan tidak terjadwal pada MVP.

Endpoint Matrix (13 verified · 20 deferred · 3 aspirational)

EndpointMethodStatus
/api/v1/auth/logoutPOSTASPIRATIONAL
/api/v1/auth/magic-linkPOSTASPIRATIONAL
/api/v1/auth/verify-sessionPOSTASPIRATIONAL
/api/v1/bookings/confirmPOSTVERIFIED
/api/v1/bookings/inquirePOSTVERIFIED
/api/v1/bookings/ledgerGETDEFERRED
/api/v1/coursesGETDEFERRED
/api/v1/coursesPOSTDEFERRED
/api/v1/economy/balanceGETVERIFIED
/api/v1/economy/ledgerGETVERIFIED
/api/v1/economy/transactionsGETVERIFIED
/api/v1/educatorsGETDEFERRED
/api/v1/educators/:idGETDEFERRED
/api/v1/educators/:id/reviewsGETDEFERRED
/api/v1/lms/attendancePOSTDEFERRED
/api/v1/lms/external-ssoGETDEFERRED
/api/v1/lms/progress-reportPOSTDEFERRED
/api/v1/management/cms/articlesGETDEFERRED
/api/v1/management/economy/adjustmentsPOSTVERIFIED
/api/v1/management/economy/overviewGETVERIFIED
/api/v1/management/economy/reversalsPOSTVERIFIED
/api/v1/management/erp/ledger-summaryGETDEFERRED
/api/v1/management/rbac/rolesGETDEFERRED
/api/v1/management/taxonomyGETDEFERRED
/api/v1/management/verification/queueGETDEFERRED
/api/v1/member/dashboardGETDEFERRED
/api/v1/member/progress-reportsGETDEFERRED
/api/v1/payments/webhookPOSTVERIFIED
/api/v1/referrals/generate-codePOSTDEFERRED
/api/v1/referrals/leaderboardGETDEFERRED
/api/v1/referrals/statsGETDEFERRED
/api/v1/verification/confirm-tokenPOSTDEFERRED
/api/v1/verification/resubmitPOSTVERIFIED
/api/v1/verification/reviewPOSTVERIFIED
/api/v1/verification/statusGETVERIFIED
/api/v1/verification/submitPOSTVERIFIED

Non-Endpoint Capabilities (Aspirational)

Supabase Auth & RBAC

ASPIRATIONALdocs/07_API_ENDPOINTS.md §1

Proteksi route API via Supabase Auth RBAC.

Runtime: Belum ada. Role diresolusi server-side (DEMO_LEARNER_USER_ID, DEMO_EDUCATOR_ID, LAJNAH verifier) hingga kredensial cloud tersedia.

Upstash Redis Rate Limiter

ASPIRATIONALdocs/07_API_ENDPOINTS.md §4

Rate limit per IP / user (60/menit public, 5/menit verification, 3/menit auth).

Runtime: Belum ada middleware rate limit; terblokir kredensial cloud Upstash.