OpenAPI Specification¶

Version: 3.0.0 Last Updated: 2026-05-26 Status: ✅ Published

Dokumen ini berisi spesifikasi OpenAPI untuk backend NestJS ERP migrasi.

📄 Sumber Kebenaran¶

Sumber	Lokasi	Status
OpenAPI JSON (canonical)	backend/docs/openapi.json	✅ Auto-generated
Snapshot docs	docs/api/openapi.json	✅ Synced
Implementasi	`backend/src/*/.controller.ts`	Runtime truth
Standard	backend/docs/API_STANDARD.md	Normatif

🌐 Akses Dokumen¶

1. Swagger UI (Development)¶

# Backend running di dev
open http://localhost:3000/api/docs

2. Static JSON¶

# Dari root repo
curl http://localhost:3000/api/docs-json > openapi.json

# Atau langsung file
cat backend/docs/openapi.json

3. MkDocs Portal¶

Dokumen OpenAPI terintegrasi di portal MkDocs:

npm run docs:serve
# Buka: http://localhost:8000/migrasi/api/openapi-spec/

📊 Ringkasan Endpoint¶

Authentication & Session¶

Method	Path	Description
POST	`/api/auth/sesi`	Create session (Firebase JWT)
POST	`/api/auth/refresh`	Refresh access token
DELETE	`/api/auth/sesi`	Logout / invalidate session

Tenant Management¶

Method	Path	Description
GET	`/api/tenants`	List available tenants
POST	`/api/tenants/{kode}/pilih`	Select active tenant
GET	`/api/tenants/saya`	Get current tenant info

Master Data¶

Method	Path	Description
GET	`/api/master/barang`	List barang
POST	`/api/master/barang`	Create barang
PUT	`/api/master/barang/:id`	Update barang
GET	`/api/master/kontak`	List kontak (pelanggan/vendor)
GET	`/api/master/akun`	List chart of accounts
GET	`/api/master/lokasi`	List lokasi gudang

Transaksi¶

Method	Path	Description
GET	`/api/transaksi/:jenis`	List transaksi by jenis
POST	`/api/transaksi/:jenis`	Create transaksi
GET	`/api/transaksi/:jenis/:id`	Get detail transaksi
PUT	`/api/transaksi/:jenis/:id`	Update transaksi
DELETE	`/api/transaksi/:jenis/:id`	Delete transaksi

Jenis Transaksi: - PJ — Penjualan - PB — Pembelian - RJ — Retur Penjualan - RB — Retur Pembelian - PL — Pemindahan Lokasi - OS — Opname Stok

Laporan¶

Method	Path	Description
GET	`/api/laporan/stok`	Laporan stok
GET	`/api/laporan/penjualan`	Laporan penjualan
GET	`/api/laporan/piutang`	Aging piutang
GET	`/api/laporan/hutang`	Aging hutang
GET	`/api/laporan/jurnal`	Jurnal umum
GET	`/api/laporan/neraca`	Neraca
GET	`/api/laporan/rugi-laba`	Laporan rugi laba

Dashboard¶

Method	Path	Description
GET	`/api/dashboard/summary`	Ringkasan dashboard
GET	`/api/dashboard/trend`	Trend harian
GET	`/api/dashboard/top10`	Top 10 pelanggan/produk

Operations (CDC)¶

Method	Path	Description
GET	`/api/ops/cdc/jobs`	List CDC jobs
POST	`/api/ops/cdc/jobs`	Create CDC job (control plane)
GET	`/api/ops/cdc/status`	CDC pipeline status

🔐 Autentikasi¶

Flow¶

┌─────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Client │     │  Firebase│     │  Backend │     │PostgreSQL│
└────┬────┘     └────┬─────┘     └────┬─────┘     └────┬─────┘
     │               │                │                │
     │  1. Login     │                │                │
     │──────────────>│                │                │
     │               │                │                │
     │  2. ID Token  │                │                │
     │<──────────────│                │                │
     │               │                │                │
     │  3. POST /sesi│                │                │
     │  (Firebase JWT)                │                │
     │──────────────>│                │                │
     │               │                │                │
     │               │  4. Verify JWT │                │
     │               │───────────────>│                │
     │               │                │                │
     │  5. JWT-1     │                │                │
     │  (no tenant)  │                │                │
     │<──────────────│                │                │
     │               │                │                │
     │  6. POST /pilih tenant         │                │
     │───────────────────────────────>│                │
     │               │                │                │
     │               │  7. Validate   │  8. Query      │
     │               │───────────────>│───────────────>│
     │               │                │                │
     │  9. JWT-2     │                │                │
     │  (with tenant)│                │                │
     │<──────────────│                │                │
     │               │                │                │
     │  10. API call │                │                │
     │  (JWT-2)      │                │                │
     │───────────────────────────────>│                │
     └─────────────────────────────────────────────────┘

Header Requirements¶

Request	Headers
Public (`/health`, `/auth/sesi`)	None
Tenant-aware (most endpoints)	`Authorization: Bearer <JWT-2>`
Admin-only	`Authorization: Bearer <JWT-2>` + `x-admin-key`

JWT Claims (JWT-2)¶

{
  "sub": "user-uuid",
  "email": "user@tenant.com",
  "tenant_kode": "sparepart",
  "peran": "admin",
  "iat": 1234567890,
  "exp": 1234571490
}

📦 Schema Definitions¶

Common DTOs¶

`SessionResponseDto`¶

{
  "token": "string",
  "user": {
    "id": "uuid",
    "email": "string",
    "nama": "string"
  },
  "tenants": [
    {
      "kode": "string",
      "nama": "string",
      "peran": "string"
    }
  ]
}

`TransaksiResponseDto`¶

{
  "id": "bigint",
  "nomor_bukti": "string",
  "jenis_kode": "string",
  "tanggal": "date",
  "kontak_id": "bigint",
  "total_nilai": "numeric",
  "status": "string",
  "detail": [
    {
      "barang_id": "bigint",
      "qty": "numeric",
      "harga": "numeric",
      "hpp": "numeric",
      "subtotal": "numeric"
    }
  ]
}

`ErrorDto`¶

{
  "statusCode": "number",
  "message": "string | string[]",
  "error": "string"
}

🔄 Versioning¶

Strategy¶

API menggunakan URI versioning (bukan header):

/api/v1/health  — Current (default)
/api/v2/health  — Future version

Saat ini: v1 (implicit, tanpa prefix)

Deprecation Policy¶

T-90 days: Announce deprecation via:
Deprecation header in responses
MkDocs changelog
Team Slack announcement
T-30 days: Return warnings in response body
T-0: Remove endpoint, return 410 Gone

🧪 Testing¶

Swagger UI Smoke Test¶

# 1. Open Swagger UI
open http://localhost:3000/api/docs

# 2. Try health check
GET /api/health
# Expected: 200 OK { "status": "ok" }

# 3. Try auth flow
POST /api/auth/sesi
Body: { "email": "...", "password": "..." }
# Expected: 200 OK { "token": "..." }

CLI Test¶

# Health check
curl http://localhost:3000/api/health | jq .

# Create session
curl -X POST http://localhost:3000/api/auth/sesi \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@test.com","password":"test"}' | jq .

# List tenants
TOKEN="eyJ..."
curl -X GET http://localhost:3000/api/tenants \
  -H "Authorization: Bearer $TOKEN" | jq .

📝 How to Update¶

1. Auto-Generation (Recommended)¶

OpenAPI di-generate otomatis dari NestJS decorators:

cd backend

# Generate openapi.json
npm run openapi:generate

# Verify
cat docs/openapi.json | jq '.info.version'

2. Manual Review¶

Before committing changes:

# 1. Check diff
git diff backend/docs/openapi.json

# 2. Validate JSON
cat backend/docs/openapi.json | jq . > /dev/null && echo "Valid JSON"

# 3. Test Swagger UI
npm run start:dev
# Open http://localhost:3000/api/docs

3. Sync to docs/api/¶

# Copy to docs snapshot
cp backend/docs/openapi.json docs/api/openapi.json

# Commit
git add backend/docs/openapi.json docs/api/openapi.json
git commit -m "docs(api): update OpenAPI spec"

✅ Checklist API Changes¶

New Endpoint¶

#	Task	Status
1	Add controller method with decorators	[ ]
2	Add DTO classes (request/response)	[ ]
3	Add `@ApiTags`, `@ApiOperation`, `@ApiResponse`	[ ]
4	Run `npm run openapi:generate`	[ ]
5	Test via Swagger UI	[ ]
6	Update this document	[ ]
7	Add to API_STANDARD.md	[ ]

Breaking Change¶

#	Task	Status
1	Announce deprecation (T-90)	[ ]
2	Create v2 endpoint	[ ]
3	Update OpenAPI spec	[ ]
4	Update client SDKs	[ ]
5	Monitor usage	[ ]
6	Remove v1 after T-0	[ ]

🔗 Referensi¶

Appendix: OpenAPI Spec v3.0.0 — Last updated 2026-05-26