​

📚 Manajemen Collection API (Bruno/Postman) di MStore ERP

​

1. Konteks: Kenapa Collection Jadi Rumit?

• Multi-tenant & multi-company (holding, subholding, subsidiary).
• Multi-branch per company (store, warehouse, outlet).
• Multi-negara (beda aturan pajak, mata uang, format invoice).
• Multi-role (cashier, owner, finance, auditor, ops, system).
• Banyak domain: Auth, Organization, Orders, Inventory, Finance, Tax, HR, Integrations, Compliance.

• Duplikasi folder per negara.
• Duplikasi folder per role.
• Sulit dipakai ulang lintas entity/country.
• Susah dipahami tester/QA baru.

​

2. Kondisi Aktual Bruno Collections

third_party/bruno
├── 00_API-Xendit          # Integrasi payment gateway
├── 00_V3_XENDIT           # Versi lain Xendit
├── 00_XENDIT_TEST_SELF    # Playground/payment test
├── 01_FLOW_MSTORE         # Flow end-to-end + RBAC
├── 02_API_L0              # API per role level 0 (Cashier, Owner, Viewer)
├── 03_API_L1              # API per role level 1 (AUD, FIN-MGR, INV-MGR, dst.)
├── 04_API_L2              # (reserved / pattern serupa)
├── 05_API_L3              # (reserved / pattern serupa)
├── 06_API_L4              # (reserved / pattern serupa)
├── 98_MSTORE              # Domain-level: ONBOARDING, AUTH, PRODUCT, INVENTORY, REPORT, TRANSACTION, dst.
└── README_API_LEVELS.md   # Penjelasan API levels & RBAC

• Sudah ada domain-level di 98_MSTORE (ONBOARDING, AUTH, INVENTORY, PRODUCT, REPORT, TRANSACTION, dll.).
• Sudah ada flow-level di 01_FLOW_MSTORE (AUTH FLOW, FLOW CHECKOUT QRIS, SUBMIT PAYMENT POS, dsb.).
• Masih banyak folder per-role di 02_API_L0, 03_API_L1, dst. dengan subfolder seperti:
  Copy

  02_API_L0/
  ├── L0_CASHIER
  ├── L0_OWNER
  └── L0_VIEWER
  
  03_API_L1/
  ├── L1_AUD
  ├── L1_CSH
  ├── L1_FIN-MGR
  ├── L1_HR-MGR
  ├── L1_INV-MGR
  └── L1_OWN-MGR
  

• Tiap collection memiliki folder environments/ untuk konfigurasi.

• Kamu sudah bergerak ke arah domain-based + flow-based (bagus).
• Tapi masih ada kompleksitas tinggi karena duplikasi per role di API_L0..L4.

​

3. Blueprint Ideal (Dari Draft Konsep)

​

3.1 Domainization

Enterprise ERP (Collection)
├── Auth
├── Organization
├── Orders
├── Inventory
├── Finance
├── Tax
├── HR
├── Integrations
└── Compliance

​

3.2 Environmentization

{
  "base_url": "https://api-global.erp.company.com",
  "entity_id": "HK-001",
  "country_code": "HK",
  "currency": "HKD",
  "vat_rate": 0,
  "withholding_rate": 0.02,
  "role": "finance_local",
  "token": "{{dynamic_token}}"
}

​

3.3 Flow Mapping

Orders
├── 01_draft
├── 02_approved
├── 03_paid
├── 04_picked
├── 05_shipped
└── 06_settled

​

4. Gap Analysis: Blueprint vs Bruno Saat Ini

​

4.1 Sudah Selaras

• Domainization (parsial):
  • 98_MSTORE sudah berisi domain: ONBOARDING, AUTH, MERCHANT, PRODUCT, INVENTORY, TRANSACTION, REPORT, dll.
  • 00_API-Xendit dan 00_V3_XENDIT sudah terpisah sebagai domain Integrations → Payment.
• Flow Mapping (parsial):
  • 01_FLOW_MSTORE menyimpan flow seperti AUTH FLOW, FLOW CHECKOUT QRIS, SUBMIT PAYMENT POS, dsb.
  • Sudah memakai pola flow per use-case, meskipun belum full 01_, 02_ konsisten.
• Environmentization (parsial):
  • Masing-masing collection Bruno punya folder environments/ untuk token, base_url, dsb.

​

4.2 Belum Selaras / Titik Kerumitan

• Folder per role (L0_CASHIER, L0_OWNER, L1_FIN-MGR, dll.) masih mendominasi:
  • Menyulitkan reuse request antar role.
  • Menambah overhead maintenance kalau ada perubahan endpoint.
• Belum ada domain khusus untuk:
  • Organization (entity_list, entity_switch, permission_matrix).
  • Tax (vat/gst/withholding/invoice numbering).
  • Compliance (audit_logs, data_retention).
• Flows belum sepenuhnya distandarisasi:
  • Beberapa flow ada di 01_FLOW_MSTORE, sebagian lain tersebar di domain lain.

​

5. Rekomendasi Refactor Bertahap

​

5.1 Langkah 1 – Tetapkan “Collection Induk” Domain-Based

98_MSTORE
├── AUTH
├── MERCHANT / ORGANIZATION
├── PRODUCT
├── INVENTORY
├── TRANSACTION / ORDERS
├── FINANCE (AR/AP/GL)
├── TAX
├── HR
├── INTEGRATIONS (link ke 00_API-Xendit, dll.)
└── COMPLIANCE

• Rename/struktur ulang folder di 98_MSTORE supaya mirip blueprint domain.
• Jadikan 98_MSTORE sumber utama semua endpoint; folder API_L0..L4 hanya view/filter.

​

5.2 Langkah 2 – Pindahkan Role ke Environment

02_API_L0/L0_CASHIER
02_API_L0/L0_OWNER
03_API_L1/L1_FIN-MGR
...

environments/
├── L0_CASHIER.json
├── L0_OWNER.json
├── L1_FIN_MGR.json
├── L1_INV_MGR.json
└── AUDITOR.json

{
  "base_url": "{{base_url_mstore}}",
  "role": "L1_FIN_MGR",
  "token": "{{jwt_token}}",
  "entity_id": "COMP-ID-001",
  "country_code": "ID"
}

• Endpoint cukup 1 kali di domain (misal POST /v1/transaction), behavior beda tergantung role/env.
• Mengurangi duplikasi folder & request.

​

5.3 Langkah 3 – Standarisasi Flow Folder

01_FLOW_MSTORE
├── AUTH FLOW
├── ONBOARDING MERCHANT
├── POS CHECKOUT
├── STOCK OPNAME
└── INTERCOMPANY BILLING

TRANSACTION
├── 01_create_draft
├── 02_approve
├── 03_pay
├── 04_fulfill
└── 05_close

​

5.4 Langkah 4 – Tambah Domain Organization, Tax, Compliance

• ORGANIZATION:
  • GET /entities, POST /entity/switch, GET /permissions/matrix.
• TAX:
  • POST /tax/calculate, GET /tax/rates, GET /invoice/numbering.
• COMPLIANCE:
  • GET /audit/logs, GET /data-retention/policies.

​

6. Pola Penamaan & Konvensi

• Folder: UPPER_SNAKE_CASE untuk domain utama (AUTH, INVENTORY, FINANCE).
• Subfolder flow: prefix numerik 01_, 02_, 03_ untuk urutan.
• Request: HTTP_METHOD + tujuan (contoh: POST - Create Transaction, GET - List Inventory).
• Environment:
  • Nama: ENV_{COUNTRY}_{ROLE} (misal: ENV_ID_L1_FIN, ENV_SG_AUDITOR).

​

7. Ringkasan

• Faktual:
  • Struktur Bruno saat ini sudah punya kombinasi domain-level, flow-level, dan API level per role.
  • Kompleksitas terbesar datang dari duplikasi folder per role dan per level API.
• Rekomendasi:
  • Jadikan 98_MSTORE sebagai collection domain utama.
  • Pindahkan variasi role/negara/entity ke environment, bukan folder.
  • Standarisasi flow dengan prefix dan pisahkan domain Organization, Tax, dan Compliance.
• Hasil akhir yang diinginkan:
  • Collection lebih mudah dipahami untuk engineer baru, QA, dan auditor.
  • Perubahan endpoint cukup di satu tempat (domain), sementara behavior dibedakan lewat environment.
  • Selaras dengan pola enterprise yang kamu tulis di dokumen konsep (domainization, environmentization, flow mapping).