Gateway Sinkron Nilai ke SIAKAD dipakai oleh aplikasi eksternal yang sudah terdaftar (mis. aplikasi PPL) untuk mengajukan nilai mahasiswa. Pengajuan tidak langsung masuk ke SIAKAD — tersimpan dulu sebagai staging dengan status pending, lalu harus disetujui admin akademik sebelum lanjut diproses.

Autentikasi memakai dua header: Auth-token adalah token yang didapat dari proses login (bukan token akses fitur), dan Auth-api-key adalah token aplikasi yang terdaftar di list aplikasi (tabel apps), bukan token yang didaftarkan lewat menu akses fitur/akses apps. Auth-token yang sudah habis masa berlakunya akan ditolak; Auth-api-key harus milik aplikasi yang statusnya aktif.

1. Mengajukan nilai

curl -X POST https://api.uinmadura.ac.id/api/siakad/nilai \
  -H "Auth-token: YOUR_LOGIN_TOKEN" \
  -H "Auth-api-key: YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kode_user": "U00096",
    "nim": "25314012010",
    "kode_matakuliah": "IQT-34012303",
    "kode_kelas": "A",
    "nilai_akhir": 85.5
  }'

Keterangan body:

kode_user (wajib) — kode user dosen pengampu di SIAKAD (bukan NIP).
nim (wajib) — NIM/NPM mahasiswa yang dinilai, harus terdaftar di SIAKAD.
kode_matakuliah & kode_kelas (wajib) — kode matakuliah dan kelas sesuai data SIAKAD.
nilai_akhir (wajib) — satu nilai akhir mahasiswa untuk matakuliah/kelas ini, angka 0–100. Endpoint ini tidak menerima rincian nilai per komponen (tugas/uts/uas/dll) — hanya satu nilai akhir, karena aplikasi eksternal yang memakai fitur ini pada praktiknya hanya punya satu nilai akhir per mahasiswa.

Keterangan header:

Auth-token — token hasil login (akun pegawai/aplikasi yang sudah login lewat endpoint auth), bukan token akses fitur.
Auth-api-key — token aplikasi sesuai yang tercatat di list aplikasi (tabel apps), dan aplikasinya harus berstatus aktif.

Verifikasi yang dilakukan sebelum pengajuan disimpan:

Dosen dengan kode_user tersebut harus ditemukan di SIAKAD.
Mahasiswa dengan nim tersebut harus ditemukan di SIAKAD.
Kombinasi kode_matakuliah + kode_kelas harus ditemukan di SIAKAD.
Dosen harus terdaftar sebagai pengampu kelas tersebut di SIAKAD — kecuali untuk matakuliah yang memang tidak punya data pengampu sama sekali (mis. KKN, PPL, Skripsi), yang otomatis dilewati karena tidak ada acuan untuk dicocokkan.
Tidak boleh ada pengajuan lain yang masih pending untuk kombinasi mahasiswa + matakuliah + kelas yang sama.

Contoh respons sukses (201):

{
  "status": "success",
  "message": "Pengajuan nilai diterima, menunggu approval admin akademik",
  "data": {
    "id": "[uuid]",
    "status": "pending"
  }
}

2. Melihat daftar pengajuan / cek status satu pengajuan

# Daftar (berpaginasi)
curl https://api.uinmadura.ac.id/api/siakad/nilai?status=pending \
  -H "Auth-token: TOKEN_LOGIN"

# Cek satu pengajuan spesifik (nim + kode_matakuliah + kode_kelas lengkap)
curl "https://api.uinmadura.ac.id/api/siakad/nilai?nim=25314012010&kode_matakuliah=IQT-34012303&kode_kelas=A" \
  -H "Auth-token: TOKEN_LOGIN"

# Admin fakultas: lihat semua pengajuan di fakultas dengan id_fakultas = 1
curl "https://api.uinmadura.ac.id/api/siakad/nilai?id_fakultas=1" \
  -H "Auth-token: TOKEN_LOGIN_ADMIN_FAKULTAS"

Header Auth-token di sini adalah token login (bukan token akses fitur di langkah 1). Endpoint ini tidak dibatasi hanya untuk akun yang terdaftar sebagai admin akademik di aplikasi ini — siapa saja yang sudah login bisa mengakses, tapi data yang terlihat dibatasi menurut cara memanggilnya:

Tanpa parameter id_fakultas — hanya melihat pengajuan yang dia buat sendiri (cocok untuk dosen/akun yang submit).
Dengan parameter id_fakultas — melihat semua pengajuan dari fakultas tersebut saja (cocok untuk admin fakultas). Bukan whitelist di sisi API ini — siapa yang boleh memakai parameter ini dan id_fakultas berapa yang menjadi haknya, ditentukan di aplikasi eksternal pemanggil (mis. PPL), karena pemetaan admin fakultas bisa berbeda antara SIAKAD dan aplikasi lain.

Parameter query (semua opsional, bisa dikombinasikan):

status — pending/approved/rejected.
nim, kode_matakuliah, kode_kelas — filter berdasarkan kombinasi pengajuan.
id_fakultas — lihat penjelasan scoping di atas. Nilainya id_fakultas sesuai tabel master.fakultas di SIAKAD (angka, bukan nama/kode singkatan), otomatis tercatat di setiap pengajuan saat dibuat berdasarkan prodi pemilik kelasnya.

Jika nim + kode_matakuliah + kode_kelas dikirim lengkap sekaligus, data dikembalikan sebagai satu object (bukan list/paginasi) — karena tidak boleh ada dua pengajuan pending untuk kombinasi yang sama (lihat langkah 1), jadi hasilnya cukup satu. Kalau tidak ditemukan, responsnya 404. Selain kombinasi lengkap itu (mis. hanya filter status saja, untuk menyusuri semua pengajuan), data tetap berupa list terpaginasi seperti biasa.

3. Menyetujui / menolak pengajuan

Satu endpoint untuk kedua aksi — aksinya ditentukan lewat payload approve, bukan lewat path URL terpisah.

# Setuju
curl -X POST https://api.uinmadura.ac.id/api/siakad/nilai/[ID]/review \
  -H "Auth-token: TOKEN_LOGIN" \
  -H "Content-Type: application/json" \
  -d '{"approve": 1}'

# Tolak
curl -X POST https://api.uinmadura.ac.id/api/siakad/nilai/[ID]/review \
  -H "Auth-token: TOKEN_LOGIN" \
  -H "Content-Type: application/json" \
  -d '{"approve": 0, "reason": "Komponen nilai tidak sesuai rekap"}'

Keterangan body:

approve (wajib) — boolean, 1/true untuk setuju, 0/false untuk tolak.
reason — wajib diisi hanya saat approve = 0/false (alasan penolakan).

Sama seperti di atas: endpoint ini hanya mensyaratkan token login yang valid (Auth-token), tidak ada pengecekan status admin akademik di sisi API ini. Pembatasan siapa yang boleh menyetujui/menolak sepenuhnya jadi tanggung jawab aplikasi pemanggil.

Penting: status approved hanya berarti admin sudah menyetujui pengajuannya — bukan berarti nilainya sudah pasti berhasil tertulis di SIAKAD. Cek field terpisah applied_to_siakad pada data pengajuan (lihat juga sinkron_ke_siakad di respons approve) untuk tahu status teknisnya: true = sudah benar-benar tersinkron ke SIAKAD, false = sudah dicoba tapi gagal (bisa di-retry, lihat langkah 4), null = belum pernah dicoba (pengajuan masih pending, atau ditolak).

4. Retry sinkron ke SIAKAD

Untuk pengajuan yang sudah approved tapi applied_to_siakad masih false/null (gagal/belum tersinkron, mis. karena nilai_komponen_custom belum ada saat approve, lalu belakangan dilengkapi tim SIAKAD) — coba sinkron ulang tanpa perlu mengubah status approval-nya:

curl -X POST https://api.uinmadura.ac.id/api/siakad/nilai/[ID]/retry-sync \
  -H "Auth-token: TOKEN_LOGIN"

Hanya bisa dipakai untuk pengajuan berstatus approved dan yang applied_to_siakad belum true (kalau sudah true, ditolak dengan pesan "sudah berhasil tersinkron, tidak perlu retry"). Response-nya sama bentuknya seperti approve: ada data (pengajuan terbaru, termasuk applied_to_siakad/sync_message yang sudah terupdate) dan sinkron_ke_siakad (hasil percobaan kali ini).

5. Membatalkan sinkron yang sudah masuk ke SIAKAD (revert)

Dipakai kalau pengajuan sudah berhasil tersinkron (applied_to_siakad = true) tapi ternyata keliru (mis. nilai salah input) dan datanya di SIAKAD perlu dikembalikan ke kondisi sebelum disetujui:

curl -X POST https://api.uinmadura.ac.id/api/siakad/nilai/[ID]/revert-sync \
  -H "Auth-token: TOKEN_LOGIN"

Hanya bisa dipakai kalau applied_to_siakad pengajuan tersebut sudah true, belum pernah di-revert sebelumnya, dan snapshot nilai sebelum sinkron masih tersimpan — pengajuan yang tersinkron sebelum fitur revert ini dirilis tidak punya snapshot, jadi tidak bisa direvert otomatis lewat endpoint ini (respons 409 di kedua kasus). Lihat cara kerja lengkapnya di bagian "Bagaimana revert mengembalikan nilai di SIAKAD" di bawah.

Catatan:

Pengajuan yang sudah rejected tidak bisa diproses ulang. Pengajuan approved juga tidak bisa di-review ulang (approve/reject lagi), tapi bisa dicoba sinkron ulang lewat /retry-sync selama applied_to_siakad belum true, atau dikembalikan lewat /revert-sync kalau applied_to_siakad sudah true.
Setiap langkah (pengajuan, approve, reject, retry, revert) tercatat di activity log untuk audit.
id_fakultas pemilik kelas dideteksi otomatis saat pengajuan dibuat (lewat prodi kelas tersebut di SIAKAD), tidak perlu dikirim di payload saat mengajukan nilai.

Bagaimana approve menulis nilai ke SIAKAD:

Saat disetujui, sistem mengecek dulu apakah kelas tersebut sudah punya definisi komponen nilai di SIAKAD (academic.nilai_komponen_custom, mis. UTS/UAS/Penugasan/Kehadiran beserta bobot persentasenya).

Kalau kelas TIDAK punya dosen pengampu terdaftar di SIAKAD (mis. KKN/PPL/Skripsi, dicek lewat feeder.matakuliah_kelas_pengajar saat pengajuan dibuat) dan belum punya definisi komponen: nilai_akhir ditulis langsung ke academic.nilai_detail saja, tanpa mengisi academic.nilai_mahasiswa_per_komponen — dikonfirmasi tim pengembang SIAKAD, karena kelas semacam ini memang tidak dinilai lewat skema komponen reguler. Pengajuan LAMA yang dibuat sebelum status ini mulai dicatat (tidak diketahui ada pengampu atau tidak) juga dihitung masuk kondisi ini, bukan ditolak hanya karena informasinya tidak tercatat.
Kalau kelas PUNYA dosen pengampu terdaftar tapi belum punya definisi komponen sama sekali (baris nilai_komponen_custom kosong untuk kelas ini): approve ditolak, nilai tidak ditulis ke SIAKAD sama sekali. Respons sinkron_ke_siakad akan berisi "applied": false — mengisi komponen nilai itu tanggung jawab dosen pengampu lewat SIAKAD, bukan kasus yang boleh dilewati di sini.
Kalau kelas sudah punya definisi komponen (baik ada dosen pengampu terdaftar atau tidak): nilai_akhir yang dikirim di payload ditulis ke setiap komponen kelas tersebut secara sama di academic.nilai_mahasiswa_per_komponen (nilai yang sama di semua komponen) — karena endpoint ini hanya menerima satu nilai akhir per mahasiswa, bukan rincian per komponen. Nilai akhir yang sama itu juga langsung ditulis ke academic.nilai_detail (dikonversi ke huruf/angka mutu lewat academic.rentang_nilai).
Pengaman: kalau nilai mahasiswa untuk matakuliah/kelas itu sudah is_khs (sudah final/tayang di KHS) di SIAKAD, approve tidak menimpanya — ditolak dengan pesan jelas di respons sinkron_ke_siakad, perlu penanganan manual.
Field academic.matakuliah_kelas.status_input_nilai / token_input_nilai tidak disentuh karena semantiknya belum dikonfirmasi resmi ke tim SIAKAD.
Hasil approve selalu disertakan di field sinkron_ke_siakad pada respons (status applied, komponen yang diisi, nilai akhir yang ditulis, atau pesan kenapa gagal) supaya bisa diperiksa per kasus.

Bagaimana revert mengembalikan nilai di SIAKAD:

Setiap kali approve atau retry-sync berhasil menulis ke SIAKAD, nilai yang LAMA (sebelum ditulis) direkam otomatis sebagai snapshot pada pengajuan tersebut. /revert-sync membaca snapshot itu lalu mengembalikan:

academic.nilai_detail — nilai_akhir, huruf_mutu, angka_mutu, dan is_lulus dikembalikan ke nilai sebelum sinkron ini.
academic.nilai_mahasiswa_per_komponen (kalau sempat diisi, lihat poin komponen di atas) — baris yang sebelum sinkron ini SUDAH ADA dikembalikan nilainya; baris yang DIBUAT BARU oleh sinkron ini dihapus (soft-delete), karena baris itu memang belum ada sebelum sinkron.

Pengaman: sama seperti approve, kalau nilai di SIAKAD sekarang sudah is_khs (final/tayang KHS) — kemungkinan sudah ada proses resmi lain yang menjadikannya final setelah sinkron ini — revert ditolak demi keamanan data akademik (respons 409).

Setelah berhasil direvert, applied_to_siakad pengajuan tersebut kembali ke false. Kalau nanti /retry-sync (atau approve) dipanggil lagi dan berhasil menulis ulang, status revert ini otomatis direset — snapshot yang baru dicatat, dan pengajuan bisa direvert lagi dari snapshot tersebut kalau perlu.

Nama	Contoh Nilai	Keterangan
{{ key }}	`{{ selected.params[key] }}`	{{ selected.note ? selected.note[key] : '' }}
limit	`[ANGKA]`	Membatasi jumlah data yang ditampilkan, default 30
page	`[ANGKA]`	Menampilkan data berdasarkan halaman tertentu, default 1

{{ selected.prefix }}