{
    "openapi": "3.0.3",
    "info": {
        "title": "SPP Sekolah API",
        "version": "1.0.0",
        "description": "REST API aplikasi SaaS Pembayaran Administrasi Sekolah (SPP & biaya lain). Multi-sekolah: setiap token hanya dapat mengakses data sekolahnya sendiri.\n\nFormat respons: `{success, message, data, meta}`. Dokumentasi lengkap: https://belajar-api.unama.ac.id/spp/docs"
    },
    "servers": [
        {
            "url": "https://belajar-api.unama.ac.id/api/spp"
        }
    ],
    "tags": [
        {
            "name": "Umum",
            "description": "Endpoint publik tanpa token."
        },
        {
            "name": "Autentikasi Admin",
            "description": "Daftar sekolah baru atau login admin untuk mendapatkan token. Kirim token di setiap request sebagai header `Authorization: Bearer {token}`. Token berlaku 30 hari."
        },
        {
            "name": "Sekolah & Pengguna",
            "description": "Pengaturan profil sekolah (tampil di kuitansi & portal wali) dan pengelolaan user admin sekolah."
        },
        {
            "name": "Tahun Ajaran",
            "description": "Hanya satu tahun ajaran yang aktif. Bulan tagihan SPP diambil dari rentang tanggal tahun ajaran."
        },
        {
            "name": "Kelas",
            "description": "Kelas/rombel beserta tingkat (`grade`, 1–13) yang dipakai untuk tarif per tingkat."
        },
        {
            "name": "Siswa & Import Excel",
            "description": "NIS unik per sekolah. Status: `aktif`, `lulus`, `pindah`, `keluar`. Import Excel 2 langkah: unggah → pratinjau (validasi per baris) → commit."
        },
        {
            "name": "Jenis Biaya, Tarif & Potongan",
            "description": "`frequency`: `bulanan` (ditagih tiap bulan, mis. SPP) atau `sekali` (sekali per tahun ajaran, boleh dicicil). Tarif diatur per tahun ajaran: umum, per tingkat, atau per kelas. Prioritas: tarif khusus siswa → kelas → tingkat → umum, lalu potongan."
        },
        {
            "name": "Tagihan",
            "description": "Status tagihan: `belum`, `sebagian` (dicicil), `lunas`, `batal`. Generate massal bersifat idempotent — memanggil ulang tidak membuat tagihan dobel."
        },
        {
            "name": "Pembayaran & Kuitansi",
            "description": "Satu pembayaran bisa melunasi beberapa tagihan sekaligus; nominal per tagihan boleh lebih kecil dari sisa (cicilan). Nomor kuitansi otomatis per sekolah per tahun: `{PREFIX}-{TAHUN}-{00001}`. Semua diproses dalam transaksi database."
        },
        {
            "name": "Laporan",
            "description": "Semua laporan mendukung `format=xlsx` untuk mengunduh Excel."
        },
        {
            "name": "Portal Wali Murid",
            "description": "Wali login dengan kode sekolah + NIS + PIN dari sekolah. Token wali hanya bisa membaca data siswa itu sendiri."
        },
        {
            "name": "Superadmin Platform",
            "description": "Hanya untuk token superadmin (login via `/auth/login`)."
        }
    ],
    "paths": {
        "/": {
            "get": {
                "tags": [
                    "Umum"
                ],
                "summary": "Info API & daftar endpoint",
                "description": "Cocok untuk cek koneksi. Mengembalikan versi, URL dokumentasi, dan daftar endpoint.",
                "operationId": "get_",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Selamat datang di API SPP Sekolah",
                                    "data": {
                                        "name": "SPP Sekolah API",
                                        "version": "1.0.0",
                                        "base_url": "https://belajar-api.unama.ac.id/api/spp",
                                        "documentation": "https://belajar-api.unama.ac.id/spp/docs",
                                        "openapi": "https://belajar-api.unama.ac.id/api/spp/openapi",
                                        "postman": "https://belajar-api.unama.ac.id/spp/docs/postman",
                                        "auth": "Bearer token. Admin: POST /auth/login. Wali: POST /wali/login.",
                                        "response_format": {
                                            "success": "bool",
                                            "message": "string",
                                            "data": "mixed",
                                            "meta": "object (paginasi)"
                                        },
                                        "endpoints": [
                                            {
                                                "group": "Umum",
                                                "method": "GET",
                                                "path": "/api/spp/",
                                                "title": "Info API & daftar endpoint",
                                                "auth": "none"
                                            },
                                            {
                                                "group": "Umum",
                                                "method": "GET",
                                                "path": "/api/spp/openapi",
                                                "title": "Spesifikasi OpenAPI 3 (JSON)",
                                                "auth": "none"
                                            },
                                            "…"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/openapi": {
            "get": {
                "tags": [
                    "Umum"
                ],
                "summary": "Spesifikasi OpenAPI 3 (JSON)",
                "description": "Impor ke Swagger UI, Insomnia, atau Postman. (Alias `/openapi.json` tersedia bila server meneruskan *.json ke aplikasi.)",
                "operationId": "get_openapi",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "*/*": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/postman": {
            "get": {
                "tags": [
                    "Umum"
                ],
                "summary": "Koleksi Postman v2.1",
                "description": "Sama dengan tombol unduh di halaman dokumentasi.",
                "operationId": "get_postman",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "*/*": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/schools/{slug}": {
            "get": {
                "tags": [
                    "Umum"
                ],
                "summary": "Info publik sekolah",
                "description": "Nama, logo, dan cara bayar sekolah berdasarkan kode sekolah (slug). Berguna untuk layar login wali.",
                "operationId": "get_schools_slug_",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "description": "Kode sekolah",
                        "schema": {
                            "type": "string"
                        },
                        "example": "smp-negeri-1-demo"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 4,
                                        "name": "SMP Negeri 1 (Demo)",
                                        "slug": "smp-negeri-1-demo",
                                        "npsn": "10500001",
                                        "level": "SMP",
                                        "address": "Jl. Kapten Pattimura No. 1, Kenali Besar",
                                        "city": "Jambi",
                                        "phone": "0741-123456",
                                        "email": "tu@smpn1.demo",
                                        "logo_url": "https://belajar-api.unama.ac.id/spp/logo/smp-negeri-1-demo?v=1794529086",
                                        "payment_instructions": "1. Tunai di ruang Tata Usaha, Senin–Jumat pukul 07.30–14.00.\n2. Transfer ke salah satu rekening sekolah, lalu kirim foto bukti transfer ke WA bendahara 0812-3456-7890 dengan format: NAMA – KELAS – BULAN.\n3. SPP dibayar paling lambat tanggal 10 setiap bulan.",
                                        "bank_accounts": "Bank Jambi 1234567890 a.n. SMP Negeri 1 Demo\nBRI 0021-01-000123-30-5 a.n. SMP Negeri 1 Demo"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/auth/register": {
            "post": {
                "tags": [
                    "Autentikasi Admin"
                ],
                "summary": "Daftar sekolah + admin",
                "description": "Membuat sekolah baru beserta akun admin pertamanya, lalu langsung mengembalikan token.",
                "operationId": "post_auth_register",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Sekolah berhasil didaftarkan. Lanjutkan dengan membuat tahun ajaran, kelas, siswa, jenis biaya, lalu tagihan.",
                                    "data": {
                                        "user": {
                                            "id": 14,
                                            "name": "Admin API",
                                            "email": "api7001@uji.test",
                                            "phone": null,
                                            "role": "admin",
                                            "position": "Bendahara",
                                            "is_active": true,
                                            "school_id": 9,
                                            "last_login_at": null,
                                            "created_at": "2026-11-13T06:21:02+07:00"
                                        },
                                        "school": {
                                            "id": 9,
                                            "name": "SMA API Test 7001",
                                            "slug": "sma-api-test-7001",
                                            "npsn": null,
                                            "level": "SMA",
                                            "address": null,
                                            "city": "Jambi",
                                            "phone": null,
                                            "email": "api7001@uji.test",
                                            "logo_url": null,
                                            "payment_instructions": "Pembayaran dapat dilakukan:\n1. Tunai di ruang Tata Usaha (Senin–Jumat, 07.30–14.00).\n2. Transfer ke rekening sekolah, lalu kirim bukti transfer ke bendahara.",
                                            "bank_accounts": null,
                                            "principal_name": null,
                                            "principal_nip": null,
                                            "treasurer_name": "Admin API",
                                            "treasurer_nip": null,
                                            "receipt_prefix": "KW",
                                            "receipt_footer": null,
                                            "status": "active",
                                            "created_at": "2026-11-13T06:21:02+07:00"
                                        },
                                        "token": {
                                            "access_token": "14|Xk3vN0pQ...contoh-token...9aZ",
                                            "token_type": "Bearer",
                                            "expires_at": "2026-12-13T06:21:02+07:00"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "school_name": {
                                        "type": "string",
                                        "description": "Nama sekolah"
                                    },
                                    "level": {
                                        "type": "string",
                                        "description": "TK/SD/MI/SMP/MTs/SMA/MA/SMK/Lainnya"
                                    },
                                    "npsn": {
                                        "type": "string",
                                        "description": "NPSN"
                                    },
                                    "city": {
                                        "type": "string",
                                        "description": "Kota"
                                    },
                                    "school_phone": {
                                        "type": "string",
                                        "description": "Telepon sekolah"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "Nama admin"
                                    },
                                    "email": {
                                        "type": "string",
                                        "description": "Email login (unik)"
                                    },
                                    "phone": {
                                        "type": "string",
                                        "description": "No HP admin"
                                    },
                                    "password": {
                                        "type": "string",
                                        "description": "Min. 8 karakter"
                                    },
                                    "password_confirmation": {
                                        "type": "string",
                                        "description": "Ulangi password"
                                    }
                                },
                                "required": [
                                    "school_name",
                                    "name",
                                    "email",
                                    "password",
                                    "password_confirmation"
                                ]
                            },
                            "example": {
                                "school_name": "SMP Harapan Bangsa",
                                "level": "SMP",
                                "npsn": "10501234",
                                "city": "Jambi",
                                "school_phone": "0741-123456",
                                "name": "Rina Bendahara",
                                "email": "rina@harapan.sch.id",
                                "phone": "081234567890",
                                "password": "rahasia123",
                                "password_confirmation": "rahasia123"
                            }
                        }
                    }
                }
            }
        },
        "/auth/login": {
            "post": {
                "tags": [
                    "Autentikasi Admin"
                ],
                "summary": "Login admin",
                "description": "Tukar email & kata sandi dengan token. Superadmin juga login di sini (tokennya hanya untuk `/super/*`).",
                "operationId": "post_auth_login",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Login berhasil",
                                    "data": {
                                        "user": {
                                            "id": 14,
                                            "name": "Admin API",
                                            "email": "api7001@uji.test",
                                            "phone": null,
                                            "role": "admin",
                                            "position": "Bendahara",
                                            "is_active": true,
                                            "school_id": 9,
                                            "last_login_at": "2026-11-13T06:21:03+07:00",
                                            "created_at": "2026-11-13T06:21:02+07:00"
                                        },
                                        "school": {
                                            "id": 9,
                                            "name": "SMA API Test 7001",
                                            "slug": "sma-api-test-7001",
                                            "npsn": null,
                                            "level": "SMA",
                                            "address": null,
                                            "city": "Jambi",
                                            "phone": null,
                                            "email": "api7001@uji.test",
                                            "logo_url": null,
                                            "payment_instructions": "Pembayaran dapat dilakukan:\n1. Tunai di ruang Tata Usaha (Senin–Jumat, 07.30–14.00).\n2. Transfer ke rekening sekolah, lalu kirim bukti transfer ke bendahara.",
                                            "bank_accounts": null,
                                            "principal_name": null,
                                            "principal_nip": null,
                                            "treasurer_name": "Admin API",
                                            "treasurer_nip": null,
                                            "receipt_prefix": "KW",
                                            "receipt_footer": null,
                                            "status": "active",
                                            "created_at": "2026-11-13T06:21:02+07:00"
                                        },
                                        "token": {
                                            "access_token": "14|Xk3vN0pQ...contoh-token...9aZ",
                                            "token_type": "Bearer",
                                            "expires_at": "2026-12-13T06:21:03+07:00"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "description": "Email"
                                    },
                                    "password": {
                                        "type": "string",
                                        "description": "Kata sandi"
                                    },
                                    "device_name": {
                                        "type": "string",
                                        "description": "Nama perangkat"
                                    }
                                },
                                "required": [
                                    "email",
                                    "password"
                                ]
                            },
                            "example": {
                                "email": "bendahara@smpn1.demo",
                                "password": "password",
                                "device_name": "postman"
                            }
                        }
                    }
                }
            }
        },
        "/auth/me": {
            "get": {
                "tags": [
                    "Autentikasi Admin"
                ],
                "summary": "Profil admin & sekolah",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_auth_me",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "user": {
                                            "id": 14,
                                            "name": "Admin API",
                                            "email": "api7001@uji.test",
                                            "phone": null,
                                            "role": "admin",
                                            "position": "Bendahara",
                                            "is_active": true,
                                            "school_id": 9,
                                            "last_login_at": "2026-11-13T06:21:03+07:00",
                                            "created_at": "2026-11-13T06:21:02+07:00"
                                        },
                                        "school": {
                                            "id": 9,
                                            "name": "SMA API Test 7001",
                                            "slug": "sma-api-test-7001",
                                            "npsn": null,
                                            "level": "SMA",
                                            "address": null,
                                            "city": "Jambi",
                                            "phone": null,
                                            "email": "api7001@uji.test",
                                            "logo_url": null,
                                            "payment_instructions": "Pembayaran dapat dilakukan:\n1. Tunai di ruang Tata Usaha (Senin–Jumat, 07.30–14.00).\n2. Transfer ke rekening sekolah, lalu kirim bukti transfer ke bendahara.",
                                            "bank_accounts": null,
                                            "principal_name": null,
                                            "principal_nip": null,
                                            "treasurer_name": "Admin API",
                                            "treasurer_nip": null,
                                            "receipt_prefix": "KW",
                                            "receipt_footer": null,
                                            "status": "active",
                                            "created_at": "2026-11-13T06:21:02+07:00"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Autentikasi Admin"
                ],
                "summary": "Ubah profil",
                "description": "Memerlukan token **admin**.",
                "operationId": "put_auth_me",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Profil diperbarui",
                                    "data": {
                                        "id": 14,
                                        "name": "Admin API",
                                        "email": "api7001@uji.test",
                                        "phone": "081200000000",
                                        "role": "admin",
                                        "position": "Bendahara",
                                        "is_active": true,
                                        "school_id": 9,
                                        "last_login_at": "2026-11-13T06:21:03+07:00",
                                        "created_at": "2026-11-13T06:21:02+07:00"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "Nama"
                                    },
                                    "phone": {
                                        "type": "string",
                                        "description": "No HP"
                                    },
                                    "position": {
                                        "type": "string",
                                        "description": "Jabatan"
                                    }
                                }
                            },
                            "example": {
                                "name": "Rina S.",
                                "phone": "0812000000",
                                "position": "Bendahara"
                            }
                        }
                    }
                }
            }
        },
        "/auth/password": {
            "put": {
                "tags": [
                    "Autentikasi Admin"
                ],
                "summary": "Ganti kata sandi",
                "description": "Token lain milik user dicabut otomatis.\n\nMemerlukan token **admin**.",
                "operationId": "put_auth_password",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Kata sandi diganti. Token di perangkat lain telah dicabut.",
                                    "data": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "current_password": {
                                        "type": "string",
                                        "description": "Kata sandi saat ini"
                                    },
                                    "password": {
                                        "type": "string",
                                        "description": "Kata sandi baru (min. 8)"
                                    },
                                    "password_confirmation": {
                                        "type": "string",
                                        "description": "Ulangi"
                                    }
                                },
                                "required": [
                                    "current_password",
                                    "password",
                                    "password_confirmation"
                                ]
                            },
                            "example": {
                                "current_password": "password",
                                "password": "passwordbaru",
                                "password_confirmation": "passwordbaru"
                            }
                        }
                    }
                }
            }
        },
        "/auth/logout": {
            "post": {
                "tags": [
                    "Autentikasi Admin"
                ],
                "summary": "Logout (cabut token)",
                "description": "Memerlukan token **admin**.",
                "operationId": "post_auth_logout",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Logout berhasil. Token tidak berlaku lagi.",
                                    "data": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/school": {
            "get": {
                "tags": [
                    "Sekolah & Pengguna"
                ],
                "summary": "Profil sekolah + status wizard",
                "description": "`setup` berisi 5 langkah wizard awal dan status selesai/belum.\n\nMemerlukan token **admin**.",
                "operationId": "get_school",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 9,
                                        "name": "SMA API Test 7001",
                                        "slug": "sma-api-test-7001",
                                        "npsn": null,
                                        "level": "SMA",
                                        "address": null,
                                        "city": "Jambi",
                                        "phone": null,
                                        "email": "api7001@uji.test",
                                        "logo_url": null,
                                        "payment_instructions": "Pembayaran dapat dilakukan:\n1. Tunai di ruang Tata Usaha (Senin–Jumat, 07.30–14.00).\n2. Transfer ke rekening sekolah, lalu kirim bukti transfer ke bendahara.",
                                        "bank_accounts": null,
                                        "principal_name": null,
                                        "principal_nip": null,
                                        "treasurer_name": "Admin API",
                                        "treasurer_nip": null,
                                        "receipt_prefix": "KW",
                                        "receipt_footer": null,
                                        "status": "active",
                                        "created_at": "2026-11-13T06:21:02+07:00",
                                        "setup": [
                                            {
                                                "key": "tahun",
                                                "title": "Tahun ajaran",
                                                "desc": "Tentukan tahun ajaran yang sedang berjalan.",
                                                "done": false,
                                                "icon": "calendar3"
                                            },
                                            {
                                                "key": "kelas",
                                                "title": "Kelas",
                                                "desc": "Buat daftar kelas/rombel beserta tingkatnya.",
                                                "done": false,
                                                "icon": "diagram-3"
                                            },
                                            "…"
                                        ],
                                        "wali_login_url": "https://belajar-api.unama.ac.id/spp/wali/masuk?sekolah=sma-api-test-7001"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Sekolah & Pengguna"
                ],
                "summary": "Ubah pengaturan sekolah",
                "description": "Kirim hanya field yang diubah. Untuk upload logo gunakan `POST /school` dengan multipart field `logo`.\n\nMemerlukan token **admin**.",
                "operationId": "put_school",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Pengaturan sekolah disimpan",
                                    "data": {
                                        "id": 9,
                                        "name": "SMA API Test 7001",
                                        "slug": "sma-api-test-7001",
                                        "npsn": null,
                                        "level": "SMA",
                                        "address": "Jl. Uji API No. 1",
                                        "city": "Jambi",
                                        "phone": null,
                                        "email": "api7001@uji.test",
                                        "logo_url": null,
                                        "payment_instructions": "Pembayaran dapat dilakukan:\n1. Tunai di ruang Tata Usaha (Senin–Jumat, 07.30–14.00).\n2. Transfer ke rekening sekolah, lalu kirim bukti transfer ke bendahara.",
                                        "bank_accounts": "Bank Jambi 999",
                                        "principal_name": "Dr. Kepala",
                                        "principal_nip": null,
                                        "treasurer_name": "Admin API",
                                        "treasurer_nip": null,
                                        "receipt_prefix": "API",
                                        "receipt_footer": null,
                                        "status": "active",
                                        "created_at": "2026-11-13T06:21:02+07:00"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "Nama sekolah"
                                    },
                                    "address": {
                                        "type": "string",
                                        "description": "Alamat"
                                    },
                                    "principal_name": {
                                        "type": "string",
                                        "description": "Kepala sekolah"
                                    },
                                    "treasurer_name": {
                                        "type": "string",
                                        "description": "Bendahara"
                                    },
                                    "bank_accounts": {
                                        "type": "string",
                                        "description": "Rekening"
                                    },
                                    "payment_instructions": {
                                        "type": "string",
                                        "description": "Instruksi bayar"
                                    },
                                    "receipt_prefix": {
                                        "type": "string",
                                        "description": "Awalan no kuitansi (huruf/angka)"
                                    }
                                }
                            },
                            "example": {
                                "address": "Jl. Merdeka No. 1",
                                "principal_name": "Drs. Ahmad",
                                "treasurer_name": "Rina",
                                "bank_accounts": "Bank Jambi 123 a.n. Sekolah",
                                "payment_instructions": "Bayar di TU",
                                "receipt_prefix": "KW"
                            }
                        }
                    }
                }
            }
        },
        "/users": {
            "get": {
                "tags": [
                    "Sekolah & Pengguna"
                ],
                "summary": "Daftar admin sekolah",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_users",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Cari nama/email",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 14,
                                            "name": "Admin API",
                                            "email": "api7001@uji.test",
                                            "phone": "081200000000",
                                            "role": "admin",
                                            "position": "Bendahara",
                                            "is_active": true,
                                            "school_id": 9,
                                            "last_login_at": "2026-11-13T06:21:03+07:00",
                                            "created_at": "2026-11-13T06:21:02+07:00"
                                        },
                                        {
                                            "id": 15,
                                            "name": "Operator Satu",
                                            "email": "op7001@uji.test",
                                            "phone": null,
                                            "role": "admin",
                                            "position": "Operator",
                                            "is_active": true,
                                            "school_id": 9,
                                            "last_login_at": null,
                                            "created_at": "2026-11-13T06:21:03+07:00"
                                        }
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 20,
                                        "total": 2,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 2
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Sekolah & Pengguna"
                ],
                "summary": "Tambah admin",
                "description": "Memerlukan token **admin**.",
                "operationId": "post_users",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Pengguna ditambahkan",
                                    "data": {
                                        "id": 15,
                                        "name": "Operator Satu",
                                        "email": "op7001@uji.test",
                                        "phone": null,
                                        "role": "admin",
                                        "position": "Operator",
                                        "is_active": true,
                                        "school_id": 9,
                                        "last_login_at": null,
                                        "created_at": "2026-11-13T06:21:03+07:00"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "Nama"
                                    },
                                    "email": {
                                        "type": "string",
                                        "description": "Email unik"
                                    },
                                    "password": {
                                        "type": "string",
                                        "description": "Min. 8"
                                    },
                                    "position": {
                                        "type": "string",
                                        "description": "Jabatan"
                                    }
                                },
                                "required": [
                                    "name",
                                    "email",
                                    "password"
                                ]
                            },
                            "example": {
                                "name": "Operator TU",
                                "email": "operator@contoh.sch.id",
                                "password": "operator123",
                                "position": "Operator"
                            }
                        }
                    }
                }
            }
        },
        "/users/{id}": {
            "get": {
                "tags": [
                    "Sekolah & Pengguna"
                ],
                "summary": "Detail admin",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_users_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID user",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 15,
                                        "name": "Operator Satu",
                                        "email": "op7001@uji.test",
                                        "phone": null,
                                        "role": "admin",
                                        "position": "Operator",
                                        "is_active": true,
                                        "school_id": 9,
                                        "last_login_at": null,
                                        "created_at": "2026-11-13T06:21:03+07:00"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Sekolah & Pengguna"
                ],
                "summary": "Ubah admin",
                "description": "Memerlukan token **admin**.",
                "operationId": "put_users_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID user",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Pengguna diperbarui",
                                    "data": {
                                        "id": 15,
                                        "name": "Operator Satu",
                                        "email": "op7001@uji.test",
                                        "phone": null,
                                        "role": "admin",
                                        "position": "Operator TU",
                                        "is_active": true,
                                        "school_id": 9,
                                        "last_login_at": null,
                                        "created_at": "2026-11-13T06:21:03+07:00"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "Nama"
                                    },
                                    "password": {
                                        "type": "string",
                                        "description": "Kata sandi baru"
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "description": "false = nonaktif (token dicabut)"
                                    }
                                }
                            },
                            "example": {
                                "is_active": true
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Sekolah & Pengguna"
                ],
                "summary": "Hapus admin",
                "description": "Memerlukan token **admin**.",
                "operationId": "delete_users_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID user",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Pengguna dihapus",
                                    "data": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/academic-years": {
            "get": {
                "tags": [
                    "Tahun Ajaran"
                ],
                "summary": "Daftar tahun ajaran",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_academic_years",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 13,
                                            "name": "2027/2028",
                                            "start_date": "2027-07-01",
                                            "end_date": "2028-06-30",
                                            "is_active": false,
                                            "periods": [
                                                "2027-07",
                                                "2027-08",
                                                "…"
                                            ]
                                        },
                                        {
                                            "id": 12,
                                            "name": "2026/2027",
                                            "start_date": "2026-07-01",
                                            "end_date": "2027-06-30",
                                            "is_active": true,
                                            "periods": [
                                                "2026-07",
                                                "2026-08",
                                                "…"
                                            ]
                                        }
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 20,
                                        "total": 2,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 2
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Tahun Ajaran"
                ],
                "summary": "Tambah tahun ajaran",
                "description": "Memerlukan token **admin**.",
                "operationId": "post_academic_years",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Tahun ajaran ditambahkan",
                                    "data": {
                                        "id": 12,
                                        "name": "2026/2027",
                                        "start_date": "2026-07-01",
                                        "end_date": "2027-06-30",
                                        "is_active": true,
                                        "periods": [
                                            "2026-07",
                                            "2026-08",
                                            "…"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "Format YYYY/YYYY"
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Tanggal mulai"
                                    },
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Tanggal selesai"
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "description": "Langsung aktifkan"
                                    }
                                },
                                "required": [
                                    "name",
                                    "start_date",
                                    "end_date"
                                ]
                            },
                            "example": {
                                "name": "2026/2027",
                                "start_date": "2026-07-01",
                                "end_date": "2027-06-30",
                                "is_active": false
                            }
                        }
                    }
                }
            }
        },
        "/academic-years/{id}": {
            "get": {
                "tags": [
                    "Tahun Ajaran"
                ],
                "summary": "Detail",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_academic_years_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID tahun ajaran",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 12,
                                        "name": "2026/2027",
                                        "start_date": "2026-07-01",
                                        "end_date": "2027-06-30",
                                        "is_active": true,
                                        "periods": [
                                            "2026-07",
                                            "2026-08",
                                            "…"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Tahun Ajaran"
                ],
                "summary": "Ubah",
                "description": "Memerlukan token **admin**.",
                "operationId": "put_academic_years_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID tahun ajaran",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Tahun ajaran diperbarui",
                                    "data": {
                                        "id": 13,
                                        "name": "2027/2028",
                                        "start_date": "2027-07-01",
                                        "end_date": "2028-06-29",
                                        "is_active": false,
                                        "periods": [
                                            "2027-07",
                                            "2027-08",
                                            "…"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Tanggal selesai"
                                    }
                                }
                            },
                            "example": {
                                "end_date": "2027-06-30"
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Tahun Ajaran"
                ],
                "summary": "Hapus (jika belum ada tagihan)",
                "description": "Memerlukan token **admin**.",
                "operationId": "delete_academic_years_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID tahun ajaran",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Tahun ajaran dihapus",
                                    "data": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/academic-years/{id}/activate": {
            "post": {
                "tags": [
                    "Tahun Ajaran"
                ],
                "summary": "Jadikan aktif",
                "description": "Memerlukan token **admin**.",
                "operationId": "post_academic_years_id_activate",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID tahun ajaran",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Tahun ajaran 2027/2028 sekarang aktif",
                                    "data": {
                                        "id": 13,
                                        "name": "2027/2028",
                                        "start_date": "2027-07-01",
                                        "end_date": "2028-06-29",
                                        "is_active": true,
                                        "periods": [
                                            "2027-07",
                                            "2027-08",
                                            "…"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/classes": {
            "get": {
                "tags": [
                    "Kelas"
                ],
                "summary": "Daftar kelas",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_classes",
                "parameters": [
                    {
                        "name": "grade",
                        "in": "query",
                        "required": false,
                        "description": "Filter tingkat",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Cari nama",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 48,
                                            "name": "Kosong",
                                            "grade": 1,
                                            "homeroom_teacher": null,
                                            "students_count": 0
                                        },
                                        {
                                            "id": 45,
                                            "name": "X-1",
                                            "grade": 10,
                                            "homeroom_teacher": "Bu Sari",
                                            "students_count": 0
                                        },
                                        "…"
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 20,
                                        "total": 4,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 4
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Kelas"
                ],
                "summary": "Tambah kelas",
                "description": "Jika `grade` tidak dikirim, tingkat ditebak dari nama (VII A → 7, X IPA → 10).\n\nMemerlukan token **admin**.",
                "operationId": "post_classes",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Kelas ditambahkan",
                                    "data": {
                                        "id": 45,
                                        "name": "X-1",
                                        "grade": 10,
                                        "homeroom_teacher": "Bu Sari",
                                        "students_count": null
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "Nama kelas (unik)"
                                    },
                                    "grade": {
                                        "type": "integer",
                                        "description": "Tingkat"
                                    },
                                    "homeroom_teacher": {
                                        "type": "string",
                                        "description": "Wali kelas"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "VII C",
                                "grade": 7,
                                "homeroom_teacher": "Bu Sari"
                            }
                        }
                    }
                }
            }
        },
        "/classes/{id}": {
            "get": {
                "tags": [
                    "Kelas"
                ],
                "summary": "Detail kelas",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_classes_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID kelas",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 45,
                                        "name": "X-1",
                                        "grade": 10,
                                        "homeroom_teacher": "Bu Sari",
                                        "students_count": 0
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Kelas"
                ],
                "summary": "Ubah kelas",
                "description": "Memerlukan token **admin**.",
                "operationId": "put_classes_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID kelas",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Kelas diperbarui",
                                    "data": {
                                        "id": 45,
                                        "name": "X-1",
                                        "grade": 10,
                                        "homeroom_teacher": "Pak Budi",
                                        "students_count": null
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "homeroom_teacher": {
                                        "type": "string",
                                        "description": "Wali kelas"
                                    }
                                }
                            },
                            "example": {
                                "homeroom_teacher": "Pak Budi"
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Kelas"
                ],
                "summary": "Hapus kelas kosong",
                "description": "Memerlukan token **admin**.",
                "operationId": "delete_classes_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID kelas",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Kelas dihapus",
                                    "data": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/classes/promote": {
            "get": {
                "tags": [
                    "Kelas"
                ],
                "summary": "Saran kenaikan kelas",
                "description": "Objek `{class_id_asal: class_id_tujuan | \"lulus\" | \"tetap\"}` hasil tebakan otomatis.\n\nMemerlukan token **admin**.",
                "operationId": "get_classes_promote",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Saran pemetaan kelas asal -> tujuan",
                                    "data": {
                                        "51": "tetap",
                                        "49": "tetap",
                                        "50": "tetap",
                                        "45": 46,
                                        "46": 47,
                                        "47": "lulus"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Kelas"
                ],
                "summary": "Proses kenaikan kelas massal",
                "description": "Siswa aktif di kelas asal dipindah ke kelas tujuan, atau status menjadi `lulus`. Diproses serentak sehingga tidak ada siswa yang \"naik dua kali\".\n\nMemerlukan token **admin**.",
                "operationId": "post_classes_promote",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Kenaikan kelas selesai",
                                    "data": {
                                        "moved": 2,
                                        "graduated": 0,
                                        "stayed": 0
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "map": {
                                        "type": "object",
                                        "description": "Pemetaan {id_asal: id_tujuan|\"lulus\"|\"tetap\"}"
                                    }
                                },
                                "required": [
                                    "map"
                                ]
                            },
                            "example": {
                                "map": {
                                    "1": 3,
                                    "3": "lulus"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/students": {
            "get": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Daftar & cari siswa",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_students",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Cari nama/NIS/NISN/nama wali",
                        "schema": {
                            "type": "string"
                        },
                        "example": "ahmad"
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter kelas",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "aktif (bawaan) / lulus / pindah / keluar / semua",
                        "schema": {
                            "type": "string"
                        },
                        "example": "aktif"
                    },
                    {
                        "name": "gender",
                        "in": "query",
                        "required": false,
                        "description": "L / P",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "with_outstanding",
                        "in": "query",
                        "required": false,
                        "description": "Sertakan total tunggakan per siswa",
                        "schema": {
                            "type": "boolean"
                        },
                        "example": "true"
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "description": "name (bawaan) / nis",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 392,
                                            "nis": "2026112",
                                            "nisn": "0112340444",
                                            "name": "Aisyah Ramadhan",
                                            "gender": "P",
                                            "class": {
                                                "id": 51,
                                                "name": "VII A",
                                                "grade": 7
                                            },
                                            "entry_year": 2026,
                                            "guardian_name": "Ibu Mariani Ramadhan",
                                            "guardian_phone": "081255501356",
                                            "email": "aisyah.12@contoh.id",
                                            "address": "Jl. Sultan Thaha No. 22, Jambi",
                                            "status": "aktif",
                                            "has_portal_access": true,
                                            "pin_changed_by_guardian": false,
                                            "created_at": "2026-11-13T06:21:05+07:00",
                                            "outstanding": 0
                                        },
                                        {
                                            "id": 391,
                                            "nis": "2026111",
                                            "nisn": "0112340407",
                                            "name": "Aldi Saputra",
                                            "gender": "L",
                                            "class": {
                                                "id": 50,
                                                "name": "VII C",
                                                "grade": 7
                                            },
                                            "entry_year": 2026,
                                            "guardian_name": "Ibu Sri Saputra",
                                            "guardian_phone": "081255501243",
                                            "email": null,
                                            "address": "Jl. Hayam Wuruk No. 21, Jambi",
                                            "status": "aktif",
                                            "has_portal_access": true,
                                            "pin_changed_by_guardian": false,
                                            "created_at": "2026-11-13T06:21:05+07:00",
                                            "outstanding": 0
                                        },
                                        "…"
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 3,
                                        "total": 31,
                                        "last_page": 11,
                                        "from": 1,
                                        "to": 3
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Tambah siswa",
                "description": "Respons berisi `portal_pin` untuk login wali (dibuat acak bila tidak dikirim).\n\nMemerlukan token **admin**.",
                "operationId": "post_students",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Siswa ditambahkan",
                                    "data": {
                                        "id": 380,
                                        "nis": "S700101",
                                        "nisn": null,
                                        "name": "Dewi Lestari",
                                        "gender": "P",
                                        "class": {
                                            "id": 45,
                                            "name": "X-1",
                                            "grade": 10
                                        },
                                        "entry_year": 2026,
                                        "guardian_name": "Ibu Lestari",
                                        "guardian_phone": "081311112222",
                                        "email": null,
                                        "address": null,
                                        "status": "aktif",
                                        "has_portal_access": true,
                                        "pin_changed_by_guardian": false,
                                        "created_at": "2026-11-13T06:21:05+07:00",
                                        "portal_pin": "364832"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "nis": {
                                        "type": "string",
                                        "description": "NIS unik"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "Nama"
                                    },
                                    "nisn": {
                                        "type": "string",
                                        "description": "NISN (angka)"
                                    },
                                    "gender": {
                                        "type": "string",
                                        "description": "L/P"
                                    },
                                    "class_id": {
                                        "type": "integer",
                                        "description": "ID kelas"
                                    },
                                    "entry_year": {
                                        "type": "integer",
                                        "description": "Angkatan"
                                    },
                                    "guardian_name": {
                                        "type": "string",
                                        "description": "Nama wali"
                                    },
                                    "guardian_phone": {
                                        "type": "string",
                                        "description": "HP wali"
                                    },
                                    "email": {
                                        "type": "string",
                                        "description": "Email"
                                    },
                                    "address": {
                                        "type": "string",
                                        "description": "Alamat"
                                    },
                                    "portal_pin": {
                                        "type": "string",
                                        "description": "PIN portal wali (min 4)"
                                    }
                                },
                                "required": [
                                    "nis",
                                    "name"
                                ]
                            },
                            "example": {
                                "nis": "2026999",
                                "name": "Dewi Lestari",
                                "nisn": "0101010101",
                                "gender": "P",
                                "class_id": 1,
                                "entry_year": 2026,
                                "guardian_name": "Ibu Lestari",
                                "guardian_phone": "081311112222",
                                "address": "Jambi"
                            }
                        }
                    }
                }
            }
        },
        "/students/{id}": {
            "get": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Detail siswa",
                "description": "Termasuk `outstanding`, PIN awal (jika wali belum mengganti), dan potongan.\n\nMemerlukan token **admin**.",
                "operationId": "get_students_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID siswa",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 380,
                                        "nis": "S700101",
                                        "nisn": null,
                                        "name": "Dewi Lestari",
                                        "gender": "P",
                                        "class": {
                                            "id": 45,
                                            "name": "X-1",
                                            "grade": 10
                                        },
                                        "entry_year": 2026,
                                        "guardian_name": "Ibu Lestari",
                                        "guardian_phone": "081311112222",
                                        "email": null,
                                        "address": null,
                                        "status": "aktif",
                                        "has_portal_access": true,
                                        "pin_changed_by_guardian": false,
                                        "created_at": "2026-11-13T06:21:05+07:00",
                                        "outstanding": 0,
                                        "portal_pin": "364832",
                                        "adjustments": []
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Ubah siswa",
                "description": "Memerlukan token **admin**.",
                "operationId": "put_students_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID siswa",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Data siswa diperbarui",
                                    "data": {
                                        "id": 380,
                                        "nis": "S700101",
                                        "nisn": null,
                                        "name": "Dewi Lestari",
                                        "gender": "P",
                                        "class": {
                                            "id": 45,
                                            "name": "X-1",
                                            "grade": 10
                                        },
                                        "entry_year": 2026,
                                        "guardian_name": "Ibu Lestari",
                                        "guardian_phone": "081299998888",
                                        "email": null,
                                        "address": null,
                                        "status": "aktif",
                                        "has_portal_access": true,
                                        "pin_changed_by_guardian": false,
                                        "created_at": "2026-11-13T06:21:05+07:00"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "class_id": {
                                        "type": "integer",
                                        "description": "Pindah kelas"
                                    },
                                    "status": {
                                        "type": "string",
                                        "description": "aktif/lulus/pindah/keluar"
                                    },
                                    "guardian_phone": {
                                        "type": "string",
                                        "description": "HP wali"
                                    }
                                }
                            },
                            "example": {
                                "class_id": 2,
                                "status": "aktif",
                                "guardian_phone": "081299998888"
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Hapus siswa (tanpa riwayat bayar)",
                "description": "Memerlukan token **admin**.",
                "operationId": "delete_students_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID siswa",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/students/{id}/reset-pin": {
            "post": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Buat PIN portal wali baru",
                "description": "Memerlukan token **admin**.",
                "operationId": "post_students_id_reset_pin",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID siswa",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "PIN baru dibuat",
                                    "data": {
                                        "student_id": 380,
                                        "nis": "S700101",
                                        "school_slug": "sma-api-test-7001",
                                        "portal_pin": "654321"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "pin": {
                                        "type": "string",
                                        "description": "PIN tertentu (kosong = acak 6 digit)"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/students/{id}/invoices": {
            "get": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Tagihan siswa",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_students_id_invoices",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID siswa",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "terbuka / belum / sebagian / lunas / batal",
                        "schema": {
                            "type": "string"
                        },
                        "example": "terbuka"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 4983,
                                            "title": "SPP Juli 2026",
                                            "fee_type": {
                                                "id": 24,
                                                "name": "SPP",
                                                "frequency": "bulanan"
                                            },
                                            "academic_year_id": 12,
                                            "period": "2026-07",
                                            "amount": 200000,
                                            "discount": 100000,
                                            "total": 100000,
                                            "paid_amount": 0,
                                            "remaining": 100000,
                                            "status": "belum",
                                            "status_label": "Belum bayar",
                                            "due_date": "2026-07-10",
                                            "is_overdue": true,
                                            "note": "Beasiswa prestasi",
                                            "cancel_reason": null,
                                            "created_at": "2026-11-13T06:21:08+07:00"
                                        },
                                        {
                                            "id": 4984,
                                            "title": "SPP Agustus 2026",
                                            "fee_type": {
                                                "id": 24,
                                                "name": "SPP",
                                                "frequency": "bulanan"
                                            },
                                            "academic_year_id": 12,
                                            "period": "2026-08",
                                            "amount": 200000,
                                            "discount": 100000,
                                            "total": 100000,
                                            "paid_amount": 0,
                                            "remaining": 100000,
                                            "status": "belum",
                                            "status_label": "Belum bayar",
                                            "due_date": "2026-08-10",
                                            "is_overdue": true,
                                            "note": "Beasiswa prestasi",
                                            "cancel_reason": null,
                                            "created_at": "2026-11-13T06:21:08+07:00"
                                        },
                                        "…"
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 50,
                                        "total": 14,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 14,
                                        "outstanding": 1525000
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/students/{id}/payments": {
            "get": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Riwayat pembayaran siswa",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_students_id_payments",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID siswa",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 1221,
                                            "receipt_no": "API-2026-00001",
                                            "paid_at": "2026-11-13T06:21:09+07:00",
                                            "method": "tunai",
                                            "amount": 140000,
                                            "reference": null,
                                            "payer_name": "Ibu Lestari",
                                            "note": null,
                                            "received_by": "Admin API",
                                            "status": "sah",
                                            "cancelled_at": null,
                                            "cancel_reason": null,
                                            "student": {
                                                "id": 380,
                                                "nis": "S700101",
                                                "name": "Dewi Lestari",
                                                "class": "X-1"
                                            },
                                            "items": [
                                                {
                                                    "invoice_id": 4983,
                                                    "title": "SPP Juli 2026",
                                                    "amount": 100000
                                                },
                                                {
                                                    "invoice_id": 4984,
                                                    "title": "SPP Agustus 2026",
                                                    "amount": 40000
                                                }
                                            ]
                                        },
                                        {
                                            "id": 1222,
                                            "receipt_no": "API-2026-00002",
                                            "paid_at": "2026-11-13T06:21:09+07:00",
                                            "method": "transfer",
                                            "amount": 160000,
                                            "reference": "BRI 12/11",
                                            "payer_name": null,
                                            "note": null,
                                            "received_by": "Admin API",
                                            "status": "sah",
                                            "cancelled_at": null,
                                            "cancel_reason": null,
                                            "student": {
                                                "id": 380,
                                                "nis": "S700101",
                                                "name": "Dewi Lestari",
                                                "class": "X-1"
                                            },
                                            "items": [
                                                {
                                                    "invoice_id": 4984,
                                                    "title": "SPP Agustus 2026",
                                                    "amount": 60000
                                                },
                                                {
                                                    "invoice_id": 4985,
                                                    "title": "SPP September 2026",
                                                    "amount": 100000
                                                }
                                            ]
                                        }
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 20,
                                        "total": 2,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 2
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/students/{id}/card": {
            "get": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Kartu SPP (matriks bulan)",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_students_id_card",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID siswa",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "description": "Bawaan: tahun aktif",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "required": false,
                        "description": "json (bawaan) / xlsx",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "student": {
                                            "id": 380,
                                            "nis": "S700101",
                                            "nisn": null,
                                            "name": "Dewi Lestari",
                                            "gender": "P",
                                            "class": {
                                                "id": 45,
                                                "name": "X-1",
                                                "grade": 10
                                            },
                                            "entry_year": 2026,
                                            "guardian_name": "Ibu Lestari",
                                            "guardian_phone": "081299998888",
                                            "email": null,
                                            "address": null,
                                            "status": "aktif",
                                            "has_portal_access": true,
                                            "pin_changed_by_guardian": false,
                                            "created_at": "2026-11-13T06:21:05+07:00"
                                        },
                                        "year": {
                                            "id": 12,
                                            "name": "2026/2027",
                                            "start_date": "2026-07-01",
                                            "end_date": "2027-06-30",
                                            "is_active": true,
                                            "periods": [
                                                "2026-07",
                                                "2026-08",
                                                "…"
                                            ]
                                        },
                                        "periods": [
                                            "2026-07",
                                            "2026-08",
                                            "…"
                                        ],
                                        "period_labels": [
                                            "Juli 2026",
                                            "Agustus 2026",
                                            "…"
                                        ],
                                        "monthly": [
                                            {
                                                "fee_type": "SPP",
                                                "months": {
                                                    "2026-07": {
                                                        "invoice_id": 4983,
                                                        "total": 100000,
                                                        "paid": 100000,
                                                        "status": "lunas",
                                                        "paid_at": "2026-11-13",
                                                        "receipt_no": "API-2026-00001"
                                                    },
                                                    "2026-08": {
                                                        "invoice_id": 4984,
                                                        "total": 100000,
                                                        "paid": 100000,
                                                        "status": "lunas",
                                                        "paid_at": "2026-11-13",
                                                        "receipt_no": "API-2026-00001"
                                                    },
                                                    "2026-09": {
                                                        "invoice_id": 4985,
                                                        "total": 100000,
                                                        "paid": 100000,
                                                        "status": "lunas",
                                                        "paid_at": "2026-11-13",
                                                        "receipt_no": "API-2026-00002"
                                                    },
                                                    "2026-10": {
                                                        "invoice_id": 4986,
                                                        "total": 100000,
                                                        "paid": 0,
                                                        "status": "belum",
                                                        "paid_at": null,
                                                        "receipt_no": null
                                                    },
                                                    "2026-11": {
                                                        "invoice_id": 4987,
                                                        "total": 100000,
                                                        "paid": 0,
                                                        "status": "belum",
                                                        "paid_at": null,
                                                        "receipt_no": null
                                                    },
                                                    "2026-12": {
                                                        "invoice_id": 4988,
                                                        "total": 100000,
                                                        "paid": 0,
                                                        "status": "belum",
                                                        "paid_at": null,
                                                        "receipt_no": null
                                                    },
                                                    "2027-01": {
                                                        "invoice_id": 4989,
                                                        "total": 100000,
                                                        "paid": 0,
                                                        "status": "belum",
                                                        "paid_at": null,
                                                        "receipt_no": null
                                                    },
                                                    "2027-02": {
                                                        "invoice_id": 4990,
                                                        "total": 100000,
                                                        "paid": 0,
                                                        "status": "belum",
                                                        "paid_at": null,
                                                        "receipt_no": null
                                                    },
                                                    "2027-03": {
                                                        "invoice_id": 4991,
                                                        "total": 100000,
                                                        "paid": 0,
                                                        "status": "belum",
                                                        "paid_at": null,
                                                        "receipt_no": null
                                                    },
                                                    "2027-04": {
                                                        "invoice_id": 4992,
                                                        "total": 100000,
                                                        "paid": 0,
                                                        "status": "belum",
                                                        "paid_at": null,
                                                        "receipt_no": null
                                                    },
                                                    "2027-05": {
                                                        "invoice_id": 4993,
                                                        "total": 100000,
                                                        "paid": 0,
                                                        "status": "belum",
                                                        "paid_at": null,
                                                        "receipt_no": null
                                                    },
                                                    "2027-06": {
                                                        "invoice_id": 4994,
                                                        "total": 100000,
                                                        "paid": 0,
                                                        "status": "belum",
                                                        "paid_at": null,
                                                        "receipt_no": null
                                                    }
                                                }
                                            }
                                        ],
                                        "others": [
                                            {
                                                "invoice_id": 5355,
                                                "title": "Uang Kegiatan 2026/2027",
                                                "total": 300000,
                                                "paid": 0,
                                                "remaining": 300000,
                                                "status": "belum",
                                                "due_date": "2027-03-31"
                                            }
                                        ],
                                        "total": 1500000,
                                        "paid": 300000,
                                        "remaining": 1200000
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/students/export": {
            "get": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Export siswa ke Excel",
                "description": "Mengembalikan file `.xlsx` (bukan JSON).\n\nMemerlukan token **admin**.",
                "operationId": "get_students_export",
                "parameters": [
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter kelas",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter status",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "*/*": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/students/import/template": {
            "get": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Unduh template import",
                "description": "File `.xlsx` dengan kolom: `nis`, `nisn`, `nama`, `jenis_kelamin` (L/P), `kelas`, `angkatan`, `nama_wali`, `no_hp_wali`, `email`, `alamat` + sheet Petunjuk. Template juga tersedia publik di `/spp/template-import-siswa.xlsx`.\n\nMemerlukan token **admin**.",
                "operationId": "get_students_import_template",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "*/*": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/students/import": {
            "post": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Import (langkah 1: pratinjau)",
                "description": "Unggah file `.xlsx/.xls/.csv`. Setiap baris divalidasi: `action` = `baru` | `perbarui` | `lewati` | `error` beserta `errors` & `warnings`. Data BELUM disimpan, kecuali `commit=1`.\n\nMemerlukan token **admin**.",
                "operationId": "post_students_import",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Pratinjau import siap. Periksa baris error, lalu panggil POST /students/import/7/commit untuk menyimpan.",
                                    "data": {
                                        "import_id": 7,
                                        "filename": "contoh-import-siswa.xlsx",
                                        "mode": "tambah",
                                        "create_classes": true,
                                        "status": "pratinjau",
                                        "summary": {
                                            "total": 30,
                                            "baru": 30,
                                            "perbarui": 0,
                                            "lewati": 0,
                                            "error": 0,
                                            "kelas_baru": [
                                                "VII B",
                                                "VII C",
                                                "…"
                                            ]
                                        },
                                        "result": null,
                                        "commit_url": "https://belajar-api.unama.ac.id/api/spp/students/import/7/commit",
                                        "rows": [
                                            {
                                                "row": 2,
                                                "data": {
                                                    "nis": "2026101",
                                                    "nisn": "0112340037",
                                                    "nama": "Fajar Setiawan",
                                                    "jenis_kelamin": "L",
                                                    "kelas": "VII B",
                                                    "angkatan": "2026",
                                                    "nama_wali": "Bapak Hasan Setiawan",
                                                    "no_hp_wali": "081255500113",
                                                    "email": "",
                                                    "alamat": "Jl. Gatot Subroto No. 11, Jambi"
                                                },
                                                "action": "baru",
                                                "errors": [],
                                                "warnings": [
                                                    "Kelas \"VII B\" belum ada, akan dibuat otomatis"
                                                ]
                                            },
                                            {
                                                "row": 3,
                                                "data": {
                                                    "nis": "2026102",
                                                    "nisn": "0112340074",
                                                    "nama": "Zahra Hidayat",
                                                    "jenis_kelamin": "P",
                                                    "kelas": "VII C",
                                                    "angkatan": "2026",
                                                    "nama_wali": "Bapak Darmawan Hidayat",
                                                    "no_hp_wali": "081255500226",
                                                    "email": "",
                                                    "alamat": "Jl. Hayam Wuruk No. 12, Jambi"
                                                },
                                                "action": "baru",
                                                "errors": [],
                                                "warnings": [
                                                    "Kelas \"VII C\" belum ada, akan dibuat otomatis"
                                                ]
                                            },
                                            "…"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "File Excel/CSV maks 5 MB"
                                    },
                                    "mode": {
                                        "type": "string",
                                        "description": "tambah (NIS ada → lewati) / perbarui (NIS ada → timpa)"
                                    },
                                    "create_classes": {
                                        "type": "boolean",
                                        "description": "Buat kelas otomatis bila belum ada (bawaan 1)"
                                    },
                                    "commit": {
                                        "type": "boolean",
                                        "description": "1 = langsung simpan tanpa pratinjau"
                                    }
                                },
                                "required": [
                                    "file"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/students/import/{id}": {
            "get": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Lihat hasil pratinjau",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_students_import_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID import",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "only",
                        "in": "query",
                        "required": false,
                        "description": "Filter baris: baru / perbarui / lewati / error",
                        "schema": {
                            "type": "string"
                        },
                        "example": "error"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "import_id": 7,
                                        "filename": "contoh-import-siswa.xlsx",
                                        "mode": "tambah",
                                        "create_classes": true,
                                        "status": "pratinjau",
                                        "summary": {
                                            "baru": 30,
                                            "error": 0,
                                            "total": 30,
                                            "lewati": 0,
                                            "perbarui": 0,
                                            "kelas_baru": [
                                                "VII B",
                                                "VII C",
                                                "…"
                                            ]
                                        },
                                        "result": null,
                                        "commit_url": "https://belajar-api.unama.ac.id/api/spp/students/import/7/commit",
                                        "rows": [
                                            {
                                                "row": 2,
                                                "data": {
                                                    "nis": "2026101",
                                                    "nisn": "0112340037",
                                                    "nama": "Fajar Setiawan",
                                                    "jenis_kelamin": "L",
                                                    "kelas": "VII B",
                                                    "angkatan": "2026",
                                                    "nama_wali": "Bapak Hasan Setiawan",
                                                    "no_hp_wali": "081255500113",
                                                    "email": "",
                                                    "alamat": "Jl. Gatot Subroto No. 11, Jambi"
                                                },
                                                "action": "baru",
                                                "errors": [],
                                                "warnings": [
                                                    "Kelas \"VII B\" belum ada, akan dibuat otomatis"
                                                ]
                                            },
                                            {
                                                "row": 3,
                                                "data": {
                                                    "nis": "2026102",
                                                    "nisn": "0112340074",
                                                    "nama": "Zahra Hidayat",
                                                    "jenis_kelamin": "P",
                                                    "kelas": "VII C",
                                                    "angkatan": "2026",
                                                    "nama_wali": "Bapak Darmawan Hidayat",
                                                    "no_hp_wali": "081255500226",
                                                    "email": "",
                                                    "alamat": "Jl. Hayam Wuruk No. 12, Jambi"
                                                },
                                                "action": "baru",
                                                "errors": [],
                                                "warnings": [
                                                    "Kelas \"VII C\" belum ada, akan dibuat otomatis"
                                                ]
                                            },
                                            "…"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/students/import/{id}/commit": {
            "post": {
                "tags": [
                    "Siswa & Import Excel"
                ],
                "summary": "Import (langkah 2: simpan)",
                "description": "Menyimpan semua baris yang valid dalam satu transaksi. Baris error dilewati.\n\nMemerlukan token **admin**.",
                "operationId": "post_students_import_id_commit",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID import",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Import disimpan: 30 baru, 0 diperbarui, 0 dilewati, 0 gagal",
                                    "data": {
                                        "import_id": 7,
                                        "result": {
                                            "created": 30,
                                            "updated": 0,
                                            "skipped": 0,
                                            "failed": 0,
                                            "new_classes": [
                                                "VII B",
                                                "VII C",
                                                "…"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/fee-types": {
            "get": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Daftar jenis biaya + tarif",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_fee_types",
                "parameters": [
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "description": "Tarif tahun ini (bawaan aktif)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "frequency",
                        "in": "query",
                        "required": false,
                        "description": "bulanan / sekali",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 26,
                                            "name": "Hapus Saya",
                                            "code": null,
                                            "frequency": "sekali",
                                            "description": null,
                                            "is_active": true,
                                            "rates": []
                                        },
                                        {
                                            "id": 24,
                                            "name": "SPP",
                                            "code": "SPP",
                                            "frequency": "bulanan",
                                            "description": null,
                                            "is_active": true,
                                            "rates": [
                                                {
                                                    "id": 26,
                                                    "academic_year_id": 12,
                                                    "grade": null,
                                                    "class_id": null,
                                                    "amount": 200000,
                                                    "applies_to": "all"
                                                },
                                                {
                                                    "id": 27,
                                                    "academic_year_id": 12,
                                                    "grade": 12,
                                                    "class_id": null,
                                                    "amount": 225000,
                                                    "applies_to": "grade"
                                                }
                                            ]
                                        },
                                        "…"
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 20,
                                        "total": 3,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 3,
                                        "academic_year_id": 12
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Tambah jenis biaya",
                "description": "`rates` opsional, langsung mengatur tarif tahun ajaran aktif.\n\nMemerlukan token **admin**.",
                "operationId": "post_fee_types",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Jenis biaya ditambahkan",
                                    "data": {
                                        "id": 24,
                                        "name": "SPP",
                                        "code": "SPP",
                                        "frequency": "bulanan",
                                        "description": null,
                                        "is_active": true,
                                        "rates": [
                                            {
                                                "id": 26,
                                                "academic_year_id": 12,
                                                "grade": null,
                                                "class_id": null,
                                                "amount": 200000,
                                                "applies_to": "all"
                                            },
                                            {
                                                "id": 27,
                                                "academic_year_id": 12,
                                                "grade": 12,
                                                "class_id": null,
                                                "amount": 225000,
                                                "applies_to": "grade"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "Nama unik"
                                    },
                                    "frequency": {
                                        "type": "string",
                                        "description": "bulanan / sekali"
                                    },
                                    "code": {
                                        "type": "string",
                                        "description": "Kode"
                                    },
                                    "rates": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        },
                                        "description": "Daftar tarif [{amount, grade?, class_id?}]"
                                    }
                                },
                                "required": [
                                    "name",
                                    "frequency"
                                ]
                            },
                            "example": {
                                "name": "Uang Kegiatan",
                                "frequency": "sekali",
                                "code": "KEG",
                                "rates": [
                                    {
                                        "amount": 300000
                                    },
                                    {
                                        "grade": 9,
                                        "amount": 450000
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/fee-types/{id}": {
            "get": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Detail jenis biaya",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_fee_types_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID jenis biaya",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 24,
                                        "name": "SPP",
                                        "code": "SPP",
                                        "frequency": "bulanan",
                                        "description": null,
                                        "is_active": true,
                                        "rates": [
                                            {
                                                "id": 26,
                                                "academic_year_id": 12,
                                                "grade": null,
                                                "class_id": null,
                                                "amount": 200000,
                                                "applies_to": "all"
                                            },
                                            {
                                                "id": 27,
                                                "academic_year_id": 12,
                                                "grade": 12,
                                                "class_id": null,
                                                "amount": 225000,
                                                "applies_to": "grade"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Ubah jenis biaya",
                "description": "Memerlukan token **admin**.",
                "operationId": "put_fee_types_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID jenis biaya",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Jenis biaya diperbarui",
                                    "data": {
                                        "id": 25,
                                        "name": "Uang Kegiatan",
                                        "code": null,
                                        "frequency": "sekali",
                                        "description": "Kegiatan OSIS",
                                        "is_active": true,
                                        "rates": [
                                            {
                                                "id": 28,
                                                "academic_year_id": 12,
                                                "grade": null,
                                                "class_id": null,
                                                "amount": 300000,
                                                "applies_to": "all"
                                            },
                                            {
                                                "id": 29,
                                                "academic_year_id": 12,
                                                "grade": null,
                                                "class_id": 47,
                                                "amount": 500000,
                                                "applies_to": "class"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "is_active": {
                                        "type": "boolean",
                                        "description": "false = tidak bisa ditagihkan"
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "Keterangan"
                                    }
                                }
                            },
                            "example": {
                                "is_active": true
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Hapus (jika belum ada tagihan)",
                "description": "Memerlukan token **admin**.",
                "operationId": "delete_fee_types_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID jenis biaya",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Jenis biaya dihapus",
                                    "data": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/fee-types/{id}/rates": {
            "get": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Lihat tarif",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_fee_types_id_rates",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID jenis biaya",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "description": "Bawaan aktif",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "fee_type": {
                                            "id": 25,
                                            "name": "Uang Kegiatan",
                                            "code": null,
                                            "frequency": "sekali",
                                            "description": null,
                                            "is_active": true
                                        },
                                        "academic_year_id": 12,
                                        "rates": [
                                            {
                                                "id": 28,
                                                "academic_year_id": 12,
                                                "grade": null,
                                                "class_id": null,
                                                "amount": 300000,
                                                "applies_to": "all",
                                                "label": "Semua tingkat"
                                            },
                                            {
                                                "id": 29,
                                                "academic_year_id": 12,
                                                "grade": null,
                                                "class_id": 47,
                                                "amount": 500000,
                                                "applies_to": "class",
                                                "label": "Kelas XII-1"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Ganti seluruh tarif satu tahun ajaran",
                "description": "Tarif lama tahun ajaran tsb dihapus lalu diganti isi `rates`. Item tanpa `grade` & `class_id` = tarif umum.\n\nMemerlukan token **admin**.",
                "operationId": "put_fee_types_id_rates",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID jenis biaya",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Tarif disimpan",
                                    "data": {
                                        "fee_type_id": 25,
                                        "academic_year_id": 12,
                                        "saved": 2,
                                        "rates": [
                                            {
                                                "id": 28,
                                                "academic_year_id": 12,
                                                "grade": null,
                                                "class_id": null,
                                                "amount": 300000,
                                                "applies_to": "all"
                                            },
                                            {
                                                "id": 29,
                                                "academic_year_id": 12,
                                                "grade": null,
                                                "class_id": 47,
                                                "amount": 500000,
                                                "applies_to": "class"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "type": "integer",
                                        "description": "ID tahun ajaran"
                                    },
                                    "rates": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        },
                                        "description": "Daftar tarif"
                                    }
                                },
                                "required": [
                                    "academic_year_id",
                                    "rates"
                                ]
                            },
                            "example": {
                                "academic_year_id": 1,
                                "rates": [
                                    {
                                        "amount": 150000
                                    },
                                    {
                                        "grade": 9,
                                        "amount": 175000
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/adjustments": {
            "get": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Daftar potongan/beasiswa",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_adjustments",
                "parameters": [
                    {
                        "name": "student_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter siswa",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "fee_type_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter biaya",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 20,
                                            "student_id": 380,
                                            "student": {
                                                "id": 380,
                                                "nis": "S700101",
                                                "name": "Dewi Lestari"
                                            },
                                            "fee_type_id": 24,
                                            "fee_type": "SPP",
                                            "academic_year_id": null,
                                            "custom_amount": null,
                                            "discount_type": "persen",
                                            "discount_value": 50,
                                            "note": "Beasiswa prestasi",
                                            "summary": "Potongan 50%"
                                        }
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 20,
                                        "total": 1,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Simpan potongan / tarif khusus siswa",
                "description": "Isi `discount_type`+`discount_value` (potongan) dan/atau `custom_amount` (tarif khusus). Berlaku untuk tagihan yang dibuat setelahnya; jalankan generate dengan `update_unpaid=true` untuk memperbarui tagihan yang belum dibayar.\n\nMemerlukan token **admin**.",
                "operationId": "post_adjustments",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Potongan/tarif khusus disimpan. Berlaku untuk tagihan berikutnya (atau generate ulang dengan update_unpaid=true).",
                                    "data": {
                                        "id": 20,
                                        "student_id": 380,
                                        "student": {
                                            "id": 380,
                                            "nis": "S700101",
                                            "name": "Dewi Lestari"
                                        },
                                        "fee_type_id": 24,
                                        "fee_type": "SPP",
                                        "academic_year_id": null,
                                        "custom_amount": null,
                                        "discount_type": "persen",
                                        "discount_value": 50,
                                        "note": "Beasiswa prestasi",
                                        "summary": "Potongan 50%"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "student_id": {
                                        "type": "integer",
                                        "description": "ID siswa"
                                    },
                                    "fee_type_id": {
                                        "type": "integer",
                                        "description": "ID jenis biaya"
                                    },
                                    "academic_year_id": {
                                        "type": "integer",
                                        "description": "Kosong = semua tahun"
                                    },
                                    "discount_type": {
                                        "type": "string",
                                        "description": "nominal / persen"
                                    },
                                    "discount_value": {
                                        "type": "integer",
                                        "description": "Nilai potongan"
                                    },
                                    "custom_amount": {
                                        "type": "integer",
                                        "description": "Tarif khusus (Rp)"
                                    },
                                    "note": {
                                        "type": "string",
                                        "description": "Keterangan"
                                    }
                                },
                                "required": [
                                    "student_id",
                                    "fee_type_id"
                                ]
                            },
                            "example": {
                                "student_id": 1,
                                "fee_type_id": 1,
                                "discount_type": "persen",
                                "discount_value": 50,
                                "note": "Beasiswa prestasi"
                            }
                        }
                    }
                }
            }
        },
        "/adjustments/{id}": {
            "delete": {
                "tags": [
                    "Jenis Biaya, Tarif & Potongan"
                ],
                "summary": "Hapus potongan",
                "description": "Memerlukan token **admin**.",
                "operationId": "delete_adjustments_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID potongan",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Potongan dihapus",
                                    "data": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/invoices": {
            "get": {
                "tags": [
                    "Tagihan"
                ],
                "summary": "Daftar tagihan",
                "description": "`meta` berisi `sum_total`, `sum_paid`, `sum_remaining` sesuai filter.\n\nMemerlukan token **admin**.",
                "operationId": "get_invoices",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Cari nama/NIS",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "terbuka / belum / sebagian / lunas / batal",
                        "schema": {
                            "type": "string"
                        },
                        "example": "terbuka"
                    },
                    {
                        "name": "student_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter siswa",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter kelas",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "fee_type_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter biaya",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter TA",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "required": false,
                        "description": "YYYY-MM",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "overdue",
                        "in": "query",
                        "required": false,
                        "description": "1 = hanya lewat jatuh tempo",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 5386,
                                            "title": "Denda buku perpustakaan",
                                            "fee_type": {
                                                "id": 25,
                                                "name": "Uang Kegiatan",
                                                "frequency": "sekali"
                                            },
                                            "academic_year_id": 12,
                                            "period": null,
                                            "amount": 25000,
                                            "discount": 0,
                                            "total": 25000,
                                            "paid_amount": 0,
                                            "remaining": 25000,
                                            "status": "belum",
                                            "status_label": "Belum bayar",
                                            "due_date": "2026-12-31",
                                            "is_overdue": false,
                                            "note": null,
                                            "cancel_reason": null,
                                            "created_at": "2026-11-13T06:21:08+07:00",
                                            "student": {
                                                "id": 380,
                                                "nis": "S700101",
                                                "name": "Dewi Lestari",
                                                "class": "X-1"
                                            }
                                        },
                                        {
                                            "id": 5355,
                                            "title": "Uang Kegiatan 2026/2027",
                                            "fee_type": {
                                                "id": 25,
                                                "name": "Uang Kegiatan",
                                                "frequency": "sekali"
                                            },
                                            "academic_year_id": 12,
                                            "period": null,
                                            "amount": 300000,
                                            "discount": 0,
                                            "total": 300000,
                                            "paid_amount": 0,
                                            "remaining": 300000,
                                            "status": "belum",
                                            "status_label": "Belum bayar",
                                            "due_date": "2027-03-31",
                                            "is_overdue": false,
                                            "note": null,
                                            "cancel_reason": null,
                                            "created_at": "2026-11-13T06:21:08+07:00",
                                            "student": {
                                                "id": 380,
                                                "nis": "S700101",
                                                "name": "Dewi Lestari",
                                                "class": "X-1"
                                            }
                                        },
                                        "…"
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 3,
                                        "total": 14,
                                        "last_page": 5,
                                        "from": 1,
                                        "to": 3,
                                        "sum_total": 1525000,
                                        "sum_paid": 0,
                                        "sum_remaining": 1525000
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Tagihan"
                ],
                "summary": "Tagihan manual satu siswa",
                "description": "Memerlukan token **admin**.",
                "operationId": "post_invoices",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Tagihan dibuat",
                                    "data": {
                                        "id": 5386,
                                        "title": "Denda buku perpustakaan",
                                        "fee_type": {
                                            "id": 25,
                                            "name": "Uang Kegiatan",
                                            "frequency": "sekali"
                                        },
                                        "academic_year_id": 12,
                                        "period": null,
                                        "amount": 25000,
                                        "discount": 0,
                                        "total": 25000,
                                        "paid_amount": 0,
                                        "remaining": 25000,
                                        "status": "belum",
                                        "status_label": "Belum bayar",
                                        "due_date": "2026-12-31",
                                        "is_overdue": false,
                                        "note": null,
                                        "cancel_reason": null,
                                        "created_at": "2026-11-13T06:21:08+07:00",
                                        "student": {
                                            "id": 380,
                                            "nis": "S700101",
                                            "name": "Dewi Lestari",
                                            "class": "X-1"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "student_id": {
                                        "type": "integer",
                                        "description": "ID siswa"
                                    },
                                    "fee_type_id": {
                                        "type": "integer",
                                        "description": "ID jenis biaya"
                                    },
                                    "title": {
                                        "type": "string",
                                        "description": "Judul"
                                    },
                                    "amount": {
                                        "type": "integer",
                                        "description": "Nominal"
                                    },
                                    "discount": {
                                        "type": "integer",
                                        "description": "Potongan"
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Jatuh tempo"
                                    },
                                    "note": {
                                        "type": "string",
                                        "description": "Catatan"
                                    }
                                },
                                "required": [
                                    "student_id",
                                    "fee_type_id",
                                    "amount"
                                ]
                            },
                            "example": {
                                "student_id": 1,
                                "fee_type_id": 2,
                                "title": "Denda keterlambatan buku",
                                "amount": 25000,
                                "discount": 0,
                                "due_date": "2026-12-31"
                            }
                        }
                    }
                }
            }
        },
        "/invoices/generate": {
            "post": {
                "tags": [
                    "Tagihan"
                ],
                "summary": "Generate tagihan massal",
                "description": "Membuat tagihan untuk semua siswa aktif (atau kelas/siswa tertentu). Untuk biaya bulanan dibuat satu tagihan per bulan dalam `periods` (bawaan: semua bulan tahun ajaran).\n\nMemerlukan token **admin**.",
                "operationId": "post_invoices_generate",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "372 tagihan dibuat, 0 dilewati (sudah ada), 0 diperbarui",
                                    "data": {
                                        "created": 372,
                                        "skipped": 0,
                                        "updated": 0,
                                        "students": 31,
                                        "total_amount": 73200000,
                                        "classes_without_rate": []
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "fee_type_id": {
                                        "type": "integer",
                                        "description": "ID jenis biaya"
                                    },
                                    "academic_year_id": {
                                        "type": "integer",
                                        "description": "ID tahun ajaran"
                                    },
                                    "class_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        },
                                        "description": "ID kelas (kosong = semua)"
                                    },
                                    "student_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        },
                                        "description": "ID siswa tertentu"
                                    },
                                    "periods": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        },
                                        "description": "Bulan YYYY-MM (khusus bulanan)"
                                    },
                                    "due_day": {
                                        "type": "integer",
                                        "description": "Tgl jatuh tempo bulanan (1-28, bawaan 10)"
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Jatuh tempo biaya sekali bayar"
                                    },
                                    "update_unpaid": {
                                        "type": "boolean",
                                        "description": "Perbarui nominal tagihan yang belum dibayar sama sekali"
                                    }
                                },
                                "required": [
                                    "fee_type_id",
                                    "academic_year_id"
                                ]
                            },
                            "example": {
                                "fee_type_id": 1,
                                "academic_year_id": 1,
                                "class_ids": [
                                    1,
                                    2
                                ],
                                "periods": [
                                    "2026-07",
                                    "2026-08"
                                ],
                                "due_day": 10,
                                "due_date": "2027-05-31",
                                "update_unpaid": false
                            }
                        }
                    }
                }
            }
        },
        "/invoices/{id}": {
            "get": {
                "tags": [
                    "Tagihan"
                ],
                "summary": "Detail tagihan + pembayarannya",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_invoices_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID tagihan",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 4983,
                                        "title": "SPP Juli 2026",
                                        "fee_type": {
                                            "id": 24,
                                            "name": "SPP",
                                            "frequency": "bulanan"
                                        },
                                        "academic_year_id": 12,
                                        "period": "2026-07",
                                        "amount": 200000,
                                        "discount": 100000,
                                        "total": 100000,
                                        "paid_amount": 0,
                                        "remaining": 100000,
                                        "status": "belum",
                                        "status_label": "Belum bayar",
                                        "due_date": "2026-07-10",
                                        "is_overdue": true,
                                        "note": "Beasiswa prestasi",
                                        "cancel_reason": null,
                                        "created_at": "2026-11-13T06:21:08+07:00",
                                        "student": {
                                            "id": 380,
                                            "nis": "S700101",
                                            "name": "Dewi Lestari",
                                            "class": "X-1"
                                        },
                                        "payments": []
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/invoices/{id}/cancel": {
            "post": {
                "tags": [
                    "Tagihan"
                ],
                "summary": "Batalkan tagihan",
                "description": "Hanya untuk tagihan yang belum ada pembayaran.\n\nMemerlukan token **admin**.",
                "operationId": "post_invoices_id_cancel",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID tagihan",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Tagihan dibatalkan",
                                    "data": {
                                        "id": 5386,
                                        "title": "Denda buku perpustakaan",
                                        "fee_type": {
                                            "id": 25,
                                            "name": "Uang Kegiatan",
                                            "frequency": "sekali"
                                        },
                                        "academic_year_id": 12,
                                        "period": null,
                                        "amount": 25000,
                                        "discount": 0,
                                        "total": 25000,
                                        "paid_amount": 0,
                                        "remaining": 0,
                                        "status": "batal",
                                        "status_label": "Dibatalkan",
                                        "due_date": "2026-12-31",
                                        "is_overdue": false,
                                        "note": null,
                                        "cancel_reason": "Buku sudah dikembalikan",
                                        "created_at": "2026-11-13T06:21:08+07:00",
                                        "student": {
                                            "id": 380,
                                            "nis": "S700101",
                                            "name": "Dewi Lestari",
                                            "class": "X-1"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "description": "Alasan (min 3)"
                                    }
                                },
                                "required": [
                                    "reason"
                                ]
                            },
                            "example": {
                                "reason": "Siswa mendapat pembebasan"
                            }
                        }
                    }
                }
            }
        },
        "/payments": {
            "get": {
                "tags": [
                    "Pembayaran & Kuitansi"
                ],
                "summary": "Riwayat pembayaran",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_payments",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "No kuitansi / nama / NIS",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "description": "Dari tanggal",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "description": "Sampai tanggal",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "method",
                        "in": "query",
                        "required": false,
                        "description": "tunai / transfer",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "sah / batal",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "student_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter siswa",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 1222,
                                            "receipt_no": "API-2026-00002",
                                            "paid_at": "2026-11-13T06:21:09+07:00",
                                            "method": "transfer",
                                            "amount": 160000,
                                            "reference": "BRI 12/11",
                                            "payer_name": null,
                                            "note": null,
                                            "received_by": "Admin API",
                                            "status": "sah",
                                            "cancelled_at": null,
                                            "cancel_reason": null,
                                            "student": {
                                                "id": 380,
                                                "nis": "S700101",
                                                "name": "Dewi Lestari",
                                                "class": "X-1"
                                            },
                                            "items": [
                                                {
                                                    "invoice_id": 4984,
                                                    "title": "SPP Agustus 2026",
                                                    "amount": 60000
                                                },
                                                {
                                                    "invoice_id": 4985,
                                                    "title": "SPP September 2026",
                                                    "amount": 100000
                                                }
                                            ]
                                        },
                                        {
                                            "id": 1221,
                                            "receipt_no": "API-2026-00001",
                                            "paid_at": "2026-11-13T06:21:09+07:00",
                                            "method": "tunai",
                                            "amount": 140000,
                                            "reference": null,
                                            "payer_name": "Ibu Lestari",
                                            "note": null,
                                            "received_by": "Admin API",
                                            "status": "sah",
                                            "cancelled_at": null,
                                            "cancel_reason": null,
                                            "student": {
                                                "id": 380,
                                                "nis": "S700101",
                                                "name": "Dewi Lestari",
                                                "class": "X-1"
                                            },
                                            "items": [
                                                {
                                                    "invoice_id": 4983,
                                                    "title": "SPP Juli 2026",
                                                    "amount": 100000
                                                },
                                                {
                                                    "invoice_id": 4984,
                                                    "title": "SPP Agustus 2026",
                                                    "amount": 40000
                                                }
                                            ]
                                        }
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 20,
                                        "total": 2,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 2,
                                        "sum_amount": 300000
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Pembayaran & Kuitansi"
                ],
                "summary": "Terima pembayaran",
                "description": "Kosongkan `amount` pada item untuk melunasi sisa tagihan. Error 422 jika nominal melebihi sisa atau tagihan bukan milik siswa.\n\nMemerlukan token **admin**.",
                "operationId": "post_payments",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Pembayaran disimpan. No. kuitansi API-2026-00001",
                                    "data": {
                                        "id": 1221,
                                        "receipt_no": "API-2026-00001",
                                        "paid_at": "2026-11-13T06:21:09+07:00",
                                        "method": "tunai",
                                        "amount": 140000,
                                        "reference": null,
                                        "payer_name": "Ibu Lestari",
                                        "note": null,
                                        "received_by": "Admin API",
                                        "status": "sah",
                                        "cancelled_at": null,
                                        "cancel_reason": null,
                                        "student": {
                                            "id": 380,
                                            "nis": "S700101",
                                            "name": "Dewi Lestari",
                                            "class": "X-1"
                                        },
                                        "items": [
                                            {
                                                "invoice_id": 4983,
                                                "title": "SPP Juli 2026",
                                                "amount": 100000
                                            },
                                            {
                                                "invoice_id": 4984,
                                                "title": "SPP Agustus 2026",
                                                "amount": 40000
                                            }
                                        ],
                                        "amount_in_words": "seratus empat puluh ribu rupiah",
                                        "receipt_html_url": "https://belajar-api.unama.ac.id/api/spp/payments/1221/receipt"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "student_id": {
                                        "type": "integer",
                                        "description": "ID siswa"
                                    },
                                    "method": {
                                        "type": "string",
                                        "description": "tunai / transfer"
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        },
                                        "description": "Tagihan yang dibayar [{invoice_id, amount?}]"
                                    },
                                    "paid_at": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Tanggal bayar (bawaan sekarang)"
                                    },
                                    "reference": {
                                        "type": "string",
                                        "description": "No ref transfer"
                                    },
                                    "payer_name": {
                                        "type": "string",
                                        "description": "Nama penyetor"
                                    },
                                    "note": {
                                        "type": "string",
                                        "description": "Catatan"
                                    }
                                },
                                "required": [
                                    "student_id",
                                    "method",
                                    "items"
                                ]
                            },
                            "example": {
                                "student_id": 1,
                                "method": "tunai",
                                "items": [
                                    {
                                        "invoice_id": 1
                                    },
                                    {
                                        "invoice_id": 2,
                                        "amount": 50000
                                    }
                                ],
                                "payer_name": "Bapak Budi"
                            }
                        }
                    }
                }
            }
        },
        "/payments/{id}": {
            "get": {
                "tags": [
                    "Pembayaran & Kuitansi"
                ],
                "summary": "Detail pembayaran",
                "description": "Termasuk `amount_in_words` (terbilang).\n\nMemerlukan token **admin**.",
                "operationId": "get_payments_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID pembayaran",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 1221,
                                        "receipt_no": "API-2026-00001",
                                        "paid_at": "2026-11-13T06:21:09+07:00",
                                        "method": "tunai",
                                        "amount": 140000,
                                        "reference": null,
                                        "payer_name": "Ibu Lestari",
                                        "note": null,
                                        "received_by": "Admin API",
                                        "status": "sah",
                                        "cancelled_at": null,
                                        "cancel_reason": null,
                                        "student": {
                                            "id": 380,
                                            "nis": "S700101",
                                            "name": "Dewi Lestari",
                                            "class": "X-1"
                                        },
                                        "items": [
                                            {
                                                "invoice_id": 4983,
                                                "title": "SPP Juli 2026",
                                                "amount": 100000
                                            },
                                            {
                                                "invoice_id": 4984,
                                                "title": "SPP Agustus 2026",
                                                "amount": 40000
                                            }
                                        ],
                                        "amount_in_words": "seratus empat puluh ribu rupiah",
                                        "receipt_html_url": "https://belajar-api.unama.ac.id/api/spp/payments/1221/receipt"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/payments/{id}/receipt": {
            "get": {
                "tags": [
                    "Pembayaran & Kuitansi"
                ],
                "summary": "Kuitansi HTML siap cetak",
                "description": "Mengembalikan halaman HTML (bukan JSON) yang bisa langsung dicetak / dijadikan PDF.\n\nMemerlukan token **admin**.",
                "operationId": "get_payments_id_receipt",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID pembayaran",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "required": false,
                        "description": "a5 (bawaan) / thermal",
                        "schema": {
                            "type": "string"
                        },
                        "example": "a5"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "*/*": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/payments/{id}/cancel": {
            "post": {
                "tags": [
                    "Pembayaran & Kuitansi"
                ],
                "summary": "Batalkan pembayaran",
                "description": "Tagihan terkait dikembalikan (paid_amount dikurangi). Tercatat di log aktivitas.\n\nMemerlukan token **admin**.",
                "operationId": "post_payments_id_cancel",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID pembayaran",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Pembayaran dibatalkan, tagihan terkait dikembalikan",
                                    "data": {
                                        "id": 1222,
                                        "receipt_no": "API-2026-00002",
                                        "paid_at": "2026-11-13T06:21:09+07:00",
                                        "method": "transfer",
                                        "amount": 160000,
                                        "reference": "BRI 12/11",
                                        "payer_name": null,
                                        "note": null,
                                        "received_by": "Admin API",
                                        "status": "batal",
                                        "cancelled_at": "2026-11-13T06:21:09+07:00",
                                        "cancel_reason": "Salah input metode",
                                        "student": {
                                            "id": 380,
                                            "nis": "S700101",
                                            "name": "Dewi Lestari",
                                            "class": "X-1"
                                        },
                                        "items": [
                                            {
                                                "invoice_id": 4984,
                                                "title": "SPP Agustus 2026",
                                                "amount": 60000
                                            },
                                            {
                                                "invoice_id": 4985,
                                                "title": "SPP September 2026",
                                                "amount": 100000
                                            }
                                        ],
                                        "amount_in_words": "seratus enam puluh ribu rupiah",
                                        "receipt_html_url": "https://belajar-api.unama.ac.id/api/spp/payments/1222/receipt"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "description": "Alasan (min 3)"
                                    }
                                },
                                "required": [
                                    "reason"
                                ]
                            },
                            "example": {
                                "reason": "Salah input nominal"
                            }
                        }
                    }
                }
            }
        },
        "/reports/dashboard": {
            "get": {
                "tags": [
                    "Laporan"
                ],
                "summary": "Ringkasan dasbor",
                "description": "Penerimaan hari ini/bulan ini/TA, total tunggakan, grafik 12 bulan, % lunas per kelas, 8 pembayaran terakhir.\n\nMemerlukan token **admin**.",
                "operationId": "get_reports_dashboard",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "today_income": 140000,
                                        "today_count": 1,
                                        "month_income": 140000,
                                        "year_income": 140000,
                                        "outstanding_total": 82360000,
                                        "outstanding_invoices": 402,
                                        "overdue_total": 30360000,
                                        "overdue_students": 31,
                                        "active_students": 31,
                                        "academic_year": "2026/2027",
                                        "monthly": [
                                            {
                                                "period": "2025-12",
                                                "label": "Desember 2025",
                                                "amount": 0
                                            },
                                            {
                                                "period": "2026-01",
                                                "label": "Januari 2026",
                                                "amount": 0
                                            },
                                            "…"
                                        ],
                                        "class_progress": [
                                            {
                                                "class_id": 51,
                                                "class": "VII A",
                                                "total": 10000000,
                                                "paid": 0,
                                                "outstanding": 10000000,
                                                "invoices": 50,
                                                "paid_invoices": 0,
                                                "percent": 0
                                            },
                                            {
                                                "class_id": 49,
                                                "class": "VII B",
                                                "total": 9000000,
                                                "paid": 0,
                                                "outstanding": 9000000,
                                                "invoices": 45,
                                                "paid_invoices": 0,
                                                "percent": 0
                                            },
                                            "…"
                                        ],
                                        "recent_payments": [
                                            {
                                                "id": 1222,
                                                "receipt_no": "API-2026-00002",
                                                "paid_at": "2026-11-13T06:21:09+07:00",
                                                "method": "transfer",
                                                "amount": 160000,
                                                "reference": "BRI 12/11",
                                                "payer_name": null,
                                                "note": null,
                                                "received_by": "Admin API",
                                                "status": "batal",
                                                "cancelled_at": "2026-11-13T06:21:09+07:00",
                                                "cancel_reason": "Salah input metode",
                                                "student": {
                                                    "id": 380,
                                                    "nis": "S700101",
                                                    "name": "Dewi Lestari",
                                                    "class": "X-1"
                                                }
                                            },
                                            {
                                                "id": 1221,
                                                "receipt_no": "API-2026-00001",
                                                "paid_at": "2026-11-13T06:21:09+07:00",
                                                "method": "tunai",
                                                "amount": 140000,
                                                "reference": null,
                                                "payer_name": "Ibu Lestari",
                                                "note": null,
                                                "received_by": "Admin API",
                                                "status": "sah",
                                                "cancelled_at": null,
                                                "cancel_reason": null,
                                                "student": {
                                                    "id": 380,
                                                    "nis": "S700101",
                                                    "name": "Dewi Lestari",
                                                    "class": "X-1"
                                                }
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/reports/income": {
            "get": {
                "tags": [
                    "Laporan"
                ],
                "summary": "Laporan penerimaan",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_reports_income",
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "description": "Bawaan awal bulan",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "description": "Bawaan hari ini",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "fee_type_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter biaya",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter kelas",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "method",
                        "in": "query",
                        "required": false,
                        "description": "tunai / transfer",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "required": false,
                        "description": "json / xlsx",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "from": "2026-11-01",
                                        "to": "2026-11-13",
                                        "total": 140000,
                                        "transactions": 1,
                                        "by_fee_type": [
                                            {
                                                "label": "SPP",
                                                "count": 2,
                                                "amount": 140000
                                            }
                                        ],
                                        "by_method": [
                                            {
                                                "label": "tunai",
                                                "count": 2,
                                                "amount": 140000
                                            }
                                        ],
                                        "by_class": [
                                            {
                                                "label": "X-1",
                                                "count": 2,
                                                "amount": 140000
                                            }
                                        ],
                                        "by_day": [
                                            {
                                                "label": "2026-11-13",
                                                "count": 2,
                                                "amount": 140000
                                            }
                                        ],
                                        "rows": [
                                            {
                                                "paid_at": "2026-11-13 06:21",
                                                "receipt_no": "API-2026-00001",
                                                "payment_id": 1221,
                                                "nis": "S700101",
                                                "student": "Dewi Lestari",
                                                "class": "X-1",
                                                "fee_type": "SPP",
                                                "title": "SPP Juli 2026",
                                                "method": "tunai",
                                                "received_by": "Admin API",
                                                "amount": 100000
                                            },
                                            {
                                                "paid_at": "2026-11-13 06:21",
                                                "receipt_no": "API-2026-00001",
                                                "payment_id": 1221,
                                                "nis": "S700101",
                                                "student": "Dewi Lestari",
                                                "class": "X-1",
                                                "fee_type": "SPP",
                                                "title": "SPP Agustus 2026",
                                                "method": "tunai",
                                                "received_by": "Admin API",
                                                "amount": 40000
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/reports/arrears": {
            "get": {
                "tags": [
                    "Laporan"
                ],
                "summary": "Rekap tunggakan per siswa & kelas",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_reports_arrears",
                "parameters": [
                    {
                        "name": "until",
                        "in": "query",
                        "required": false,
                        "description": "Jatuh tempo s.d. (bawaan hari ini)",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter kelas",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "fee_type_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter biaya",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter TA",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "required": false,
                        "description": "json / xlsx",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "until": "2027-06-30",
                                        "total": 82360000,
                                        "students_count": 31,
                                        "by_class": [
                                            {
                                                "class": "VII A",
                                                "students": 10,
                                                "invoices": 130,
                                                "amount": 27000000
                                            },
                                            {
                                                "class": "VII B",
                                                "students": 9,
                                                "invoices": 117,
                                                "amount": 24300000
                                            },
                                            "…"
                                        ],
                                        "students": [
                                            {
                                                "student_id": 392,
                                                "nis": "2026112",
                                                "name": "Aisyah Ramadhan",
                                                "class": "VII A",
                                                "guardian_name": "Ibu Mariani Ramadhan",
                                                "guardian_phone": "081255501356",
                                                "invoices": 13,
                                                "items": [
                                                    "SPP Juli 2026",
                                                    "SPP Agustus 2026",
                                                    "…"
                                                ],
                                                "amount": 2700000,
                                                "oldest_due": "2026-07-10"
                                            },
                                            {
                                                "student_id": 410,
                                                "nis": "2026130",
                                                "name": "Anisa Maharani",
                                                "class": "VII A",
                                                "guardian_name": "Bapak Darmawan Maharani",
                                                "guardian_phone": "081255503390",
                                                "invoices": 13,
                                                "items": [
                                                    "SPP Juli 2026",
                                                    "SPP Agustus 2026",
                                                    "…"
                                                ],
                                                "amount": 2700000,
                                                "oldest_due": "2026-07-10"
                                            },
                                            "…"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/reports/class-progress": {
            "get": {
                "tags": [
                    "Laporan"
                ],
                "summary": "% lunas per kelas",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_reports_class_progress",
                "parameters": [
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "description": "Bawaan aktif",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "all",
                        "in": "query",
                        "required": false,
                        "description": "1 = termasuk yang belum jatuh tempo",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "class_id": 51,
                                            "class": "VII A",
                                            "total": 27000000,
                                            "paid": 0,
                                            "outstanding": 27000000,
                                            "invoices": 130,
                                            "paid_invoices": 0,
                                            "percent": 0
                                        },
                                        {
                                            "class_id": 49,
                                            "class": "VII B",
                                            "total": 24300000,
                                            "paid": 0,
                                            "outstanding": 24300000,
                                            "invoices": 117,
                                            "paid_invoices": 0,
                                            "percent": 0
                                        },
                                        "…"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/activity-logs": {
            "get": {
                "tags": [
                    "Laporan"
                ],
                "summary": "Log aktivitas",
                "description": "Memerlukan token **admin**.",
                "operationId": "get_activity_logs",
                "parameters": [
                    {
                        "name": "action",
                        "in": "query",
                        "required": false,
                        "description": "Awalan aksi, mis. pembayaran",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Cari keterangan",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 1303,
                                            "action": "pembayaran.batal",
                                            "description": "Batalkan pembayaran API-2026-00002 Rp 160.000. Alasan: Salah input metode",
                                            "actor": "Admin API",
                                            "actor_type": "admin",
                                            "subject_type": "Payment",
                                            "subject_id": 1222,
                                            "properties": {
                                                "reason": "Salah input metode"
                                            },
                                            "channel": "api",
                                            "ip": "192.168.36.201",
                                            "created_at": "2026-11-13T06:21:09+07:00"
                                        },
                                        {
                                            "id": 1302,
                                            "action": "pembayaran.terima",
                                            "description": "Terima pembayaran API-2026-00002 Rp 160.000 dari Dewi Lestari (S700101)",
                                            "actor": "Admin API",
                                            "actor_type": "admin",
                                            "subject_type": "Payment",
                                            "subject_id": 1222,
                                            "properties": {
                                                "amount": 160000,
                                                "method": "transfer",
                                                "invoices": [
                                                    4984,
                                                    4985
                                                ]
                                            },
                                            "channel": "api",
                                            "ip": "192.168.36.201",
                                            "created_at": "2026-11-13T06:21:09+07:00"
                                        },
                                        "…"
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 3,
                                        "total": 26,
                                        "last_page": 9,
                                        "from": 1,
                                        "to": 3
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/wali/login": {
            "post": {
                "tags": [
                    "Portal Wali Murid"
                ],
                "summary": "Login wali",
                "description": "",
                "operationId": "post_wali_login",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Login wali berhasil",
                                    "data": {
                                        "student": {
                                            "id": 181,
                                            "nis": "2024001",
                                            "nisn": "0064058227",
                                            "name": "Ahmad Fauzi",
                                            "gender": "L",
                                            "class": {
                                                "id": 19,
                                                "name": "VII A",
                                                "grade": 7
                                            },
                                            "entry_year": 2026,
                                            "guardian_name": "Bapak Budi Santoso",
                                            "guardian_phone": "081234567890",
                                            "email": null,
                                            "address": "Jl. Kenali Asam No. 111, Jambi",
                                            "status": "aktif",
                                            "has_portal_access": true,
                                            "pin_changed_by_guardian": false,
                                            "created_at": "2026-11-13T06:16:37+07:00"
                                        },
                                        "school": {
                                            "id": 4,
                                            "name": "SMP Negeri 1 (Demo)",
                                            "slug": "smp-negeri-1-demo",
                                            "npsn": "10500001",
                                            "level": "SMP",
                                            "address": "Jl. Kapten Pattimura No. 1, Kenali Besar",
                                            "city": "Jambi",
                                            "phone": "0741-123456",
                                            "email": "tu@smpn1.demo",
                                            "logo_url": "https://belajar-api.unama.ac.id/spp/logo/smp-negeri-1-demo?v=1794529086",
                                            "payment_instructions": "1. Tunai di ruang Tata Usaha, Senin–Jumat pukul 07.30–14.00.\n2. Transfer ke salah satu rekening sekolah, lalu kirim foto bukti transfer ke WA bendahara 0812-3456-7890 dengan format: NAMA – KELAS – BULAN.\n3. SPP dibayar paling lambat tanggal 10 setiap bulan.",
                                            "bank_accounts": "Bank Jambi 1234567890 a.n. SMP Negeri 1 Demo\nBRI 0021-01-000123-30-5 a.n. SMP Negeri 1 Demo"
                                        },
                                        "must_change_password": true,
                                        "token": {
                                            "access_token": "14|Xk3vN0pQ...contoh-token...9aZ",
                                            "token_type": "Bearer",
                                            "expires_at": "2026-12-13T06:21:11+07:00"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "school_slug": {
                                        "type": "string",
                                        "description": "Kode sekolah"
                                    },
                                    "nis": {
                                        "type": "string",
                                        "description": "NIS"
                                    },
                                    "password": {
                                        "type": "string",
                                        "description": "PIN / kata sandi"
                                    }
                                },
                                "required": [
                                    "school_slug",
                                    "nis",
                                    "password"
                                ]
                            },
                            "example": {
                                "school_slug": "smp-negeri-1-demo",
                                "nis": "2024001",
                                "password": "123456"
                            }
                        }
                    }
                }
            }
        },
        "/wali/me": {
            "get": {
                "tags": [
                    "Portal Wali Murid"
                ],
                "summary": "Data siswa & total tagihan",
                "description": "Memerlukan token **wali**.",
                "operationId": "get_wali_me",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "student": {
                                            "id": 181,
                                            "nis": "2024001",
                                            "nisn": "0064058227",
                                            "name": "Ahmad Fauzi",
                                            "gender": "L",
                                            "class": {
                                                "id": 19,
                                                "name": "VII A",
                                                "grade": 7
                                            },
                                            "entry_year": 2026,
                                            "guardian_name": "Bapak Budi Santoso",
                                            "guardian_phone": "081234567890",
                                            "email": null,
                                            "address": "Jl. Kenali Asam No. 111, Jambi",
                                            "status": "aktif",
                                            "has_portal_access": true,
                                            "pin_changed_by_guardian": false,
                                            "created_at": "2026-11-13T06:16:37+07:00"
                                        },
                                        "school": {
                                            "id": 4,
                                            "name": "SMP Negeri 1 (Demo)",
                                            "slug": "smp-negeri-1-demo",
                                            "npsn": "10500001",
                                            "level": "SMP",
                                            "address": "Jl. Kapten Pattimura No. 1, Kenali Besar",
                                            "city": "Jambi",
                                            "phone": "0741-123456",
                                            "email": "tu@smpn1.demo",
                                            "logo_url": "https://belajar-api.unama.ac.id/spp/logo/smp-negeri-1-demo?v=1794529086",
                                            "payment_instructions": "1. Tunai di ruang Tata Usaha, Senin–Jumat pukul 07.30–14.00.\n2. Transfer ke salah satu rekening sekolah, lalu kirim foto bukti transfer ke WA bendahara 0812-3456-7890 dengan format: NAMA – KELAS – BULAN.\n3. SPP dibayar paling lambat tanggal 10 setiap bulan.",
                                            "bank_accounts": "Bank Jambi 1234567890 a.n. SMP Negeri 1 Demo\nBRI 0021-01-000123-30-5 a.n. SMP Negeri 1 Demo"
                                        },
                                        "outstanding": 1050000
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/wali/invoices": {
            "get": {
                "tags": [
                    "Portal Wali Murid"
                ],
                "summary": "Tagihan siswa",
                "description": "Memerlukan token **wali**.",
                "operationId": "get_wali_invoices",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "terbuka / lunas",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 2580,
                                            "title": "SPP Desember 2026",
                                            "fee_type": {
                                                "id": 12,
                                                "name": "SPP",
                                                "frequency": "bulanan"
                                            },
                                            "academic_year_id": 7,
                                            "period": "2026-12",
                                            "amount": 150000,
                                            "discount": 0,
                                            "total": 150000,
                                            "paid_amount": 0,
                                            "remaining": 150000,
                                            "status": "belum",
                                            "status_label": "Belum bayar",
                                            "due_date": "2026-12-10",
                                            "is_overdue": false,
                                            "note": null,
                                            "cancel_reason": null,
                                            "created_at": "2026-11-13T06:16:37+07:00"
                                        },
                                        {
                                            "id": 2581,
                                            "title": "SPP Januari 2027",
                                            "fee_type": {
                                                "id": 12,
                                                "name": "SPP",
                                                "frequency": "bulanan"
                                            },
                                            "academic_year_id": 7,
                                            "period": "2027-01",
                                            "amount": 150000,
                                            "discount": 0,
                                            "total": 150000,
                                            "paid_amount": 0,
                                            "remaining": 150000,
                                            "status": "belum",
                                            "status_label": "Belum bayar",
                                            "due_date": "2027-01-10",
                                            "is_overdue": false,
                                            "note": null,
                                            "cancel_reason": null,
                                            "created_at": "2026-11-13T06:16:37+07:00"
                                        },
                                        "…"
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 3,
                                        "total": 7,
                                        "last_page": 3,
                                        "from": 1,
                                        "to": 3,
                                        "outstanding": 1050000
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/wali/payments": {
            "get": {
                "tags": [
                    "Portal Wali Murid"
                ],
                "summary": "Riwayat pembayaran",
                "description": "Memerlukan token **wali**.",
                "operationId": "get_wali_payments",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 635,
                                            "receipt_no": "KW-2026-00003",
                                            "paid_at": "2026-11-13T03:02:39+07:00",
                                            "method": "tunai",
                                            "amount": 150000,
                                            "reference": null,
                                            "payer_name": "Ibu Mariani Syahputra",
                                            "note": null,
                                            "received_by": "Joko Operator",
                                            "status": "sah",
                                            "cancelled_at": null,
                                            "cancel_reason": null,
                                            "student": {
                                                "id": 181,
                                                "nis": "2024001",
                                                "name": "Ahmad Fauzi",
                                                "class": "VII A"
                                            },
                                            "items": [
                                                {
                                                    "invoice_id": 2579,
                                                    "title": "SPP November 2026",
                                                    "amount": 150000
                                                }
                                            ]
                                        },
                                        {
                                            "id": 636,
                                            "receipt_no": "KW-2026-00004",
                                            "paid_at": "2026-09-29T09:33:00+07:00",
                                            "method": "transfer",
                                            "amount": 450000,
                                            "reference": "TRF-921165",
                                            "payer_name": "Ibu Mariani Syahputra",
                                            "note": null,
                                            "received_by": "Joko Operator",
                                            "status": "sah",
                                            "cancelled_at": null,
                                            "cancel_reason": null,
                                            "student": {
                                                "id": 181,
                                                "nis": "2024001",
                                                "name": "Ahmad Fauzi",
                                                "class": "VII A"
                                            },
                                            "items": [
                                                {
                                                    "invoice_id": 3511,
                                                    "title": "Seragam 2026/2027",
                                                    "amount": 450000
                                                }
                                            ]
                                        }
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 2,
                                        "total": 5,
                                        "last_page": 3,
                                        "from": 1,
                                        "to": 2
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/wali/payments/{id}": {
            "get": {
                "tags": [
                    "Portal Wali Murid"
                ],
                "summary": "Detail kuitansi",
                "description": "Memerlukan token **wali**.",
                "operationId": "get_wali_payments_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID pembayaran",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 635,
                                        "receipt_no": "KW-2026-00003",
                                        "paid_at": "2026-11-13T03:02:39+07:00",
                                        "method": "tunai",
                                        "amount": 150000,
                                        "reference": null,
                                        "payer_name": "Ibu Mariani Syahputra",
                                        "note": null,
                                        "received_by": "Joko Operator",
                                        "status": "sah",
                                        "cancelled_at": null,
                                        "cancel_reason": null,
                                        "student": {
                                            "id": 181,
                                            "nis": "2024001",
                                            "name": "Ahmad Fauzi",
                                            "class": "VII A"
                                        },
                                        "items": [
                                            {
                                                "invoice_id": 2579,
                                                "title": "SPP November 2026",
                                                "amount": 150000
                                            }
                                        ],
                                        "amount_in_words": "seratus lima puluh ribu rupiah",
                                        "receipt_html_url": "https://belajar-api.unama.ac.id/api/spp/wali/payments/635/receipt"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/wali/payments/{id}/receipt": {
            "get": {
                "tags": [
                    "Portal Wali Murid"
                ],
                "summary": "Kuitansi HTML",
                "description": "Memerlukan token **wali**.",
                "operationId": "get_wali_payments_id_receipt",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID pembayaran",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "*/*": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/wali/payment-info": {
            "get": {
                "tags": [
                    "Portal Wali Murid"
                ],
                "summary": "Cara bayar sekolah",
                "description": "Memerlukan token **wali**.",
                "operationId": "get_wali_payment_info",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "school": "SMP Negeri 1 (Demo)",
                                        "bank_accounts": "Bank Jambi 1234567890 a.n. SMP Negeri 1 Demo\nBRI 0021-01-000123-30-5 a.n. SMP Negeri 1 Demo",
                                        "payment_instructions": "1. Tunai di ruang Tata Usaha, Senin–Jumat pukul 07.30–14.00.\n2. Transfer ke salah satu rekening sekolah, lalu kirim foto bukti transfer ke WA bendahara 0812-3456-7890 dengan format: NAMA – KELAS – BULAN.\n3. SPP dibayar paling lambat tanggal 10 setiap bulan.",
                                        "phone": "0741-123456",
                                        "email": "tu@smpn1.demo",
                                        "treasurer_name": "Rina Marlina, S.E."
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/wali/password": {
            "put": {
                "tags": [
                    "Portal Wali Murid"
                ],
                "summary": "Ganti PIN/kata sandi",
                "description": "Memerlukan token **wali**.",
                "operationId": "put_wali_password",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Kata sandi diganti",
                                    "data": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "current_password": {
                                        "type": "string",
                                        "description": "PIN saat ini"
                                    },
                                    "password": {
                                        "type": "string",
                                        "description": "Baru (min 6)"
                                    },
                                    "password_confirmation": {
                                        "type": "string",
                                        "description": "Ulangi"
                                    }
                                },
                                "required": [
                                    "current_password",
                                    "password",
                                    "password_confirmation"
                                ]
                            },
                            "example": {
                                "current_password": "123456",
                                "password": "rahasiaku",
                                "password_confirmation": "rahasiaku"
                            }
                        }
                    }
                }
            }
        },
        "/wali/logout": {
            "post": {
                "tags": [
                    "Portal Wali Murid"
                ],
                "summary": "Logout wali",
                "description": "Memerlukan token **wali**.",
                "operationId": "post_wali_logout",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Logout berhasil",
                                    "data": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/super/summary": {
            "get": {
                "tags": [
                    "Superadmin Platform"
                ],
                "summary": "Ringkasan platform",
                "description": "Memerlukan token **super**.",
                "operationId": "get_super_summary",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "schools": 6,
                                        "active_schools": 6,
                                        "admins": 9,
                                        "students": 230,
                                        "invoices": 2812,
                                        "payments": 586,
                                        "payments_amount": 145248750,
                                        "month_amount": 18155000,
                                        "new_schools_month": 6
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/super/schools": {
            "get": {
                "tags": [
                    "Superadmin Platform"
                ],
                "summary": "Daftar sekolah",
                "description": "Memerlukan token **super**.",
                "operationId": "get_super_schools",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Cari",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "active / inactive",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Nomor halaman",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Jumlah data per halaman (1-100, bawaan 20)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": [
                                        {
                                            "id": 9,
                                            "name": "SMA API Test 7001",
                                            "slug": "sma-api-test-7001",
                                            "npsn": null,
                                            "level": "SMA",
                                            "address": "Jl. Uji API No. 1",
                                            "city": "Jambi",
                                            "phone": null,
                                            "email": "api7001@uji.test",
                                            "logo_url": null,
                                            "payment_instructions": "Pembayaran dapat dilakukan:\n1. Tunai di ruang Tata Usaha (Senin–Jumat, 07.30–14.00).\n2. Transfer ke rekening sekolah, lalu kirim bukti transfer ke bendahara.",
                                            "bank_accounts": "Bank Jambi 999",
                                            "principal_name": "Dr. Kepala",
                                            "principal_nip": null,
                                            "treasurer_name": "Admin API",
                                            "treasurer_nip": null,
                                            "receipt_prefix": "API",
                                            "receipt_footer": null,
                                            "status": "active",
                                            "created_at": "2026-11-13T06:21:02+07:00",
                                            "students_count": 31,
                                            "admins_count": 2,
                                            "payments_amount": 140000
                                        }
                                    ],
                                    "meta": {
                                        "current_page": 1,
                                        "per_page": 20,
                                        "total": 1,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/super/schools/{id}": {
            "get": {
                "tags": [
                    "Superadmin Platform"
                ],
                "summary": "Detail sekolah + statistik",
                "description": "Memerlukan token **super**.",
                "operationId": "get_super_schools_id_",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID sekolah",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "OK",
                                    "data": {
                                        "id": 9,
                                        "name": "SMA API Test 7001",
                                        "slug": "sma-api-test-7001",
                                        "npsn": null,
                                        "level": "SMA",
                                        "address": "Jl. Uji API No. 1",
                                        "city": "Jambi",
                                        "phone": null,
                                        "email": "api7001@uji.test",
                                        "logo_url": null,
                                        "payment_instructions": "Pembayaran dapat dilakukan:\n1. Tunai di ruang Tata Usaha (Senin–Jumat, 07.30–14.00).\n2. Transfer ke rekening sekolah, lalu kirim bukti transfer ke bendahara.",
                                        "bank_accounts": "Bank Jambi 999",
                                        "principal_name": "Dr. Kepala",
                                        "principal_nip": null,
                                        "treasurer_name": "Admin API",
                                        "treasurer_nip": null,
                                        "receipt_prefix": "API",
                                        "receipt_footer": null,
                                        "status": "active",
                                        "created_at": "2026-11-13T06:21:02+07:00",
                                        "stats": {
                                            "students": 31,
                                            "classes": 5,
                                            "invoices": 404,
                                            "outstanding": 82360000,
                                            "payments": 1,
                                            "payments_amount": 140000,
                                            "last_payment": "2026-11-12T23:21:09.000000Z"
                                        },
                                        "admins": [
                                            {
                                                "id": 14,
                                                "name": "Admin API",
                                                "email": "api7001@uji.test",
                                                "phone": "081200000000",
                                                "role": "admin",
                                                "position": "Bendahara",
                                                "is_active": true,
                                                "school_id": 9,
                                                "last_login_at": "2026-11-13T06:21:03+07:00",
                                                "created_at": "2026-11-13T06:21:02+07:00"
                                            },
                                            {
                                                "id": 15,
                                                "name": "Operator Satu",
                                                "email": "op7001@uji.test",
                                                "phone": null,
                                                "role": "admin",
                                                "position": "Operator TU",
                                                "is_active": true,
                                                "school_id": 9,
                                                "last_login_at": null,
                                                "created_at": "2026-11-13T06:21:03+07:00"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/super/schools/{id}/status": {
            "patch": {
                "tags": [
                    "Superadmin Platform"
                ],
                "summary": "Aktif/nonaktifkan sekolah",
                "description": "Memerlukan token **super**.",
                "operationId": "patch_super_schools_id_status",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "ID sekolah",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "success": true,
                                    "message": "Status sekolah diperbarui",
                                    "data": {
                                        "id": 9,
                                        "name": "SMA API Test 7001",
                                        "slug": "sma-api-test-7001",
                                        "npsn": null,
                                        "level": "SMA",
                                        "address": "Jl. Uji API No. 1",
                                        "city": "Jambi",
                                        "phone": null,
                                        "email": "api7001@uji.test",
                                        "logo_url": null,
                                        "payment_instructions": "Pembayaran dapat dilakukan:\n1. Tunai di ruang Tata Usaha (Senin–Jumat, 07.30–14.00).\n2. Transfer ke rekening sekolah, lalu kirim bukti transfer ke bendahara.",
                                        "bank_accounts": "Bank Jambi 999",
                                        "principal_name": "Dr. Kepala",
                                        "principal_nip": null,
                                        "treasurer_name": "Admin API",
                                        "treasurer_nip": null,
                                        "receipt_prefix": "API",
                                        "receipt_footer": null,
                                        "status": "inactive",
                                        "created_at": "2026-11-13T06:21:02+07:00"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "description": "active / inactive"
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            },
                            "example": {
                                "status": "inactive"
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Token dari POST /auth/login (admin) atau POST /wali/login (wali)."
            }
        },
        "schemas": {
            "Envelope": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean"
                    },
                    "message": {
                        "type": "string"
                    },
                    "data": {
                        "nullable": true
                    },
                    "meta": {
                        "type": "object",
                        "properties": {
                            "current_page": {
                                "type": "integer"
                            },
                            "per_page": {
                                "type": "integer"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "last_page": {
                                "type": "integer"
                            }
                        }
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": false
                    },
                    "message": {
                        "type": "string"
                    },
                    "errors": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                }
            }
        },
        "responses": {
            "Error": {
                "description": "Error",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        }
    }
}