Kontrak API PPN POS (Server-Driven Mode)

Dokumen ini adalah kontrak endpoint untuk server agar kompatibel dengan aplikasi POS saat ini.

Aturan inti aplikasi POS saat ini:

Mode pajak transaksi dapat mengikuti server: include atau exclude.
Persentase PPN mengikuti ppn_percent dari server jika tersedia dan valid.
Jika endpoint belum tersedia/invalid/tidak ada aturan, POS fallback aman ke include 11% (non-fatal).

1) Endpoint

Item	Nilai
Config key POS	`ep_ppn_settings`
Method	`GET`
Contoh path	`/eusvc/NonRest/get_ppn_settings`
Auth	`Authorization: Bearer <access_token>`
Query opsional	`machine_id`, `cabang_id`

2) Request

Headers wajib

Authorization: Bearer <access_token>
Accept: application/json

Query string (opsional, direkomendasikan didukung server)

?machine_id=118933446257318&cabang_id=47

3) Response Sukses (Wajib)

Server wajib mengembalikan struktur berikut agar parsing POS konsisten:

{
  "status": 1,
  "reason": "ok",
  "message": "PPN setting loaded.",
  "data": {
    "ppn_mode": "include",
    "ppn_percent": 11,
    "policy_version": "2026-03-09T00:00:00Z",
    "effective_from": "2026-03-09 00:00:00",
    "scope": "global"
  },
  "trace_id": "eusvc-ppn-20260309-0001"
}

Validasi di POS

status harus 1.
data.ppn_mode harus include atau exclude.
data.ppn_percent harus integer 0..100.

4) Response Error (Wajib)

{
  "status": 0,
  "reason": "unauthorized",
  "message": "Access token tidak valid atau tidak tersedia.",
  "data": null,
  "trace_id": "eusvc-ppn-20260309-0002",
  "error": "jwt_expired"
}

Kode reason yang direkomendasikan:

unauthorized
forbidden
invalid_payload
setting_not_found
internal_error

5) Perilaku Fallback Jika Aturan Server Belum Ada

Jika endpoint belum dikonfigurasi, timeout, 404, payload invalid, atau server mengembalikan status=0, POS tidak menghentikan proses sinkronisasi. POS akan menerapkan fallback default lokal: ppn_mode=include dan ppn_percent=11.

6) Catatan Implementasi Server

Pastikan endpoint ini termasuk endpoint protected JWT (access token).
Tetap kirim response envelope konsisten: status/reason/message/data/trace_id.
Jika setting belum ada, kembalikan status=0 dengan reason jelas, bukan HTML/error mentah.

7) Ringkasan Kontrak Minimal

{
  "status": 1,
  "reason": "ok",
  "data": {
    "ppn_mode": "include",
    "ppn_percent": 11
  },
  "trace_id": "..."
}

Contoh mode exclude

{
  "status": 1,
  "reason": "ok",
  "data": {
    "ppn_mode": "exclude",
    "ppn_percent": 11
  },
  "trace_id": "eusvc-ppn-20260309-0015"
}