Referensi API Endpoint Lengkap

Gambaran Umum

Bagi para pengembang perangkat lunak, integrator sistem, dan insinyur data, Application Programming Interface (API) adalah cetak biru yang menentukan batas kemungkinan sebuah platform. Temuya POS tidak sekadar menyediakan antarmuka pengguna yang indah, tetapi juga mengekspos seluruh urat nadinya melalui serangkaian REST API yang sangat terstruktur, kuat, dan terdokumentasi dengan baik. Referensi API ini adalah kompas Anda untuk menavigasi, berinteraksi, dan mengendalikan hampir setiap aspek dari ekosistem Temuya POS secara terprogram.

Backend Temuya POS dibangun di atas arsitektur serverless yang sangat cepat menggunakan kerangka kerja Hono.js, yang beroperasi pada jaringan edge Cloudflare. Keputusan arsitektural ini memastikan bahwa setiap panggilan API yang Anda lakukan tidak hanya merespons dalam hitungan milidetik dari lokasi terdekat dengan server Anda, tetapi juga mampu menangani lonjakan lalu lintas yang luar biasa besar tanpa membebani satu titik pusat kegagalan. Seluruh komunikasi API dilakukan dengan format pertukaran data JSON standar industri, memberikan kemudahan bagi Anda untuk menggunakan bahasa pemrograman atau perangkat alat apa pun yang Anda sukai.

Setiap endpoint dalam referensi ini dirancang dengan prinsip desain RESTful (Representational State Transfer) yang intuitif. Kami menggunakan kata kerja HTTP standar (GET untuk membaca, POST untuk membuat, PUT/PATCH untuk memperbarui, DELETE untuk menghapus) yang selaras dengan makna operasionalnya. Dokumentasi ini tidak hanya mencantumkan daftar rute, tetapi juga memberikan pemahaman konseptual tentang bagaimana setiap modul saling berinteraksi, memungkinkan Anda untuk membangun ekstensi, otomatisasi, dan integrasi yang kompleks dengan rasa percaya diri yang tinggi.

Skenario Bisnis Nyata

Bayangkan sebuah perusahaan distribusi besar bernama “Nusantara Supply” yang menggunakan Temuya POS di seluruh jaringan toko grosirnya. Kantor pusat Nusantara Supply menggunakan perangkat lunak Enterprise Resource Planning (ERP) raksasa bernama SAP untuk mengelola keuangan, perpajakan, dan rantai pasokan di tingkat korporat. Manajemen pusat menginstruksikan bahwa seluruh data transaksi penjualan harian dari setiap toko harus dimasukkan ke dalam SAP secara otomatis setiap malam pada pukul 23:59.

Alih-alih menyuruh karyawan untuk merekap penjualan dan mengetik ulang data secara manual ke dalam SAP—sebuah proses yang memakan waktu berjam-jam dan sangat rawan kesalahan—tim integrasi Nusantara Supply membangun sebuah skrip otomatisasi. Setiap malam, skrip ini akan bangun dari tidurnya, mengambil Kunci API yang aman, dan mengirimkan permintaan GET ke endpoint /api/transactions milik Temuya POS. Skrip tersebut menambahkan parameter rentang tanggal (filter dari pagi hingga malam hari itu) pada parameter permintaan.

Server Hono Worker Temuya POS segera merespons, memuntahkan ribuan baris data JSON yang bersih dan terstruktur yang berisi setiap detail penjualan, potongan diskon, dan metode pembayaran yang terjadi pada hari itu. Skrip otomatisasi tersebut kemudian dengan gesit memformat ulang data JSON tersebut agar sesuai dengan skema rumit yang diminta oleh SAP, lalu mendorongnya masuk ke dalam sistem ERP korporat. Berkat Referensi API Endpoint Lengkap ini, proses rekonsiliasi keuangan yang dulunya memakan waktu dua hari kerja kini selesai secara magis dalam waktu kurang dari lima menit setiap malam, tanpa campur tangan manusia sedikitpun.

Alur Kerja Arsitektur Routing

Peta arsitektur di bawah ini menggambarkan bagaimana Hono.js menangani perutean (routing) permintaan yang masuk, membaginya ke dalam sub-router fungsional, dan menerapkan lapisan keamanan otorisasi sesuai kebutuhan.

graph LR
    Client((Klien / API Key)) --> Gateway[Hono Edge Router / Worker]
    Gateway --> AuthMiddleware{Auth Middleware}
    
    AuthMiddleware -- "Valid & Punya Izin" --> RouterSplit[Modul Sub-Router]
    AuthMiddleware -- "Invalid / Ditolak" --> Error401[Response 401/403]
    
    RouterSplit --> ModAuth[Modul Autentikasi /api/sessions]
    RouterSplit --> ModTenant[Modul Tenant /api/tenants]
    RouterSplit --> ModProduct[Modul Produk /api/products]
    RouterSplit --> ModTrans[Modul Transaksi /api/transactions]
    RouterSplit --> ModReports[Modul Laporan /api/reports]
    RouterSplit --> ModSuper[Modul Super Admin /api/super-admin]
    
    ModProduct --> D1[(Cloudflare D1 Database)]
    ModTrans --> D1
    ModReports --> D1

Teknologi & Infrastruktur (Katalog Endpoint)

Berikut adalah katalog ekstensif dari endpoint-endpoint penting yang tersedia dalam ekosistem backend Hono Worker Temuya POS. Tabel-tabel di bawah ini dikelompokkan berdasarkan fungsi bisnis intinya.

1. Modul Autentikasi & Sesi

Mengelola akses masuk pengguna, penyegaran token, dan informasi profil.

Method	Path Endpoint	Penjelasan Fungsi Utama	Kebutuhan Auth
`POST`	`/api/sessions/login`	Melakukan otentikasi menggunakan kredensial email dan kata sandi untuk mendapatkan JWT (JSON Web Token).	Tidak Ada
`POST`	`/api/sessions/refresh`	Memperbarui JWT yang hampir kadaluarsa menggunakan Refresh Token yang valid.	Refresh Token
`DELETE`	`/api/sessions/logout`	Mengakhiri sesi pengguna saat ini dan memasukkan token ke dalam daftar hitam (blacklist).	Bearer Token
`GET`	`/api/users/me`	Mengambil detail profil, hak akses (roles), dan informasi tenant dari pengguna yang sedang login.	Bearer Token

2. Modul Produk & Inventori

Pusat kendali untuk mengelola katalog barang dagangan, varian produk, dan melacak pergerakan stok.

Method	Path Endpoint	Penjelasan Fungsi Utama	Kebutuhan Auth
`GET`	`/api/products`	Mengambil daftar produk lengkap, mendukung paginasi, pencarian teks, dan penyaringan berdasarkan kategori.	Bearer / API Key
`POST`	`/api/products`	Menambahkan produk baru ke dalam katalog, termasuk pengaturan harga modal, harga jual, dan SKU.	Bearer / API Key
`PUT`	`/api/products/:id`	Memperbarui detail sebuah produk secara menyeluruh (Update produk spesifik).	Bearer / API Key
`GET`	`/api/categories`	Membaca struktur hierarki kategori produk yang tersedia di toko.	Bearer / API Key
`POST`	`/api/inventory/adjust`	Melakukan penyesuaian stok manual (tambah/kurang) karena alasan seperti barang rusak atau hilang, disertai pencatatan alasan.	Bearer / API Key
`POST`	`/api/stock-opname`	Memulai sesi penghitungan fisik persediaan barang (Stock Opname) berskala besar.	Bearer / API Key

3. Modul POS, Shift & Transaksi

Jantung operasional harian, mencatat setiap rupiah yang masuk dan keluar, serta perputaran kasir.

Method	Path Endpoint	Penjelasan Fungsi Utama	Kebutuhan Auth
`POST`	`/api/shift/open`	Membuka shift kerja kasir baru, mendeklarasikan saldo uang tunai awal yang ada di dalam laci.	Bearer Token
`POST`	`/api/shift/close`	Menutup shift kerja, mencatat selisih antara uang tunai fisik aktual dan kalkulasi sistem.	Bearer Token
`GET`	`/api/transactions`	Mengambil riwayat transaksi historis dengan parameter rentang tanggal dan status (sukses/batal).	Bearer / API Key
`POST`	`/api/transactions`	Mencatat transaksi penjualan baru ke dalam buku besar, secara otomatis memotong stok barang terkait.	Bearer / API Key
`POST`	`/api/transactions/:id/refund`	Memproses pembatalan (void) atau pengembalian dana penuh dari sebuah transaksi yang telah selesai.	Bearer / API Key
`GET`	`/api/open-bills`	Mengambil daftar tagihan/pesanan yang masih menggantung (belum dibayar), berguna untuk bisnis restoran (buka meja).	Bearer Token

4. Modul Laporan & Analitik

Menyajikan data mentah yang telah diagregasi menjadi wawasan bisnis yang berharga.

Method	Path Endpoint	Penjelasan Fungsi Utama	Kebutuhan Auth
`GET`	`/api/reports/sales-summary`	Mengembalikan ringkasan total pendapatan kotor, pendapatan bersih, dan jumlah struk dalam suatu periode.	Bearer / API Key
`GET`	`/api/reports/top-products`	Mengembalikan daftar produk paling laris berdasarkan volume barang terjual atau nilai Rupiah yang dihasilkan.	Bearer / API Key
`GET`	`/api/reports/payment-methods`	Menyajikan proporsi penggunaan metode pembayaran (Tunai, QRIS, Kartu Debit) yang disukai pelanggan.	Bearer / API Key

5. Modul Super Admin

Kawasan sangat terlarang, dirancang khusus untuk administrator sistem guna mengelola platform secara keseluruhan.

Method	Path Endpoint	Penjelasan Fungsi Utama	Kebutuhan Auth
`GET`	`/api/super-admin/tenants`	Melihat semua toko/tenant yang terdaftar di platform beserta status berlangganannya.	Super Admin Role
`POST`	`/api/super-admin/tenants/:id/block`	Memblokir atau menangguhkan sementara akses login seluruh pengguna pada sebuah tenant tertentu.	Super Admin Role
`GET`	`/api/super-admin/audit-logs`	Melihat jejak rekam aktivitas seluruh sistem secara global untuk tujuan pemantauan dan investigasi keamanan.	Super Admin Role

Keterkaitan dengan Fitur Lain

API Reference ini merupakan lembaran peta yang menghubungkan berbagai pulau fitur di Temuya POS:

Frontend POS (React/Astro): Setiap kali seorang kasir menekan tombol di layar sentuh, antarmuka pengguna tersebut secara diam-diam memanggil satu atau beberapa endpoint API yang terdaftar di sini. API adalah jembatan yang menghubungkan tombol visual dengan perubahan data di basis data.
API Keys & Otorisasi: Katalog endpoint ini mendefinisikan apa yang bisa dilakukan. Namun, fitur API Keys (untuk sistem eksternal) dan Manajemen Peran (untuk pengguna manusia) bertindak sebagai penjaga gerbang yang menentukan siapa yang diizinkan untuk memanggil endpoint spesifik tersebut.
Mode Offline & Sinkronisasi: Saat koneksi internet terputus, aplikasi POS menyimpan panggilan API ke rute seperti POST /api/transactions secara lokal. Ketika internet kembali hidup, sistem sinkronisasi akan menembakkan rentetan permintaan API yang tertunda ini ke server secara berurutan untuk mencocokkan data.

Hal Penting yang Perlu Diketahui

Saat menelusuri dan memanfaatkan API Temuya POS, perhatikan dengan cermat beberapa prinsip krusial berikut untuk memastikan kelancaran operasional Anda:

Paginasi adalah Sahabat Anda: Untuk endpoint yang berpotensi mengembalikan banyak baris data (seperti daftar produk atau transaksi historis), server tidak akan pernah memberikan seluruh data sekaligus. Anda harus menggunakan parameter query ?page=1&limit=50 untuk menelusuri data halaman demi halaman. Mengabaikan hal ini akan menyebabkan kegagalan sistem.
Format Waktu Universal (UTC): Seluruh stempel waktu (timestamps) yang diterima dan dikirim melalui API ini, baik itu waktu pembuatan produk maupun waktu transaksi ditutup, menggunakan format standar ISO 8601 di zona waktu UTC (Universal Time Coordinated). Pastikan aplikasi Anda melakukan konversi zona waktu yang tepat saat menampilkannya kepada pengguna akhir di zona waktu lokal mereka.
Tangani Kesalahan dengan Anggun (Graceful Error Handling): Jangan berasumsi bahwa setiap panggilan API akan selalu berhasil. Pastikan kode Anda siap menerima dan memproses berbagai kode status HTTP dengan bijak, seperti 400 Bad Request (jika data yang Anda kirim tidak valid), 401 Unauthorized (jika token Anda kadaluarsa), 403 Forbidden (jika Anda kekurangan izin), dan 500 Internal Server Error (jika terjadi masalah langka pada server kami).
Perbarui Header Token: Untuk panggilan yang menggunakan Bearer Token (sesi login pengguna), perhatikan waktu kadaluarsa (expiry) dari token tersebut. Rancang mekanisme untuk secara proaktif memanggil /api/sessions/refresh sebelum token utama mati, agar pengguna tidak tiba-tiba terlempar keluar dari aplikasi saat sedang bekerja.
Dokumentasi yang Hidup: Arsitektur perangkat lunak kami terus berkembang seiring berjalannya waktu. Endpoint baru mungkin akan ditambahkan, dan beberapa endpoint lama mungkin akan dinyatakan usang (deprecated) sebelum akhirnya dihapus. Berlanggananlah pada notifikasi pembaruan developer untuk selalu mengetahui perubahan terbaru pada struktur referensi API ini.