Referensi API

Bagian ini isinya hasil generate dari kode karlo_be, bukan tulisan tangan. Bedanya dengan dokumen lain di situs ini: dokumen domain (misalnya Siklus status Order) menjelaskan kenapa dan bagaimana sebuah proses bisnis berjalan, sedangkan halaman di bagian ini cuma menjawab apa yang ada di kode saat ini.

Isi

• Daftar endpoint API: 804 endpoint, path, method, dan siapa yang boleh mengaksesnya.
• openapi.json: dokumen OpenAPI 3.1 dengan isi yang sama, buat diimpor ke Postman atau dipakai codegen client.

Yang sudah ada dan yang belum

	Status
Path & HTTP method	Lengkap, 804 endpoint
Butuh token atau tidak	Lengkap
Pembatasan role & permission modul	Lengkap
Controller & handler penanganan	Lengkap
Request body (field, tipe, wajib/opsional)	Sebagian, 53 dari 434 endpoint yang mengubah data
Response (bentuk & contoh)	Belum ada

Request body diambil dari skema yup di src/controllers/Validator/. Cakupannya tidak penuh karena validasi di karlo_be tidak dipasang sebagai middleware di route, tapi dipanggil di dalam method controller lewat validation.<nama>.validate(req.body), dan sebagian besar method memang tidak memanggilnya. Pemakaian validator juga terpusat di kode lama: controller yang lebih baru seperti SpotOrderController, InvoiceController, dan PaymentController belum memakainya sama sekali.

Karena itu kolom Request body yang kosong bukan berarti endpoint-nya tidak menerima body, melainkan tidak ada skema yang bisa dibaca untuk endpoint itu.

Response belum ada sumber statisnya sama sekali karena dirakit langsung di dalam controller. Satu-satunya cara realistis adalah merekam response asli saat server dijalankan.

Cara auth dibaca

Token tidak dipasang per endpoint. Di src/routes/index.js ada satu baris router.use(ensureToken), dan semua route yang didaftarkan setelah baris itu butuh token, yang sebelumnya tidak. Jadi status auth di daftar endpoint dihitung dari posisi pendaftaran route, bukan dari middleware yang menempel di route itu sendiri.

Route di src/routes/public.js didaftarkan langsung ke app di luar router ber-prefix /api, jadi tidak kena ensureToken sama sekali.

Pembatasan role di kode ditulis sebagai singkatan gabungan (ATM, ASTWWP, dan seterusnya). Di daftar endpoint singkatan itu sudah dibuka jadi nama peran biasa.

Cara generate ulang

pnpm run api:generate
pnpm run api:generate -- --be /path/ke/karlo_be
KARLO_BE_DIR=/path/ke/karlo_be pnpm run api:generate

Generator membaca karlo_be sebagai input lewat AST, tidak menjalankan kodenya dan tidak mengubah apa pun di repo itu.

CI tidak bisa menjalankan generator ini: workflow deploy hanya checkout repo docs, sedangkan karlo_be ada di CodeCommit dan tidak ikut ter-checkout. Karena itu generator dijalankan lokal dan hasilnya di-commit. Efek sampingnya justru berguna, setiap kali di-generate ulang, perubahan endpoint di backend muncul sebagai diff git, dan itu cara paling murah untuk tahu ada endpoint yang berubah, hilang, atau berpindah role.

Jangan edit hasil generate

content/referensi/endpoints.md dan content/public/openapi.json ditimpa tiap kali generator jalan. Kalau ada yang salah di situ, perbaiki generatornya di scripts/openapi/, jangan tambal hasilnya.