Membangun aplikasi untuk jemaat

Cara kerjanya

1. 1

   Admin menerbitkan kunci

   Di SISWA 2: Pengguna → Aplikasi tersambung. Admin mencentang lingkup data dan membatasi ke wilayah atau komisi.

2. 2

   Aplikasi memanggil /api/v1

   Dari jaringan jemaat, dengan header Authorization. SISWA 2 hanya mengembalikan kolom yang diizinkan.

3. 3

   Pengurus tetap memutuskan

   Catatan keuangan dan koreksi anggota masuk sebagai draft/usulan; bendahara atau Tata Usaha yang menyetujui.

Kunci & panggilan pertama

Kunci berbentuk sw2_<awalan>_<rahasia>, ditampilkan sekali saat dibuat, berlaku setahun, dan bisa dicabut admin kapan saja. Kirim di setiap permintaan ke komputer SISWA 2 (port 8177):

curl -H "Authorization: Bearer sw2_k3p9x2aa_…" http://192.168.1.10:8177/api/v1

{"data": {"versi": "2.13.0", "api": 1,
          "aplikasi": {"id": 3, "nama": "Kas & Program Komisi Pemuda"},
          "lingkup": ["kas:baca", "kas:catat", "program:baca"],
          "batas": {"wilayah": null, "bidang": [12]}, "jemaat": null}}

Contoh mencatat pengeluaran — selalu tersimpan sebagai draft:

curl -X POST http://192.168.1.10:8177/api/v1/kas/transaksi \
  -H "Authorization: Bearer sw2_k3p9x2aa_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d0c6f0e-…" \
  -d '{"tanggal":"2026-10-05","jenis":"keluar","akun_id":48,"kategori_id":40,
       "jumlah":350000,"keterangan":"Konsumsi retret pemuda"}'

{"data": {"transaksi_id": 2231, "status": "draft"}}

Lingkup

Admin mencentang lingkup per aplikasi. Lingkup bertanda ✎ adalah tulisan — selalu draft atau usulan, kecuali presensi kebaktian dan kelas serta pendaftaran & check-in kegiatan yang langsung tercatat atas nama aplikasi. Pembayaran kegiatan hanya dicatat; membukukannya ke Buku Kas tetap tugas staf keuangan di SISWA 2.

Batas: aplikasi bisa dibatasi ke wilayah tertentu (anggota di luar wilayah dijawab “tidak ditemukan”) dan ke bidang/komisi tertentu beserta sub-komisinya (kas, program, dropping, lampiran, kegiatan), dan ke kelas tertentu (misalnya hanya kelas Sekolah Minggu).

Titik /api/v1

Kolom dan isian lengkap tiap titik ada di /api/v1/openapi.json SISWA 2 Anda (butuh kunci).

Aturan main

• Jawaban: {data, halaman?}; galat {galat: {kode, pesan}} dengan status 400 (isian), 401 (kunci), 403 (lingkup/jaringan), 404, 409 (ditolak aturan SISWA 2 — pesannya layak ditampilkan ke pengguna), 429 (laju).
• Daftar anggota berhalaman: limit ≤ 200, lanjutkan dengan kursor dari halaman.kursor_berikut.
• Laju: 600 permintaan baca dan 60 tulisan per menit per aplikasi.
• Idempotency-Key pada setiap tulisan: kiriman ulang dengan kunci yang sama (24 jam) mendapat jawaban pertama tanpa menulis dua kali.
• Jaringan: kunci hanya berlaku dari jaringan jemaat. Admin bisa mengizinkan aplikasi tertentu dipakai dari luar — hanya lewat Tailscale dan selama Akses dari luar jaringan di SISWA 2 aktif.
• Versi: /api/v1 hanya bertambah (titik, kolom, lingkup baru); abaikan kolom yang belum Anda kenal. Perubahan yang merusak menunggu /api/v2.

Data pribadi (UU PDP)

KTP, nomor akta, golongan darah, catatan & kasus pastoral, alasan nonaktif, proses keanggotaan, dan data penghapusan tidak pernah keluar lewat kunci. Kontak anggota hanya dengan persetujuan Persidangan Majelis Jemaat. Sebagai pengembang Anda wajib:

• tidak menyimpan salinan penuh data anggota (tembolok paling lama 24 jam);
• tidak memindahkan data ke pihak atau layanan lain di luar yang disebut saat kunci diminta;
• membuang data anggota yang sudah dihapus dari SISWA 2 pada sinkron berikutnya.

Setiap permintaan aplikasi tercatat dan bisa dilihat admin jemaat.

Ekstensi terpasang

Tidak punya komputer atau peladen sendiri? Kemas aplikasi web statis (HTML, JS, CSS, gambar) dalam zip dengan ekstensi.json. Admin memasangnya lewat Pengguna → Aplikasi tersambung → Pasang ekstensi… dan menyetujui lingkupnya; pengguna SISWA 2 membukanya dari menu Ekstensi. Tidak ada kunci yang perlu disimpan.

{
  "nama": "Check-in Kegiatan",
  "versi": "1.0.0",
  "pengembang": "Komisi Pemuda",
  "keterangan": "Layar check-in untuk tablet di pintu masuk.",
  "api_min": 1,
  "lingkup": ["kegiatan:baca", "kegiatan:kelola"]
}

• SISWA 2 membuka index.html dengan #sesi=…&api=…: panggil ${api}/api/v1/… dengan Authorization: Bearer ${sesi}. Hapus fragmen dari alamat setelah dibaca.
• Sesi berlaku 12 jam dan lingkupnya = lingkup yang disetujui admin, diiris dengan hak pengguna yang membukanya (pembaca hanya mendapat lingkup :baca).
• Ekstensi dilayani dari port tersendiri (8176), terpisah dari SISWA 2: ia tidak bisa membaca sesi login pengguna dan hanya boleh memanggil /api/v1.
• Paket ≤ 20 MB, hanya berkas web statis; memasang ulang dengan nama yang sama = pembaruan.

Contoh resmi: Kas & Program Komisi

Aplikasi web kecil untuk pengurus komisi: saldo kas komisi, program kerja dengan realisasi, status dropping, catat pengeluaran/penerimaan dengan foto nota (draft), minta dropping, dan isi LPJ — nyaman dibuka dari HP di Wi-Fi gereja. Tanpa dependensi, cukup Node.js 22.

# 1. Di SISWA 2: Pengguna → Aplikasi tersambung → Tambah aplikasi
#    lingkup kas:baca, kas:catat, program:baca, program:usul, lampiran:unggah
#    batas: komisi Anda → salin kunci
# 2. Di komputer komisi (jaringan gereja yang sama):
SISWA2_URL=http://192.168.1.10:8177 SISWA2_KUNCI=sw2_… KODE_AKSES=kode-anda node server.mjs
# 3. Buka http://localhost:3300 — atau dari HP: http://<alamat komputer>:3300