# Merchant BO – API Documentation (cURL & Postman)

**Controller:** `App\Http\Controllers\MerchantBOController`  
**Base URL:** `{{BASE_URL}}/api`  

**Replace in examples:**
- `{{BASE_URL}}` → e.g. `http://localhost` or `https://your-domain.com`
- `{{JWT_TOKEN}}` → token from `auth/login` or `auth/refresh` (when JWT middleware is enabled)

**Route names (as in `routes/api.php`):**

| Action | Method | Route name | Endpoint |
|--------|--------|------------|----------|
| Create mother BO | `POST` | `create-merchant-mother-bo` | `merchant-bo/create-mother-bo` |
| Create merchant BO | `POST` | `create-merchant-bo` | `merchant-bo/create-merchant-bo` |
| Bulk create merchant BO (CSV) | `POST` | `create-merchant-bo-csv` | `merchant-bo/create-merchant-bo-csv` |

> Keep this file in sync whenever a new method is added to `MerchantBOController`.

**Notes:**
- Child `mother_bo_id` in request/CSV = **business** mother BO ID (`merchant_mother_bo.mother_bo_id`), not the table PK.
- `merchant_bo_type` / CSV `bo_type`: accept `cash` or `loan` → stored as **`C`** or **`L`**.

---

## 1. Create mother BO – `createMotherBo`

Create a merchant mother BO from scratch.  
**Single contact person only** (`contact_person_name`). Do **not** send `contactPersons` / `contact_persons` arrays.  
Bank and address fields are stored on the same `merchant_mother_bo` row.

| Item       | Value |
|------------|--------|
| **Method** | `POST` |
| **URL**    | `{{BASE_URL}}/api/merchant-bo/create-mother-bo` |
| **Auth**   | Currently `api` middleware (see `routes/api.php`) |

### Body (form-data)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `users_id` | int | Yes | Logged-in back-office user ID (`created_by` / `updated_by`) |
| `mother_bo_id` | int | Yes | Business mother BO ID (unique) |
| `account_status` | string | Yes | `C` = Cash, `M` = Margin |
| `account_name` | string | Yes | Max 130 |
| `contact_person_name` | string | Yes | Max 130 — **one person only** |
| `email` | string | No | Max 100 |
| `phone_no` | string | No | Max 20 |
| `account_no` | string | No | Bank account number, max 40 |
| `route_no` | string | No | Routing number, max 30 |
| `branch` | string | No | Max 100 |
| `bank_name` | string | No | Max 100 |
| `bank_branch` | string | No | Max 100 |
| `street` | string | No | Max 255 |
| `city` | string | No | Max 64 |
| `postal_code` | string | No | Max 20 |
| `country` | string | No | Max 64 |
| `activity_flag` | string | No | `I` / `P` / `A`; default `P` (Pending) |

### cURL

```bash
curl --location 'http://localhost/api/merchant-bo/create-mother-bo' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{JWT_TOKEN}}' \
--form 'users_id="1"' \
--form 'mother_bo_id="1200000000000001"' \
--form 'account_status="C"' \
--form 'account_name="Acme Merchant"' \
--form 'contact_person_name="John Doe"' \
--form 'email="john@acme.com"' \
--form 'phone_no="01700000000"' \
--form 'account_no="1234567890"' \
--form 'route_no="123456789"' \
--form 'branch="Gulshan"' \
--form 'bank_name="Example Bank"' \
--form 'bank_branch="Gulshan Branch"' \
--form 'street="Road 12"' \
--form 'city="Dhaka"' \
--form 'postal_code="1212"' \
--form 'country="Bangladesh"' \
--form 'activity_flag="P"'
```

### Postman setup

1. **Method:** POST  
2. **URL:** `http://localhost/api/merchant-bo/create-mother-bo`  
3. **Headers:** `Accept: application/json`, `Authorization: Bearer {{JWT_TOKEN}}`  
4. **Body:** form-data — add each field above as **Text**

### Success response (201)

```json
{
  "success": true,
  "message": "Merchant mother BO created successfully",
  "data": { "id": 1, "mother_bo_id": 1200000000000001, "...": "..." }
}
```

---

## 2. Create merchant BO – `createMerchantBo`

Create one merchant BO under an existing mother BO.

| Item       | Value |
|------------|--------|
| **Method** | `POST` |
| **URL**    | `{{BASE_URL}}/api/merchant-bo/create-merchant-bo` |
| **Auth**   | Currently `api` middleware (see `routes/api.php`) |

### Body (JSON)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `users_id` | int | Yes | Logged-in back-office user ID |
| `mother_bo_id` | int | Yes | Business mother BO ID (`merchant_mother_bo.mother_bo_id`) |
| `merchant_client_code` | string | Yes | Max 50 |
| `merchant_bo_id` | int | Yes | Merchant BO ID |
| `merchant_bo_name` | string | Yes | Max 130 |
| `merchant_bo_type` | string | Yes | `cash` / `loan` (or `C` / `L`) → stored as `C` / `L` |

### cURL

```bash
curl --location 'http://localhost/api/merchant-bo/create-merchant-bo' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{JWT_TOKEN}}' \
--data '{
  "users_id": 1,
  "mother_bo_id": 1200000000000001,
  "merchant_client_code": "MCL001",
  "merchant_bo_id": 1300000000000001,
  "merchant_bo_name": "Acme Cash BO",
  "merchant_bo_type": "cash"
}'
```

Loan example (`merchant_bo_type`: `"loan"` → stored as `"L"`):

```bash
curl --location 'http://localhost/api/merchant-bo/create-merchant-bo' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{JWT_TOKEN}}' \
--data '{
  "users_id": 1,
  "mother_bo_id": 1200000000000001,
  "merchant_client_code": "MCL002",
  "merchant_bo_id": 1300000000000002,
  "merchant_bo_name": "Acme Loan BO",
  "merchant_bo_type": "loan"
}'
```

### Success response (201)

```json
{
  "success": true,
  "message": "Merchant BO created successfully",
  "data": {
    "id": 1,
    "mother_bo_id": 1,
    "merchant_client_code": "MCL001",
    "merchant_bo_id": 1300000000000001,
    "merchant_bo_name": "Acme Cash BO",
    "merchant_bo_type": "C",
    "created_by": 1,
    "updated_by": 1,
    "created_at": "2026-07-12T09:00:00.000000Z",
    "updated_at": "2026-07-12T09:00:00.000000Z"
  }
}
```

### Validation error (422)

```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "mother_bo_id": ["The selected mother bo id is invalid."]
  }
}
```

---

## 3. Bulk create merchant BO (CSV) – `createMerchantBoFromCsv`

Upload a CSV to create many merchant BOs under mother BOs.

| Item       | Value |
|------------|--------|
| **Method** | `POST` |
| **URL**    | `{{BASE_URL}}/api/merchant-bo/create-merchant-bo-csv` |
| **Auth**   | Currently `api` middleware (see `routes/api.php`) |
| **Body**   | `multipart/form-data` |

### Form fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `users_id` | int | Yes | Logged-in back-office user ID |
| `csv_file` | file | Yes | CSV/TXT, max 10MB |

### CSV columns (header row required)

| Column | Required | Description |
|--------|----------|-------------|
| `mother_bo_id` | Yes | Business mother BO ID |
| `client_code` | Yes | → `merchant_client_code` |
| `bo_id` | Yes | → `merchant_bo_id` |
| `name` | Yes | → `merchant_bo_name` |
| `bo_type` | Yes | `cash` or `loan` → stored as `C` or `L` |

**Sample CSV:**

```csv
mother_bo_id,client_code,bo_id,name,bo_type
1200000000000001,MCL001,1300000000000001,Acme Cash BO,cash
1200000000000001,MCL002,1300000000000002,Acme Loan BO,loan
```

**Import behaviour:**
- Unknown `mother_bo_id` → row marked invalid (not inserted)
- Invalid / missing fields → row marked invalid
- Duplicate (`same mother PK + merchant_bo_id`) → skipped
- Valid rows inserted in one DB transaction

### cURL

```bash
curl --location 'http://localhost/api/merchant-bo/create-merchant-bo-csv' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{JWT_TOKEN}}' \
--form 'users_id="1"' \
--form 'csv_file=@"/path/to/merchant_bo.csv"'
```

### Postman setup

1. **Method:** POST  
2. **URL:** `http://localhost/api/merchant-bo/create-merchant-bo-csv`  
3. **Body:** form-data  
   - `users_id` → Text → `1`  
   - `csv_file` → File → select CSV  

### Success response (201)

```json
{
  "success": true,
  "message": "Merchant BO CSV import completed",
  "data": {
    "inserted": 2,
    "skipped_duplicate": 0,
    "invalid_rows": [],
    "invalid_count": 0
  }
}
```

### Partial success example (invalid / missing mother)

```json
{
  "success": true,
  "message": "Merchant BO CSV import completed",
  "data": {
    "inserted": 1,
    "skipped_duplicate": 1,
    "invalid_rows": [
      {
        "row": 3,
        "reason": "mother_bo_id 999 not found",
        "data": ["999", "MCL003", "1300000000000003", "Missing Mother", "cash"]
      }
    ],
    "invalid_count": 1
  }
}
```

### Missing columns (422)

```json
{
  "success": false,
  "message": "CSV is missing required columns: bo_type",
  "required_columns": ["mother_bo_id", "client_code", "bo_id", "name", "bo_type"]
}
```

---

## Changelog

| Date | Change |
|------|--------|
| 2026-07-12 | Added `createMotherBo` |
| 2026-07-12 | Added `createMerchantBo` and `createMerchantBoFromCsv`; `bo_type` cash/loan → C/L |