# Vendor Profile Update API Documentation

## Endpoint
**PATCH** `/api/dashboard/admin/vendors/{vendor}/profile`

## Description
Flexible vendor profile update endpoint that only updates the fields that are sent in the request. You can update any combination of:
- Logo and commercial register file
- Merchant basic info (commercial_register_number, stock_alert_threshold, iban)
- Translations (ar, en)
- Location data
- Categories
- Delivery settings

## Request Example

```json
{
  "logo": "d3082cdc-9e8b-49d5-828b-61163d2abe63",
  "commercial_register_number": "1010897654",
  "commercial_register_file": "142bbd15-6082-41ae-aba3-c9d31424af74",
  "stock_alert_threshold": 5,
  "expiry_alert_before_days": 30,
  "ar": {
    "name": "متجر السعيد",
    "description": "متجر متخصص في بيع المنتجات الإلكترونية والإكسسوارات"
  },
  "en": {
    "name": "Saed Store",
    "description": "A store specialized in selling electronics and accessories"
  },
  "location": {
    "city_id": 1,
    "lat": "24.713552",
    "lng": "46.675296",
    "name": "Main Branch",
    "property_number": "Building 25",
    "details": "King Fahd Road, Al Olaya District",
    "url": "https://maps.google.com/?q=24.713552,46.675296"
  },
  "category_ids": [1, 10],
  "delivery_type": "merchant",
  "delivery_cities": [
    {
      "country_id": 1,
      "city_id": 5,
      "delivery_price": 25.50
    }
  ]
}
```

## Field Descriptions

### Media Files
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `logo` | string (UUID) | No | Logo image UUID from media upload |
| `commercial_register_file` | string (UUID) | No | Commercial register file UUID from media upload |

**Note:** Only send these fields if you want to update them. If not sent, existing values remain unchanged.

### Merchant Basic Info
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `commercial_register_number` | string | No | Commercial registration number |
| `stock_alert_threshold` | integer | No | Minimum stock level for alerts (min: 0) |
| `expiry_alert_before_days` | integer | No | Days before expiry to send alert (min: 1) |
| `iban` | string | No | Bank account IBAN |

### Translations
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ar.name` | string | No | Arabic merchant name |
| `ar.description` | string | No | Arabic merchant description |
| `en.name` | string | No | English merchant name |
| `en.description` | string | No | English merchant description |

**Note:** You can send only `ar`, only `en`, or both. Within each language, you can send only `name`, only `description`, or both.

### Location
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `location.city_id` | integer | Yes (if location sent) | City ID (required when sending location) |
| `location.lat` | numeric | No | Latitude (-90 to 90) |
| `location.lng` | numeric | No | Longitude (-180 to 180) |
| `location.name` | string | No | Location name/label |
| `location.property_number` | string | No | Building/property number |
| `location.details` | string | No | Detailed address |
| `location.url` | string (URL) | No | Google Maps or location URL |

**Note:** Only send the `location` object if you want to update location. If not sent, existing location remains unchanged.

### Categories
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_ids` | array | No | Array of category IDs (min: 1 item) |

**Note:** 
- Only send if you want to update categories
- Vendor must have `can_change_categories` permission
- Will return 403 error if vendor cannot change categories

### Delivery Settings
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `delivery_type` | string | No | "merchant" or "platform" |
| `delivery_cities` | array | No | Array of delivery city objects |
| `delivery_cities.*.country_id` | integer | Yes (if delivery_cities sent) | Country ID |
| `delivery_cities.*.city_id` | integer | Yes (if delivery_cities sent) | City ID |
| `delivery_cities.*.delivery_price` | numeric | Yes (if delivery_cities sent) | Delivery price (min: 0) |

## Update Scenarios

### Scenario 1: Update Only Logo and Commercial Register
```json
{
  "logo": "d3082cdc-9e8b-49d5-828b-61163d2abe63",
  "commercial_register_number": "1010897654",
  "commercial_register_file": "142bbd15-6082-41ae-aba3-c9d31424af74"
}
```

### Scenario 2: Update Only Translations
```json
{
  "ar": {
    "name": "متجر السعيد",
    "description": "متجر متخصص في بيع المنتجات الإلكترونية"
  },
  "en": {
    "name": "Saed Store",
    "description": "A store specialized in selling electronics"
  }
}
```

### Scenario 3: Update Only Location
```json
{
  "location": {
    "city_id": 1,
    "lat": "24.713552",
    "lng": "46.675296",
    "name": "Main Branch",
    "property_number": "Building 25",
    "details": "King Fahd Road, Al Olaya District"
  }
}
```

### Scenario 4: Update Only Categories
```json
{
  "category_ids": [1, 10, 15]
}
```

### Scenario 5: Update Only Stock Alert Settings
```json
{
  "stock_alert_threshold": 10,
  "expiry_alert_before_days": 30
}
```

### Scenario 6: Update Everything
```json
{
  "logo": "d3082cdc-9e8b-49d5-828b-61163d2abe63",
  "commercial_register_number": "1010897654",
  "commercial_register_file": "142bbd15-6082-41ae-aba3-c9d31424af74",
  "stock_alert_threshold": 5,
  "expiry_alert_before_days": 30,
  "iban": "SA1234567890123456789012",
  "ar": {
    "name": "متجر السعيد",
    "description": "متجر متخصص في بيع المنتجات الإلكترونية"
  },
  "en": {
    "name": "Saed Store",
    "description": "A store specialized in selling electronics"
  },
  "location": {
    "city_id": 1,
    "lat": "24.713552",
    "lng": "46.675296",
    "name": "Main Branch",
    "property_number": "Building 25",
    "details": "King Fahd Road, Al Olaya District",
    "url": "https://maps.google.com/?q=24.713552,46.675296"
  },
  "category_ids": [1, 10],
  "delivery_type": "merchant",
  "delivery_cities": [
    {
      "country_id": 1,
      "city_id": 5,
      "delivery_price": 25.50
    },
    {
      "country_id": 1,
      "city_id": 10,
      "delivery_price": 30.00
    }
  ]
}
```

## Success Response

```json
{
  "status": "success",
  "message": "Vendor profile updated successfully",
  "data": {
    "id": 123,
    "name": "Vendor User Name",
    "email": "vendor@example.com",
    "merchant": {
      "id": 45,
      "commercial_register_number": "1010897654",
      "iban": "SA1234567890123456789012",
      "stock_alert_threshold": 5,
      "expiry_alert_before_days": 30,
      "delivery_type": "merchant",
      "logo": "https://cdn.example.com/logos/d3082cdc-9e8b-49d5-828b-61163d2abe63.jpg",
      "commercial_register_file": "https://cdn.example.com/files/142bbd15-6082-41ae-aba3-c9d31424af74.pdf",
      "translations": {
        "ar": {
          "name": "متجر السعيد",
          "description": "متجر متخصص في بيع المنتجات الإلكترونية"
        },
        "en": {
          "name": "Saed Store",
          "description": "A store specialized in selling electronics"
        }
      },
      "categories": [
        {
          "id": 1,
          "name": "Electronics"
        },
        {
          "id": 10,
          "name": "Accessories"
        }
      ],
      "delivery_cities": [
        {
          "id": 1,
          "country_id": 1,
          "city_id": 5,
          "delivery_price": "25.50",
          "city": {
            "id": 5,
            "name": "Riyadh"
          }
        }
      ]
    },
    "locations": [
      {
        "id": 1,
        "city_id": 1,
        "lat": "24.713552",
        "lng": "46.675296",
        "name": "Main Branch",
        "property_number": "Building 25",
        "details": "King Fahd Road, Al Olaya District",
        "url": "https://maps.google.com/?q=24.713552,46.675296"
      }
    ],
    "specialties": [
      {
        "id": 1,
        "name": "Electronics"
      },
      {
        "id": 10,
        "name": "Accessories"
      }
    ]
  }
}
```

## Error Responses

### 404 - Merchant Not Found
```json
{
  "status": "fail",
  "message": "Vendor merchant data not found",
  "data": []
}
```

### 403 - Cannot Change Categories
```json
{
  "status": "error",
  "message": "Vendor cannot change main categories",
  "data": []
}
```

### 400 - Update Failed
```json
{
  "status": "error",
  "message": "Failed to update vendor profile: [error details]",
  "data": []
}
```

### 422 - Validation Error
```json
{
  "status": "fail",
  "message": "The given data was invalid",
  "errors": {
    "category_ids": ["At least one category must be selected"],
    "location.city_id": ["City is required when providing location"],
    "stock_alert_threshold": ["The stock alert threshold must be at least 0"]
  }
}
```

## Important Notes

1. **Partial Updates**: This endpoint supports partial updates. Only send the fields you want to change.

2. **Null Values**: Don't send fields with `null` values if you don't want to update them. Simply omit the field from the request.

3. **Media Files**: The `logo` and `commercial_register_file` fields expect UUIDs from a previous media upload endpoint.

4. **Location**: When sending location data, `city_id` is required. All other location fields are optional.

5. **Categories**: Updating categories requires the vendor to have `can_change_categories` permission set to `true`.

6. **Translations**: You can update one language without affecting the other. You can also update just the name or just the description within a language.

7. **Delivery Cities**: When updating delivery cities, the entire array is replaced (not merged). Send all cities you want to keep.

8. **Transaction Safety**: All updates are wrapped in a database transaction. If any part fails, all changes are rolled back.

## cURL Example

```bash
curl -X PATCH \
  https://api.example.com/api/dashboard/admin/vendors/123/profile \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "logo": "d3082cdc-9e8b-49d5-828b-61163d2abe63",
    "commercial_register_number": "1010897654",
    "stock_alert_threshold": 5,
    "ar": {
      "name": "متجر السعيد",
      "description": "متجر متخصص في بيع المنتجات الإلكترونية"
    },
    "en": {
      "name": "Saed Store",
      "description": "A store specialized in selling electronics"
    }
  }'
```

## Route Name
`vendors.update-profile`

## Middleware
- `auth:api` - Requires authentication
- `admin` - Requires admin privileges