# Prop360 Integration API - cURL Command Examples

## Authentication

All API requests require an API token in the Authorization header:

```bash
# Replace YOUR_API_TOKEN with the actual token from the root admin interface
export API_TOKEN="prop360_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
export BASE_URL="https://your-domain.com/api/integration"
```

## 1. Get Available Fields

**Endpoint:** `GET /fields`

Returns the list of available fields for the merchant, including user-friendly names and field types.

```bash
curl -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/fields"
```

**Expected Response:**
```json
{
  "success": true,
  "fields": [
    {
      "fieldId": "property_title",
      "userFriendlyName": "Property Title",
      "type": "text",
      "required": true,
      "options": null
    },
    {
      "fieldId": "property_type",
      "userFriendlyName": "Property Type",
      "type": "select",
      "required": true,
      "options": [
        { "label": "Apartment", "value": "apartment" },
        { "label": "House", "value": "house" },
        { "label": "Villa", "value": "villa" }
      ]
    }
  ]
}
```

## 2. List Properties

**Endpoint:** `GET /properties`

Returns a paginated list of properties for the merchant.

### Basic request:
```bash
curl -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/properties"
```

### With pagination:
```bash
curl -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/properties?page=2&limit=5"
```

**Expected Response:**
```json
{
  "success": true,
  "properties": [
    {
      "id": "507f1f77bcf86cd799439011",
      "pid": 1,
      "data": {
        "Property Title": "Beautiful 3-bedroom apartment",
        "Property Type": "apartment",
        "Price": 250000,
        "Bedrooms": 3,
        "Bathrooms": 2
      },
      "isPublic": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "pages": 3
  }
}
```

## 3. Get Specific Property

**Endpoint:** `GET /properties/{id}`

Returns a specific property by ID.

```bash
# Replace PROPERTY_ID with the actual property ID
PROPERTY_ID="507f1f77bcf86cd799439011"

curl -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/properties/$PROPERTY_ID"
```

**Expected Response:**
```json
{
  "success": true,
  "property": {
    "id": "507f1f77bcf86cd799439011",
    "pid": 1,
    "data": {
      "Property Title": "Beautiful 3-bedroom apartment",
      "Property Type": "apartment",
      "Price": 250000,
      "Bedrooms": 3,
      "Bathrooms": 2,
      "Description": "A beautiful apartment in the city center"
    },
    "isPublic": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
```

## 4. Create New Property

**Endpoint:** `POST /properties`

Creates a new property.

### Basic property creation:
```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "Property Title": "New Beautiful Home",
      "Property Type": "house",
      "Price": 350000,
      "Bedrooms": 4,
      "Bathrooms": 3,
      "Description": "A beautiful family home with garden",
      "isPublic": true
    }
  }' \
  "$BASE_URL/properties"
```

### Property with all field types:
```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "Property Title": "Luxury Villa",
      "Property Type": "villa",
      "Price": 750000,
      "Bedrooms": 5,
      "Bathrooms": 4,
      "Square Meters": 250,
      "Year Built": 2020,
      "Parking Spaces": 3,
      "Has Garden": true,
      "Has Pool": true,
      "Furnished": false,
      "Available From": "2024-02-01",
      "Contact Phone": "+30 123 456 7890",
      "Contact Email": "agent@example.com",
      "Description": "A luxurious villa with amazing views",
      "isPublic": false
    }
  }' \
  "$BASE_URL/properties"
```

**Expected Response:**
```json
{
  "success": true,
  "property": {
    "id": "507f1f77bcf86cd799439012",
    "pid": 2,
    "data": {
      "Property Title": "New Beautiful Home",
      "Property Type": "house",
      "Price": 350000,
      "Bedrooms": 4,
      "Bathrooms": 3,
      "Description": "A beautiful family home with garden"
    },
    "isPublic": true,
    "createdAt": "2024-01-15T11:00:00Z",
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}
```

## 5. Update Property

**Endpoint:** `PUT /properties/{id}`

Updates an existing property.

### Update specific fields:
```bash
PROPERTY_ID="507f1f77bcf86cd799439011"

curl -X PUT \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "Property Title": "Updated Property Title",
      "Price": 375000,
      "Description": "Updated description with more details",
      "isPublic": false
    }
  }' \
  "$BASE_URL/properties/$PROPERTY_ID"
```

### Update only visibility:
```bash
curl -X PUT \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "isPublic": true
    }
  }' \
  "$BASE_URL/properties/$PROPERTY_ID"
```

### Update only data (keep existing visibility):
```bash
curl -X PUT \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "Price": 400000,
      "Bedrooms": 5,
      "Has Garden": true
    }
  }' \
  "$BASE_URL/properties/$PROPERTY_ID"
```

**Expected Response:**
```json
{
  "success": true,
  "property": {
    "id": "507f1f77bcf86cd799439011",
    "pid": 1,
    "data": {
      "Property Title": "Updated Property Title",
      "Property Type": "apartment",
      "Price": 375000,
      "Bedrooms": 3,
      "Bathrooms": 2,
      "Description": "Updated description with more details"
    },
    "isPublic": false,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T11:30:00Z"
  }
}
```

## 6. Delete Property

**Endpoint:** `DELETE /properties/{id}`

Deletes a property (soft delete).

```bash
PROPERTY_ID="507f1f77bcf86cd799439011"

curl -X DELETE \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/properties/$PROPERTY_ID"
```

**Expected Response:**
```json
{
  "success": true,
  "message": "Property deleted successfully"
}
```

## 7. Upload Images to Property

**Endpoint:** `POST /properties/{id}/images`

Uploads images to a property.

### Upload single image:
```bash
PROPERTY_ID="507f1f77bcf86cd799439011"

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "images=@/path/to/property1.jpg" \
  "$BASE_URL/properties/$PROPERTY_ID/images"
```

### Upload multiple images:
```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "images=@/path/to/property1.jpg" \
  -F "images=@/path/to/property2.jpg" \
  -F "images=@/path/to/property3.jpg" \
  "$BASE_URL/properties/$PROPERTY_ID/images"
```

### Upload with different image formats:
```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "images=@/path/to/property1.jpg" \
  -F "images=@/path/to/property2.png" \
  -F "images=@/path/to/property3.webp" \
  "$BASE_URL/properties/$PROPERTY_ID/images"
```

**Expected Response:**
```json
{
  "success": true,
  "message": "3 images uploaded successfully",
  "images": [
    {
      "originalName": "property1.jpg",
      "fileName": "property-507f1f77bcf86cd799439011-1705312800000-abc123.jpg",
      "fileType": "image/jpeg",
      "fileSize": 2048576,
      "url": "https://your-storage-domain.com/uploads/property-507f1f77bcf86cd799439011-1705312800000-abc123.jpg",
      "key": "uploads/property-507f1f77bcf86cd799439011-1705312800000-abc123.jpg"
    },
    {
      "originalName": "property2.png",
      "fileName": "property-507f1f77bcf86cd799439011-1705312800001-def456.png",
      "fileType": "image/png",
      "fileSize": 1536000,
      "url": "https://your-storage-domain.com/uploads/property-507f1f77bcf86cd799439011-1705312800001-def456.png",
      "key": "uploads/property-507f1f77bcf86cd799439011-1705312800001-def456.png"
    }
  ],
  "totalImages": 5
}
```

## Complete Workflow Example

Here's a complete workflow example that demonstrates the typical usage pattern:

```bash
#!/bin/bash

# Set up environment
export API_TOKEN="prop360_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
export BASE_URL="https://your-domain.com/api/integration"

echo "=== Prop360 Integration API Workflow Example ==="

# 1. Get available fields
echo "1. Getting available fields..."
curl -s -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/fields" | jq '.'

# 2. Create a new property
echo -e "\n2. Creating a new property..."
PROPERTY_RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "Property Title": "Beautiful Family Home",
      "Property Type": "house",
      "Price": 450000,
      "Bedrooms": 4,
      "Bathrooms": 3,
      "Description": "A beautiful family home with garden",
      "isPublic": true
    }
  }' \
  "$BASE_URL/properties")

echo "$PROPERTY_RESPONSE" | jq '.'

# Extract property ID from response
PROPERTY_ID=$(echo "$PROPERTY_RESPONSE" | jq -r '.property.id')

# 3. Get the created property
echo -e "\n3. Getting the created property..."
curl -s -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/properties/$PROPERTY_ID" | jq '.'

# 4. Update the property
echo -e "\n4. Updating the property..."
curl -s -X PUT \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "Price": 475000,
      "Description": "Updated description with more details"
    }
  }' \
  "$BASE_URL/properties/$PROPERTY_ID" | jq '.'

# 5. Upload images (if you have image files)
echo -e "\n5. Uploading images..."
if [ -f "/path/to/property1.jpg" ]; then
  curl -s -X POST \
    -H "Authorization: Bearer $API_TOKEN" \
    -F "images=@/path/to/property1.jpg" \
    "$BASE_URL/properties/$PROPERTY_ID/images" | jq '.'
else
  echo "No image files found for upload"
fi

# 6. List all properties
echo -e "\n6. Listing all properties..."
curl -s -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/properties" | jq '.'

# 7. Delete the property (uncomment to test)
# echo -e "\n7. Deleting the property..."
# curl -s -X DELETE \
#   -H "Authorization: Bearer $API_TOKEN" \
#   -H "Content-Type: application/json" \
#   "$BASE_URL/properties/$PROPERTY_ID" | jq '.'

echo -e "\n=== Workflow completed ==="
```

## Error Handling Examples

### Invalid token:
```bash
curl -X GET \
  -H "Authorization: Bearer invalid_token" \
  -H "Content-Type: application/json" \
  "$BASE_URL/properties"
```

**Response:**
```json
{
  "error": "Invalid or inactive token"
}
```

### Missing required fields:
```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "Property Type": "house"
    }
  }' \
  "$BASE_URL/properties"
```

**Response:**
```json
{
  "error": "Property data is required"
}
```

### Property not found:
```bash
curl -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/properties/nonexistent_id"
```

**Response:**
```json
{
  "error": "Property not found"
}
```

### Invalid file type for upload:
```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "images=@/path/to/document.pdf" \
  "$BASE_URL/properties/$PROPERTY_ID/images"
```

**Response:**
```json
{
  "error": "Invalid file type: application/pdf. Allowed types: image/jpeg, image/jpg, image/png, image/webp"
}
```

## Testing Script

Here's a complete testing script that validates all endpoints:

```bash
#!/bin/bash

# Prop360 Integration API Testing Script

# Configuration
export API_TOKEN="your_api_token_here"
export BASE_URL="https://your-domain.com/api/integration"
export TEST_PROPERTY_ID=""

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Test function
test_endpoint() {
    local name="$1"
    local method="$2"
    local url="$3"
    local data="$4"
    
    echo -e "${YELLOW}Testing: $name${NC}"
    
    if [ -n "$data" ]; then
        response=$(curl -s -X "$method" \
            -H "Authorization: Bearer $API_TOKEN" \
            -H "Content-Type: application/json" \
            -d "$data" \
            "$BASE_URL$url")
    else
        response=$(curl -s -X "$method" \
            -H "Authorization: Bearer $API_TOKEN" \
            -H "Content-Type: application/json" \
            "$BASE_URL$url")
    fi
    
    if echo "$response" | jq -e '.success' > /dev/null 2>&1; then
        echo -e "${GREEN}✓ Success${NC}"
        echo "$response" | jq '.'
    else
        echo -e "${RED}✗ Failed${NC}"
        echo "$response" | jq '.'
    fi
    echo ""
}

# Run tests
echo "=== Prop360 Integration API Tests ==="

# Test 1: Get fields
test_endpoint "Get Available Fields" "GET" "/fields"

# Test 2: Create property
test_endpoint "Create Property" "POST" "/properties" '{
    "data": {
        "Property Title": "Test Property",
        "Property Type": "apartment",
        "Price": 250000,
        "Bedrooms": 2,
        "Bathrooms": 1
        "isPublic": true
    }
}'

# Extract property ID for subsequent tests
PROPERTY_RESPONSE=$(curl -s -X POST \
    -H "Authorization: Bearer $API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "data": {
            "Property Title": "Test Property for ID",
            "Property Type": "house",
            "Price": 300000
            "isPublic": true
        }
    }' \
    "$BASE_URL/properties")

TEST_PROPERTY_ID=$(echo "$PROPERTY_RESPONSE" | jq -r '.property.id')

if [ "$TEST_PROPERTY_ID" != "null" ] && [ "$TEST_PROPERTY_ID" != "" ]; then
    echo "Created test property with ID: $TEST_PROPERTY_ID"
    
    # Test 3: Get property
    test_endpoint "Get Property" "GET" "/properties/$TEST_PROPERTY_ID"
    
    # Test 4: Update property
    test_endpoint "Update Property" "PUT" "/properties/$TEST_PROPERTY_ID" '{
        "data": {
            "Price": 325000,
            "Description": "Updated test property"
        }
    }'
    
    # Test 5: List properties
    test_endpoint "List Properties" "GET" "/properties"
    
    # Test 6: Delete property
    test_endpoint "Delete Property" "DELETE" "/properties/$TEST_PROPERTY_ID"
    
else
    echo -e "${RED}Failed to create test property${NC}"
fi

echo "=== Tests completed ==="
```

## Notes

1. **Replace placeholders**: Update `YOUR_API_TOKEN` and `your-domain.com` with actual values
2. **Install jq**: The examples use `jq` for JSON formatting. Install it with `brew install jq` (macOS) or `apt-get install jq` (Ubuntu)
3. **File paths**: Update image file paths in upload examples
4. **Error handling**: Always check response status and handle errors appropriately
5. **Rate limiting**: Be mindful of API rate limits in production use
6. **Security**: Never commit API tokens to version control

## Common Issues and Solutions

### SSL Certificate Issues
```bash
# Skip SSL verification (not recommended for production)
curl -k -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  "$BASE_URL/properties"
```

### Timeout Issues
```bash
# Set timeout for long operations
curl --max-time 30 -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "images=@large_image.jpg" \
  "$BASE_URL/properties/$PROPERTY_ID/images"
```

### Verbose Output
```bash
# Get detailed request/response information
curl -v -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  "$BASE_URL/properties"
```