# Vendor Update Endpoints Documentation

## Overview
Two new endpoints have been added to the Admin API for updating vendor information separately:

1. **Update Basic Info** - Updates user table data (name, email, phone, etc.)
2. **Update Merchant Data** - Updates merchant-specific data (location, delivery settings)

---

## 1. Update Vendor Basic Information

**Endpoint:** `PATCH /api/dashboard/admin/vendors/{vendor}/basic-info`

**Purpose:** Update vendor's basic user information and merchant profile details.

### Request Body

```json
{
  "name": "Vendor Name",
  "email": "vendor@example.com",
  "phone": "1234567890",
  "phone_code": "+966",
  "username": "vendor_username",
  "password": "newpassword123",
  "is_active": true,
  "is_banned": false,
  "commercial_register": "CR123456",
  "bank_account": "SA1234567890",
  "ar": {
    "name": "اسم التاجر",
    "description": "وصف التاجر"
  },
  "en": {
    "name": "Merchant Name",
    "description": "Merchant Description"
  }
}
```

### Validation Rules

| Field | Type | Rules |
|-------|------|-------|
| `name` | string | optional, max:255 |
| `email` | string | optional, email, unique (except current vendor) |
| `phone` | string | optional, unique (except current vendor) |
| `phone_code` | string | optional |
| `username` | string | optional, unique (except current vendor) |
| `password` | string | optional, min:8 |
| `is_active` | boolean | optional |
| `is_banned` | boolean | optional |
| `commercial_register` | string | optional, max:255 |
| `bank_account` | string | optional, max:255 |
| `ar.name` | string | optional, max:255 |
| `ar.description` | string | optional |
| `en.name` | string | optional, max:255 |
| `en.description` | string | optional |

### Response

```json
{
  "status": "success",
  "message": "Vendor basic information updated successfully",
  "data": {
    "id": 1,
    "name": "Vendor Name",
    "email": "vendor@example.com",
    "phone": "1234567890",
    "merchant": {
      "id": 1,
      "commercial_register_number": "CR123456",
      "iban": "SA1234567890",
      "translations": {
        "ar": {
          "name": "اسم التاجر",
          "description": "وصف التاجر"
        },
        "en": {
          "name": "Merchant Name",
          "description": "Merchant Description"
        }
      }
    }
  }
}
```

---

## 2. Update Vendor Merchant Data

**Endpoint:** `PATCH /api/dashboard/admin/vendors/{vendor}/merchant-data`

**Purpose:** Update vendor's merchant-specific data including location and delivery settings.

### Request Body

```json
{
  "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
    }
  ],
  "location": {
    "address": "123 Main Street, Building 5",
    "latitude": 24.7136,
    "longitude": 46.6753,
    "country_id": 1,
    "city_id": 5
  }
}
```

### Validation Rules

| Field | Type | Rules |
|-------|------|-------|
| `delivery_type` | string | optional, must be: "merchant" or "platform" |
| `delivery_cities` | array | required if delivery_type is "merchant" |
| `delivery_cities.*.country_id` | integer | required with delivery_cities, exists in countries table |
| `delivery_cities.*.city_id` | integer | required with delivery_cities, exists in cities table |
| `delivery_cities.*.delivery_price` | numeric | required with delivery_cities, min:0 |
| `location` | object | optional |
| `location.address` | string | optional |
| `location.latitude` | numeric | optional, between -90 and 90 |
| `location.longitude` | numeric | optional, between -180 and 180 |
| `location.country_id` | integer | optional, exists in countries table |
| `location.city_id` | integer | required when location is provided, exists in cities table |

### Delivery Type Options

- **`merchant`**: Vendor handles their own delivery (requires delivery_cities)
- **`platform`**: Platform handles delivery (delivery_cities not required)

### Response

```json
{
  "status": "success",
  "message": "Vendor merchant data updated successfully",
  "data": {
    "id": 1,
    "name": "Vendor Name",
    "merchant": {
      "id": 1,
      "delivery_type": "merchant",
      "delivery_cities": [
        {
          "id": 1,
          "country_id": 1,
          "city_id": 5,
          "delivery_price": "25.50",
          "city": {
            "id": 5,
            "name": "Riyadh"
          }
        },
        {
          "id": 2,
          "country_id": 1,
          "city_id": 10,
          "delivery_price": "30.00",
          "city": {
            "id": 10,
            "name": "Jeddah"
          }
        }
      ]
    },
    "locations": [
      {
        "id": 1,
        "address": "123 Main Street, Building 5",
        "latitude": "24.7136",
        "longitude": "46.6753",
        "country_id": 1,
        "city_id": 5
      }
    ]
  }
}
```

---

## Error Responses

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

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

### 422 - Validation Error
```json
{
  "status": "fail",
  "message": "The given data was invalid",
  "errors": {
    "email": ["The email has already been taken."],
    "delivery_cities": ["Delivery cities are required when delivery is handled by merchant"]
  }
}
```

---

## Usage Examples

### Example 1: Update Only Basic Info

```bash
curl -X PATCH \
  https://api.example.com/api/dashboard/admin/vendors/123/basic-info \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "New Vendor Name",
    "email": "newemail@example.com",
    "phone": "0501234567"
  }'
```

### Example 2: Update Delivery Settings

```bash
curl -X PATCH \
  https://api.example.com/api/dashboard/admin/vendors/123/merchant-data \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "delivery_type": "merchant",
    "delivery_cities": [
      {
        "country_id": 1,
        "city_id": 5,
        "delivery_price": 25.50
      }
    ]
  }'
```

### Example 3: Update Location Only

```bash
curl -X PATCH \
  https://api.example.com/api/dashboard/admin/vendors/123/merchant-data \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": {
      "address": "New Address",
      "latitude": 24.7136,
      "longitude": 46.6753,
      "city_id": 5
    }
  }'
```

---

## Notes

1. **Separation of Concerns**: Basic user info and merchant-specific data are now separated into two endpoints for better organization and flexibility.

2. **Partial Updates**: Both endpoints support partial updates - you only need to send the fields you want to update.

3. **Delivery Cities**: When `delivery_type` is set to "merchant", the `delivery_cities` array is required. When set to "platform", delivery_cities are optional.

4. **Location**: The location object requires `city_id` when provided. Other fields are optional.

5. **Translations**: Merchant name and description support multiple languages (ar, en).

6. **Existing Endpoint**: The original `PUT/PATCH /api/dashboard/admin/vendors/{vendor}` endpoint still works for backward compatibility.