Matriks Endpoint API × Auth × Tenant Context¶

Last Updated: 2026-05-26
OpenAPI Version: 3.0 — 65 endpoints, 19 controllers
Source: backend/src/**/*.controller.ts

Dokumen ini memetakan setiap endpoint API terhadap: - Auth requirement — apakah butuh JWT atau publik - Tenant context — apakah butuh tenant_kode dari JWT payload - Auth scope/role — role minimum yang dibutuhkan - Idempotency — apakah support Idempotency-Key header

Legenda¶

Simbol	Arti
🔒	Butuh JWT (`@UseGuards(JwtAuthGuard)`)
🌐	Publik (`@Public()` atau no guard)
🏢	Butuh tenant context (dari JWT `tenant_kode`)
🌍	Multi-tenant (user bisa akses beberapa tenant)
⚙️	System/ops only (butuh role khusus)
✅	Support idempotency (`Idempotency-Key` header)

Ringkasan Statistik¶

Kategori	Count
Total endpoints	65
Butuh JWT	~60
Publik	~5
Butuh tenant context	~55
System/ops only	~5
Support idempotency	~10 (transaksi)

1. Auth & Tenant Management¶

1.1 Auth — Publik (tidak butuh JWT)¶

Method	Path	Auth	Tenant	Idempotent	Deskripsi
`POST`	`/api/auth/sesi`	🌐	🌍	✅	Login: Firebase token → JWT aplikasi + daftar tenant user

Catatan: - Endpoint ini satu-satunya yang tidak butuh JWT - Response: { token: string, tenants: TenantDto[], default_tenant?: string } - Idempotency: optional, untuk prevent double-login

1.2 Tenant Selection — Butuh JWT¶

Method	Path	Auth	Tenant	Role	Deskripsi
`GET`	`/api/tenants`	🔒	🌍	Semua	List semua tenant yang bisa diakses user
`POST`	`/api/tenants/:kode/pilih`	🔒	🌍	Semua	Pilih tenant aktif → set `tenant_kode` di JWT

Catatan: - User bisa punya akses ke multiple tenant - Setelah pilih tenant, request selanjutnya bawa JWT dengan tenant_kode baru

2. Master Data — Butuh Tenant Context¶

Semua endpoint di bawah wajib bawa JWT dengan tenant_kode valid.

2.1 Kontak (Customer/Vendor/Karyawan)¶

Method	Path	Auth	Tenant	Idempotent	Deskripsi
`GET`	`/api/master/kontak`	🔒	🏢	—	List kontak (pagination)
`POST`	`/api/master/kontak`	🔒	🏢	✅	Buat kontak baru
`GET`	`/api/master/kontak/:id`	🔒	🏢	—	Detail kontak
`PUT`	`/api/master/kontak/:id`	🔒	🏢	—	Update kontak
`DELETE`	`/api/master/kontak/:id`	🔒	🏢	—	Hapus kontak

Query params standar:

?page=1&per_page=20&search=nama&sort=created_at:desc

2.2 Barang (Produk)¶

Method	Path	Auth	Tenant	Idempotent	Deskripsi
`GET`	`/api/master/barang`	🔒	🏢	—	List barang
`POST`	`/api/master/barang`	🔒	🏢	✅	Buat barang
`GET`	`/api/master/barang/:id`	🔒	🏢	—	Detail barang
`PUT`	`/api/master/barang/:id`	🔒	🏢	—	Update barang
`DELETE`	`/api/master/barang/:id`	🔒	🏢	—	Hapus barang

2.3 Lokasi (Gudang/Toko)¶

Method	Path	Auth	Tenant	Idempotent	Deskripsi
`GET`	`/api/master/lokasi`	🔒	🏢	—	List lokasi
`POST`	`/api/master/lokasi`	🔒	🏢	✅	Buat lokasi
`GET`	`/api/master/lokasi/:id`	🔒	🏢	—	Detail lokasi
`PUT`	`/api/master/lokasi/:id`	🔒	🏢	—	Update lokasi
`DELETE`	`/api/master/lokasi/:id`	🔒	🏢	—	Hapus lokasi

2.4 Jenis Transaksi¶

Method	Path	Auth	Tenant	Idempotent	Deskripsi
`GET`	`/api/master/jenis-transaksi`	🔒	🏢	—	List jenis transaksi (penjualan, pembelian, dll)
`POST`	`/api/master/jenis-transaksi`	🔒	🏢	✅	Buat jenis baru
`GET`	`/api/master/jenis-transaksi/:id`	🔒	🏢	—	Detail jenis
`PUT`	`/api/master/jenis-transaksi/:id`	🔒	🏢	—	Update jenis

2.5 Harga Satuan¶

Method	Path	Auth	Tenant	Idempotent	Deskripsi
`GET`	`/api/master/harga-satuan`	🔒	🏢	—	List harga satuan
`POST`	`/api/master/harga-satuan`	🔒	🏢	✅	Buat harga
`GET`	`/api/master/harga-satuan/:id`	🔒	🏢	—	Detail harga
`PUT`	`/api/master/harga-satuan/:id`	🔒	🏢	—	Update harga

2.6 Akun (Chart of Accounts)¶

Method	Path	Auth	Tenant	Idempotent	Deskripsi
`GET`	`/api/master/akun`	🔒	🏢	—	List akun (COA)
`POST`	`/api/master/akun`	🔒	🏢	✅	Buat akun
`GET`	`/api/master/akun/:id`	🔒	🏢	—	Detail akun
`PUT`	`/api/master/akun/:id`	🔒	🏢	—	Update akun

3. Transaksi — Butuh Tenant Context + Idempotency¶

Semua endpoint transaksi wajib: - JWT dengan tenant_kode - Idempotency-Key header untuk POST (recommended) - Role: admin atau staff dengan scope transaksi:*

3.1 Transaksi Generic (semua jenis)¶

Method	Path	Auth	Tenant	Idempotent	Deskripsi
`GET`	`/api/transaksi/:jenis`	🔒	🏢	—	List transaksi by jenis (`penjualan`, `pembelian`, `retur`, `stok`)
`POST`	`/api/transaksi/:jenis`	🔒	🏢	✅	Buat transaksi baru
`GET`	`/api/transaksi/:jenis/:id`	🔒	🏢	—	Detail transaksi
`PATCH`	`/api/transaksi/:jenis/:id`	🔒	🏢	—	Update (limited, hanya draft)
`POST`	`/api/transaksi/:jenis/:id/approve`	🔒	🏢	✅	Approve transaksi
`POST`	`/api/transaksi/:jenis/:id/void`	🔒	🏢	✅	Void transaksi

Query params:

?page=1&per_page=20&dari=2026-01-01&sampai=2026-12-31&status=draft

Jenis enum: penjualan, pembelian, retur_penjualan, retur_pembelian, stok_masuk, stok_keluar, kas_masuk, kas_keluar

3.2 Preferensi Tabel Transaksi¶

Method	Path	Auth	Tenant	Deskripsi
`GET`	`/api/transaksi/:jenis/preferensi-tabel`	🔒	🏢	Get user preference kolom tabel
`PUT`	`/api/transaksi/:jenis/preferensi-tabel`	🔒	🏢	Save preference kolom

4. Laporan — Butuh Tenant Context¶

4.1 Laporan Keuangan¶

Method	Path	Auth	Tenant	Query Params	Deskripsi
`GET`	`/api/laporan/neraca`	🔒	🏢	—	Neraca (posisi keuangan)
`GET`	`/api/laporan/rugi-laba`	🔒	🏢	`?dari=&sampai=`	Laporan rugi laba
`GET`	`/api/laporan/piutang`	🔒	🏢	`?dari=&sampai=&kontak_id=&status=&page=`	Laporan piutang
`GET`	`/api/laporan/hutang`	🔒	🏢	`?dari=&sampai=&kontak_id=&status=&page=`	Laporan hutang

Status enum: belum, sebagian, lunas, outstanding

4.2 Laporan Stok¶

Method	Path	Auth	Tenant	Query Params	Deskripsi
`GET`	`/api/laporan/stok`	🔒	🏢	`?lokasi_id=&barang_id=`	Stok saat ini
`GET`	`/api/laporan/kartu-stok/:barang_id`	🔒	🏢	`?dari=&sampai=&lokasi_id=`	Mutasi stok per barang
`GET`	`/api/laporan/penjualan`	🔒	🏢	`?dari=&sampai=&kontak_id=&barang_id=&page=`	Detail penjualan
`GET`	`/api/laporan/penjualan/summary`	🔒	🏢	`?group_by=barang\|pelanggan\|bulan&dari=&sampai=`	Summary penjualan

Group by enum: barang, pelanggan, bulan, hari

5. Dashboard & KPI — Butuh Tenant Context¶

Method	Path	Auth	Tenant	Deskripsi
`GET`	`/api/dashboard/kpi`	🔒	🏢	KPI utama: penjualan, pembelian, stok, kas
`GET`	`/api/dashboard/kpi/stream`	🔒	🏢	SSE stream — real-time update KPI
`GET`	`/api/dashboard/trigger`	🌐	🏢	Trigger manual SSE event (untuk testing)

Catatan: - SSE stream butuh JWT di Authorization header - Query param tenant optional di /trigger (fallback ke JWT)

6. Pengaturan Tenant — Butuh Tenant Context + Admin Role¶

Method	Path	Auth	Tenant	Role	Deskripsi
`GET`	`/api/pengaturan/tenant`	🔒	🏢	Semua	Profil tenant saat ini
`PATCH`	`/api/pengaturan/tenant`	🔒	🏢	`admin`	Update profil tenant
`GET`	`/api/pengaturan/tenant/modul`	🔒	🏢	Semua	List modul aktif
`PUT`	`/api/pengaturan/tenant/modul`	🔒	🏢	`admin`	Update status modul
`GET`	`/api/pengaturan/pengguna`	🔒	🏢	`admin`	List pengguna tenant
`POST`	`/api/pengaturan/pengguna`	🔒	🏢	`admin`	Tambah pengguna
`PUT`	`/api/pengaturan/pengguna/:id/tenant-assignments`	🔒	🌍	`admin`	Update akses tenant user

7. Notifikasi — Butuh Tenant Context¶

Method	Path	Auth	Tenant	Deskripsi
`GET`	`/api/notifikasi`	🔒	🏢	List notifikasi user
`POST`	`/api/notifikasi/request-akses-tenant`	🔒	🌍	Request akses ke tenant lain
`POST`	`/api/notifikasi/:id/baca`	🔒	🏢	Mark notifikasi sebagai dibaca

8. Ops CDC — System/Operations Only¶

Method	Path	Auth	Tenant	Role	Deskripsi
`POST`	`/api/ops/cdc/jobs`	🔒	🌍	`ops`	Buat job CDC manual (initial load, retry)
`GET`	`/api/ops/cdc/jobs`	🔒	🌍	`ops`	List semua job CDC
`GET`	`/api/ops/cdc/jobs/:id`	🔒	🌍	`ops`	Detail job
`GET`	`/api/ops/cdc/jobs/:id/log`	🔒	🌍	`ops`	Log job
`POST`	`/api/ops/cdc/jobs/:id/aksi`	🔒	🌍	`ops`	Aksi: `approve`, `cancel`, `retry`

Headers optional: - X-Idempotency-Key: string - X-Mode-Operasi: full | partial

9. Draft & AI — Butuh Tenant Context¶

9.1 Draft (Transaksi Pending)¶

Method	Path	Auth	Tenant	Deskripsi
`GET`	`/api/draft`	🔒	🏢	List draft transaksi
`POST`	`/api/draft`	🔒	🏢	Buat draft
`GET`	`/api/draft/:id`	🔒	🏢	Detail draft
`PUT`	`/api/draft/:id`	🔒	🏢	Update draft
`POST`	`/api/draft/:id/submit`	🔒	🏢	Submit draft → transaksi

9.2 AI Assistant¶

Method	Path	Auth	Tenant	Deskripsi
`POST`	`/api/ai/query`	🔒	🏢	Natural language → SQL/query
`GET`	`/api/ai/suggestions`	🔒	🏢	Saran optimisasi

10. Health & Monitoring¶

Method	Path	Auth	Tenant	Deskripsi
`GET`	`/api/health`	🌐	🌍	Health check (tanpa auth)
`GET`	`/api/audit`	🔒	🌍	Audit log (admin only)

Standard Query Parameters¶

Semua endpoint list WAJIB support:

Param	Type	Default	Deskripsi
`page`	int	1	Halaman (1-indexed)
`per_page`	int	20	Items per halaman (max 500)
`search`	string	—	Kata kunci umum
`search_fields`	string[]	—	Field yang di-search (`nama,kode`)
`sort`	string	—	`field:asc,field2:desc`
`fields`	string[]	—	Field yang ditampilkan
`filter`	string	—	Filter tambahan `key=value`

Contoh:

GET /api/master/barang?page=2&per_page=50&search=semen&sort=created_at:desc&fields=id,nama,harga

Idempotency¶

Endpoint POST berikut RECOMMENDED bawa Idempotency-Key header:

Endpoint	Key Format	TTL
`/api/transaksi/:jenis`	`txn:{jenis}:{uuid}`	24h
`/api/master/*` (POST)	`master:{entity}:{uuid}`	1h
`/api/auth/sesi`	`login:{firebase_uid}`	5m
`/api/ops/cdc/jobs`	`cdc:{tenant}:{timestamp}`	1h

Response untuk duplicate key:

{
  "status": 200,
  "idempotent": true,
  "original_request_id": "abc123"
}

Error Response Format¶

Semua error mengikuti format:

{
  "statusCode": 400,
  "message": "Validasi gagal: nama wajib diisi",
  "error": "Bad Request",
  "timestamp": "2026-05-26T10:30:00.000Z",
  "path": "/api/master/barang"
}

Error codes:

Code	Arti
400	Validasi gagal
401	JWT tidak valid / tidak ada
403	Tidak punya akses (role/tenant)
404	Resource tidak ditemukan
409	Conflict (duplikat, idempotency)
422	Idempotency key conflict
500	Internal server error

Tenant Context Flow¶

1. User login → POST /api/auth/sesi
   Response: { token, tenants: [{kode, nama}] }

2. User pilih tenant → POST /api/tenants/:kode/pilih
   Response: { new_token }  // tenant_kode baru di payload

3. Request selanjutnya → Authorization: Bearer {new_token}
   Backend extract tenant_kode dari JWT payload
   Query otomatis filter by tenant schema

Auth Scopes / Roles¶

Role	Scope	Deskripsi
`admin`	`*`	Akses penuh tenant
`staff`	`transaksi:`, `laporan:`, `master:*`	Operasional harian
`viewer`	`laporan:read`	Read-only laporan
`ops`	`ops:`, `cdc:`	Operasional CDC (system)

TODO — Yang Belum Terverifikasi¶

[ ] Versioning API strategy (/api/v2 vs header-based)
[ ] Rate limit per role/endpoint
[ ] Audit logging detail per endpoint
[ ] Webhook support untuk event transaksi
[ ] Bulk operations (batch insert/update)

Terkait¶

OpenAPI Spec — Full spec 191KB
README.md — API overview
../../backend/TODO.md — Backend tasks
ListQueryDto — Standard pagination