# Postman Collection Guide - Identiti Perniagaan APIs

## 📦 File Postman Collection

**File:** `Identiti_Perniagaan_APIs.postman_collection.json`

Collection ini berisi 6 API endpoints untuk form "Identiti Perniagaan" (Business Identity).

---

## 🚀 Cara Import ke Postman

### Method 1: Import File
1. Buka Postman
2. Klik **Import** (tombol di pojok kiri atas)
3. Drag & drop file `Identiti_Perniagaan_APIs.postman_collection.json`
4. Atau klik **Choose Files** dan pilih file tersebut
5. Klik **Import**

### Method 2: Import dari Raw JSON
1. Buka Postman
2. Klik **Import** → **Raw text**
3. Copy-paste isi file JSON
4. Klik **Continue** → **Import**

---

## ⚙️ Setup Environment Variable

Setelah import, set environment variable `base_url`:

### Option A: Global Variable
1. Klik ⚙️ (Settings) di kanan atas
2. Tab **Variables**
3. Add variable:
   - **Variable:** `base_url`
   - **Initial Value:** `http://localhost:8000`
   - **Current Value:** `http://localhost:8000`

### Option B: Environment
1. Klik **Environments** (di sidebar kiri)
2. Create new environment (misal: "Local Development")
3. Add variable:
   - **Variable:** `base_url`
   - **Value:** `http://localhost:8000`
4. Save dan aktifkan environment tersebut

### Environment untuk Production/Staging
```
Local:     http://localhost:8000
Staging:   https://staging.rikod.com
Production: https://api.rikod.com
```

---

## 📋 API Endpoints dalam Collection

### 1️⃣ Get Company Data
**Method:** POST
**Endpoint:** `/api/companyById`

**Body:**
```json
{
    "id_company": 1,
    "id_user": 1
}
```

**Usage:**
- Load data company saat buka form
- Get current values untuk semua fields

---

### 2️⃣ Update Company Data
**Method:** POST
**Endpoint:** `/api/updateCompany`

**Body:**
```json
{
    "id_user": 1,
    "company_name": "RiiKOD NIAGA",
    "number_lisence": "62519179201",
    "id_category_company": 1,
    "company_telp": "+602817491",
    "company_address": "Jl. Suka Derma Blok B No 32",
    "company_postcode": "15123",
    "id_city": 1,
    "id_state": 1,
    "id_country": 1
}
```

**Usage:**
- Save perubahan form
- Update semua field company

**Note:** Untuk upload file (sign_image, qr_payment), ganti Content-Type ke `multipart/form-data`

---

### 3️⃣ Get Category Company
**Method:** GET
**Endpoint:** `/api/getCategoryCompany`

**Usage:**
- Populate dropdown "Kategori Perniagaan"
- No parameters needed

**Response Example:**
```json
{
  "isSuccess": true,
  "data": [
    {
      "id": 1,
      "category_company_name": "Produk Digital"
    }
  ]
}
```

---

### 4️⃣ Get Country List
**Method:** GET
**Endpoint:** `/api/getCountry`

**Optional Query Params:**
- `id`: Filter by country ID
- `q`: Search by name

**Usage:**
- Populate dropdown "Negara"
- Support search

**Example:**
```
GET /api/getCountry?q=Malaysia
```

---

### 5️⃣ Get State List (Cascading)
**Method:** GET
**Endpoint:** `/api/getState?id_country=1`

**Query Params:**
- `id_country`: **Required** - ID negara yang dipilih
- `q`: Optional - Search by state name

**Usage:**
- Populate dropdown "Negeri"
- Dipanggil setelah user pilih Negara
- Cascading dari dropdown Negara

**Flow:**
```
User pilih Negara (id=1)
→ Call /api/getState?id_country=1
→ Populate dropdown Negeri
```

---

### 6️⃣ Get City List (Cascading)
**Method:** GET
**Endpoint:** `/api/getCity?id_state=1`

**Query Params:**
- `id_state`: **Required** - ID negeri yang dipilih
- `q`: Optional - Search by city name

**Usage:**
- Populate dropdown "Daerah"
- Dipanggil setelah user pilih Negeri
- Cascading dari dropdown Negeri

**Flow:**
```
User pilih Negara (id=1)
→ Load Negeri
→ User pilih Negeri (id=5)
→ Call /api/getCity?id_state=5
→ Populate dropdown Daerah
```

---

## 🔄 Complete Flow untuk Form

### Load Form (Initial)
```
1. POST /api/companyById
   → Get current company data

2. GET /api/getCategoryCompany
   → Load kategori dropdown

3. GET /api/getCountry
   → Load negara dropdown

4. GET /api/getState?id_country=X
   → Load negeri dropdown (X dari data company)

5. GET /api/getCity?id_state=Y
   → Load daerah dropdown (Y dari data company)
```

### User Interaction
```
User change Negara:
→ GET /api/getState?id_country=new_id
→ Reset & populate Negeri dropdown
→ Reset Daerah dropdown

User change Negeri:
→ GET /api/getCity?id_state=new_id
→ Reset & populate Daerah dropdown
```

### Save Form
```
User klik Save:
→ POST /api/updateCompany
   {
     "id_user": X,
     "company_name": "...",
     "id_country": Y,
     "id_state": Z,
     "id_city": W,
     ...
   }
```

---

## 🧪 Testing Guide

### 1. Test Get Company Data
1. Buka request "1. Get Company Data"
2. Update `id_company` dan `id_user` di Body
3. Click **Send**
4. Verify response contains company data

### 2. Test Cascading Dropdowns
**Test Negara → Negeri → Daerah:**

**Step 1:** Get Country
```
GET /api/getCountry
→ Note down id_country (misal: 1 untuk Malaysia)
```

**Step 2:** Get State
```
GET /api/getState?id_country=1
→ Note down id_state (misal: 5 untuk Selangor)
```

**Step 3:** Get City
```
GET /api/getCity?id_state=5
→ Get list cities in Selangor
```

### 3. Test Update Company
1. Buka request "2. Update Company Data"
2. Update semua field di Body sesuai kebutuhan
3. Make sure `id_user` valid
4. Click **Send**
5. Verify response success

### 4. Test Search
**Search Country:**
```
GET /api/getCountry?q=Malay
→ Should return Malaysia
```

**Search State:**
```
GET /api/getState?id_country=1&q=Selan
→ Should return Selangor
```

---

## 🔐 Authentication (Jika ada)

Jika API memerlukan authentication:

### Add Bearer Token
1. Buka Collection settings
2. Tab **Authorization**
3. Type: **Bearer Token**
4. Token: `{{access_token}}`

### Set token di Environment
```
access_token = eyJ0eXAiOiJKV1QiLCJhbGc...
```

### Atau per Request
Setiap request bisa override dengan:
- Tab **Authorization**
- Pilih type
- Input credentials

---

## 📝 Tips & Best Practices

### 1. Gunakan Environment Variables
```
{{base_url}}/api/companyById
{{id_user}}
{{access_token}}
```

### 2. Save Response untuk Testing
Di tab **Tests**, save response:
```javascript
// Save company_id untuk request berikutnya
pm.environment.set("company_id", pm.response.json().data[0].id_company);

// Save country_id untuk cascading
pm.environment.set("country_id", pm.response.json().data[0].id_country);
```

### 3. Pre-request Script
Auto-populate nilai:
```javascript
pm.environment.set("timestamp", new Date().toISOString());
```

### 4. Organize dengan Folders
```
📁 Identiti Perniagaan APIs
  📁 Company Data
    - Get Company Data
    - Update Company Data
  📁 Dropdowns
    - Get Category
    - Get Country
    - Get State
    - Get City
```

---

## 🐛 Troubleshooting

### Error: Connection Refused
- ✅ Check `base_url` sudah benar
- ✅ Pastikan Laravel server running (`php artisan serve`)
- ✅ Check port number (default: 8000)

### Error: 404 Not Found
- ✅ Verify route ada di `routes/api.php`
- ✅ Check endpoint path benar
- ✅ Jalankan `php artisan route:list`

### Error: 422 Validation Error
- ✅ Check required fields semua ada
- ✅ Verify data type (string, number, etc.)
- ✅ Lihat error message di response

### Error: 500 Internal Server Error
- ✅ Check Laravel logs: `storage/logs/laravel.log`
- ✅ Enable debug mode: `APP_DEBUG=true` di `.env`
- ✅ Check database connection

---

## 📊 Example Response Formats

### Success Response
```json
{
  "isSuccess": true,
  "message": "Success message here",
  "data": [...]
}
```

### Error Response
```json
{
  "isSuccess": false,
  "message": "Error message here",
  "errors": {
    "field_name": ["Error detail"]
  }
}
```

---

## 🎯 Quick Start Checklist

- [ ] Import collection ke Postman
- [ ] Set `base_url` environment variable
- [ ] Start Laravel server (`php artisan serve`)
- [ ] Test "Get Country" request (simple test)
- [ ] Test "Get Company Data" dengan valid ID
- [ ] Test cascading: Country → State → City
- [ ] Test "Update Company" dengan valid data
- [ ] Check semua response codes (200 OK)

---

## 📚 Additional Resources

- **Postman Docs:** https://learning.postman.com/
- **Environment Variables:** https://learning.postman.com/docs/sending-requests/variables/
- **Testing Scripts:** https://learning.postman.com/docs/writing-scripts/test-scripts/

---

## 💡 Pro Tips

1. **Create Test Suite**: Gunakan Collection Runner untuk test semua API sekaligus
2. **Monitor API**: Setup Postman Monitor untuk check API health
3. **Generate Code**: Klik "Code" untuk generate code snippet (cURL, JavaScript, etc.)
4. **Share Collection**: Export dan share dengan team
5. **Version Control**: Commit file JSON ke Git repository

---

Selamat testing! 🚀