docs/api-guides/MERCHANT_API_EXAMPLES.md

# Merchant API - cURL Examples

## Base URL
```bash
BASE_URL="http://localhost:8001/api/v1"
```

## 1. Create Merchant (Draft)

```bash
curl -X POST "$BASE_URL/merchants" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_type": "retail",
    "parent_merchant_id": "mch_parent_001",
    "merchant_code": "retail-MUM-001",
    "merchant_name": "Glamour retail Mumbai",
    "contact": {
      "phone": "+919876543210",
      "email": "contact@glamourretail.com",
      "address_line1": "123 Main Street",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pincode": "400001",
      "country": "India"
    },
    "geo_location": {
      "lat": 19.0760,
      "lng": 72.8777
    },
    "status": "draft",
    "created_by": "admin_001"
  }'
```

## 2. View Merchant

```bash
curl -X GET "$BASE_URL/merchants/{merchant_id}"
```

## 3. Update Merchant

```bash
curl -X PUT "$BASE_URL/merchants/{merchant_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_name": "Updated retail Name",
    "status": "draft"
  }'
```

## 4. List Merchants (with projection)

```bash
curl -X POST "$BASE_URL/merchants/list" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_type": "retail",
    "status": "active",
    "skip": 0,
    "limit": 100,
    "projection_list": ["merchant_id", "merchant_name", "merchant_type", "status"]
  }'
```

## 5. Upload KYC

```bash
curl -X POST "$BASE_URL/merchants/{merchant_id}/kyc" \
  -H "Content-Type: application/json" \
  -d '{
    "pan_number": "AAPFU0939F",
    "business_certificate_url": "https://storage.example.com/cert123.pdf"
  }'
```

## 6. Update KYC

```bash
curl -X PUT "$BASE_URL/merchants/{merchant_id}/kyc" \
  -H "Content-Type: application/json" \
  -d '{
    "gst_number": "27AAPFU0939F1ZV",
    "bank_account_number": "1234567890123",
    "bank_ifsc": "HDFC0001234",
    "cancelled_cheque_url": "https://storage.example.com/cheque123.jpg"
  }'
```

## 7. Submit for Verification

```bash
curl -X POST "$BASE_URL/merchants/{merchant_id}/submit"
```

## 8. Approve Merchant

```bash
curl -X POST "$BASE_URL/merchants/{merchant_id}/approve" \
  -H "Content-Type: application/json" \
  -d '{
    "approved_by": "admin_001",
    "reason": "All documents verified successfully"
  }'
```

## 9. Reject Merchant

```bash
curl -X POST "$BASE_URL/merchants/{merchant_id}/reject" \
  -H "Content-Type: application/json" \
  -d '{
    "rejected_by": "admin_001",
    "reason": "Incomplete documentation"
  }'
```

## 10. Bulk Upload Merchants

```bash
curl -X POST "$BASE_URL/merchants/bulk-upload" \
  -H "Content-Type: application/json" \
  -d '{
    "merchants": [
      {
        "merchant_type": "retail",
        "parent_merchant_id": "mch_parent_001",
        "merchant_code": "retail-MUM-001",
        "merchant_name": "retail 1",
        "contact": {
          "phone": "+919876543210",
          "email": "retail1@example.com",
          "address_line1": "123 Street",
          "city": "Mumbai",
          "state": "Maharashtra",
          "pincode": "400001",
          "country": "India"
        },
        "geo_location": {
          "lat": 19.0760,
          "lng": 72.8777
        },
        "kyc": {
          "pan_number": "AAPFU0939F"
        },
        "created_by": "admin_001"
      },
      {
        "merchant_type": "retail",
        "parent_merchant_id": "mch_parent_001",
        "merchant_code": "retail-MUM-002",
        "merchant_name": "retail 2",
        "contact": {
          "phone": "+919876543211",
          "email": "retail2@example.com",
          "address_line1": "456 Street",
          "city": "Mumbai",
          "state": "Maharashtra",
          "pincode": "400001",
          "country": "India"
        },
        "geo_location": {
          "lat": 19.0760,
          "lng": 72.8777
        },
        "kyc": {
          "pan_number": "BBBFU0939F"
        },
        "created_by": "admin_001"
      }
    ],
    "skip_errors": true
  }'
```

## 11. Get Merchant Children

```bash
curl -X GET "$BASE_URL/merchants/{merchant_id}/children?status=active&skip=0&limit=100"
```

## 12. Get Merchant Hierarchy

```bash
curl -X GET "$BASE_URL/merchants/{merchant_id}/hierarchy"
```

## 13. Delete Merchant (Soft Delete)

```bash
curl -X DELETE "$BASE_URL/merchants/{merchant_id}"
```

## Complete Workflow Example

```bash
# Step 1: Create merchant
MERCHANT_ID=$(curl -s -X POST "$BASE_URL/merchants" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_type": "retail",
    "parent_merchant_id": "mch_parent_001",
    "merchant_code": "WORKFLOW-TEST-001",
    "merchant_name": "Workflow Test retail",
    "contact": {
      "phone": "+919876543210",
      "email": "workflow@test.com",
      "address_line1": "123 Test Street",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pincode": "400001",
      "country": "India"
    },
    "geo_location": {
      "lat": 19.0760,
      "lng": 72.8777
    },
    "status": "draft",
    "created_by": "admin_001"
  }' | jq -r '.merchant_id')

echo "Created merchant: $MERCHANT_ID"

# Step 2: Upload KYC
curl -s -X POST "$BASE_URL/merchants/$MERCHANT_ID/kyc" \
  -H "Content-Type: application/json" \
  -d '{
    "pan_number": "AAPFU0939F"
  }' | jq '.kyc'

# Step 3: Submit for verification
curl -s -X POST "$BASE_URL/merchants/$MERCHANT_ID/submit" | jq '.status'

# Step 4: Approve
curl -s -X POST "$BASE_URL/merchants/$MERCHANT_ID/approve" \
  -H "Content-Type: application/json" \
  -d '{
    "approved_by": "admin_001",
    "reason": "Verified successfully"
  }' | jq '{merchant_id, status, metadata}'
```

## Using jq for Pretty Output

All examples can be piped through `jq` for formatted JSON output:

```bash
curl -X GET "$BASE_URL/merchants/{merchant_id}" | jq '.'
```

## Error Handling Examples

### Missing Required KYC
```bash
# This will fail if PAN is not provided for retail
curl -X POST "$BASE_URL/merchants/{merchant_id}/submit"
# Response: {"detail": "Missing required KYC field for retail: pan_number"}
```

### Invalid Status Transition
```bash
# This will fail if merchant is not in submitted status
curl -X POST "$BASE_URL/merchants/{merchant_id}/approve"
# Response: {"detail": "Can only approve merchants in submitted status. Current status: draft"}
```

### Duplicate Merchant Code
```bash
# This will fail if merchant_code already exists
curl -X POST "$BASE_URL/merchants" -d '{"merchant_code": "EXISTING-CODE", ...}'
# Response: {"detail": "merchant_code already exists within the parent scope"}
```