## API Documentation for Advertiser Management

This API provides comprehensive management capabilities for advertisers. It supports operations such as creating,
updating, and deleting advertisers. Advertisers can be created by both individual users and teams. The API includes
functionality for categorizing advertisers into paid categories and allows for the enhancement of advertiser visibility
through optional features like "urgent" or "ladder" boosts.

### List of Contents

- [Authentication](#authentication)
- [Advertisement Categories](#advertise-categories)
    - [Categories List](#advertise-categories-list)
    - [Category Attributes](#advertise-category-attributes)
- [Get Advertisement(s)](#1-advertisements-list-index)
- [Get Advertisement](#2-show-an-advertisement-single)
- [Create Advertisement](#3-create-an-advertisement)
- [Update Advertisement](#4-update-an-advertisement)
- [Remove Advertisement](#5-delete-an-advertisement)
- [Sort & Filtering](#advertise-sort--filter)

### Authentication

- Authentication is handled using [Sanctum](https://laravel.com/docs/sanctum) tokens. Ensure that you include a valid
  token in the `Authorization` header of your requests to access protected endpoints.

### Content Type

- All API endpoints operate with `application/json` for both requests and responses.

---

### Advertise Categories

#### Advertise Categories List

- **Endpoint**: `POST /api/v1/categories/list`
- **Description**: Retrieve the list of available advertise categories
- **Authentication**: No.
- **Permissions**: User or Team.

| Parameter     | Required/Optional | Type    | Description                                                                                                       |
|---------------|-------------------|---------|-------------------------------------------------------------------------------------------------------------------|
| `category_id` | Optional          | Integer | The ID of the category which you want to get and it's parents (Pass `first` if you don't want to get parents too. |
| `build_tree`  | Optional          | Integer | Build a tree style for response                                                                                   |

##### Request Example:

```json
{
    "category_id": 1,
    "build_tree": 0
}
```

##### Response Example:

```json
{
    "status": true,
    "message": "موفقیت آمیز!",
    "data": {
        "count": 2,
        "categories": [
            {
                "id": 1,
                "name": "املاک",
                "parent_id": 0,
                "term_id": null,
                "is_free": 0,
                "price": "0",
                "image": "sfJIod529Ajv4kcrzM7Co09MTUJxDMS6jwnclAji.png",
                "has_child": true
            },
            {
                "id": 2,
                "name": "Electronic",
                "parent_id": 0,
                "term_id": null,
                "is_free": 0,
                "price": "0",
                "image": "PmVBJekIDNUzEHnfKsDMPz22I9bWe73VVPzC17C1.png",
                "has_child": false
            }
        ]
    }
}
```

#### Advertise Category Attributes

- **Endpoint**: `POST /api/v1/get-category-inputs`
- **Description**: Retrieve the attributes required for an advertisement based on its category.
- **Authentication**: No.
- **Permissions**: User or Team.

| Parameter     | Required/Optional | Type    | Description                                                      |
|---------------|-------------------|---------|------------------------------------------------------------------|
| `category_id` | Required          | Integer | The ID of the category for which attributes are being requested. |

##### Request Example:

```json
{
    "category_id": 1
}
```

##### Response Example:

```json
{
    "status": true,
    "message": "موفقیت آمیز!",
    "data": [
        {
            "id": 1,
            "advertise_type_id": 1,
            "label": "floor",
            "type": "text",
            "name": "floor",
            "default_value": null,
            "is_required": 1,
            "is_filterable": 0,
            "filter_type": "text",
            "is_price_effective": 0,
            "validation": null,
            "created_at": "2024-09-11T16:19:51.000000Z",
            "updated_at": "2024-09-11T16:19:52.000000Z"
        },
        {
            "id": 2,
            "advertise_type_id": 1,
            "label": "plate",
            "type": "text",
            "name": "plate",
            "default_value": null,
            "is_required": 0,
            "is_filterable": 0,
            "filter_type": "text",
            "is_price_effective": 0,
            "validation": null,
            "created_at": "2024-09-11T16:20:09.000000Z",
            "updated_at": "2024-09-11T16:20:10.000000Z"
        },
        {
            "id": 3,
            "advertise_type_id": 1,
            "label": "size",
            "type": "range",
            "name": "size",
            "default_value": null,
            "is_required": 1,
            "is_filterable": 1,
            "filter_type": "range",
            "is_price_effective": 0,
            "validation": null,
            "created_at": "2024-09-11T16:20:41.000000Z",
            "updated_at": "2024-09-11T16:20:42.000000Z"
        }
    ]
}
```

---

### 1. **Advertisements List (Index)**

- **Endpoint**: `POST /api/v1/advertises/list` & `POST /api/v1/user/advertises`
- **Description**: Fetch a paginated list of advertisers with optional filtering and sorting. This endpoint allows you
  to retrieve a comprehensive list of advertisers based on various criteria, including pagination, filters, and sorting
  preferences.
- **Authentication**: Yes (Just for User/advertises).
- **Permissions**: User or Team.

#### Request Parameters:

| Parameter     | Required/Optional | Type    | Description                                                                                |
|---------------|-------------------|---------|--------------------------------------------------------------------------------------------|
| `per_page`    | Optional          | Integer | Number of advertisers to display per page. Default is 10.                                  |
| `page`        | Optional          | Integer | Page number to retrieve. Default is 1.                                                     |
| `filters[]`   | Optional          | Array   | Filters to apply to the advertiser list.                                                   |
| `sort`        | Optional          | String  | [Sort](#advertise-sort--filter) method to apply to the list (e.g., "newest", "price_asc"). |
| `category_id` | Optional          | Integer | [Filter](#advertise-sort--filter) results by category ID.                                  |

##### Filter Parameters:

| Parameter               | Type    | Description                                                                 |
|-------------------------|---------|-----------------------------------------------------------------------------|
| `user_id`               | Integer | Filters results by a specific user's ID.                                    |
| `is_team`               | Boolean | Filters results where `user_id` is null (team).                             |
| `is_user`               | Boolean | Filters results where `team_id` is null (user).                             |
| `advertise_type_id`     | Integer | Filters results by a specific advertisement type.                           |
| `type`                  | String  | Filters results by the specified type (supply, demand).                     |
| `price[min]`            | Numeric | Filters results where price is greater than or equal to this value.         |
| `price[max]`            | Numeric | Filters results where price is less than or equal to this value.            |
| `adv_status`            | String  | Filters results by new/used status ("new" or "old").                        |
| `call_active`           | Boolean | Filters results to include only active calls.                               |
| `chat_active`           | Boolean | Filters results to include only active chats.                               |
| `exact_location_active` | Boolean | Filters results to include only those with exact location shown.            |
| `province`              | String  | Filters results by province name.                                           |
| `city`                  | String  | Filters results by city name.                                               |
| `image`                 | Boolean | Filters results based on the presence of images (1 for exists, 0 for none). |

##### Sort Parameters:

| Parameter    | Type   | Description                                        |
|--------------|--------|----------------------------------------------------|
| `newest`     | String | Sorts results by `created_at` in descending order. |
| `oldest`     | String | Sorts results by `created_at` in ascending order.  |
| `title_asc`  | String | Sorts results by `title` in ascending order.       |
| `title_desc` | String | Sorts results by `title` in descending order.      |

#### Request Example:

```json
{
    "per_page": 10,
    "page": 1,
    "sort": "newest",
    "filters": {
        "adv_status": "new"
    },
    "category_id": 1
}
```

#### Response Example:

```json
{
    "status": true,
    "message": "Operation successful!",
    "data": {
        "data": [
            {
                "id": 1,
                "advertise_type_id": 1,
                "type": "supply",
                "title": "Sample Advertisement Title",
                "price": "100000",
                "is_new": true,
                "status": "published",
                "location": {
                    "province": {
                        "id": 1,
                        "name": "East Azerbaijan"
                    },
                    "city": {
                        "id": 1,
                        "name": "Azarshahr"
                    }
                },
                "images": [
                    {
                        "name": "image1.png",
                        "path": "http://127.0.0.1:8000/upload/image1.png",
                        "type": "png"
                    },
                    {
                        "name": "image2.png",
                        "path": "http://127.0.0.1:8000/upload/image2.png",
                        "type": "png"
                    }
                ],
                "badges": null,
                "attributes": null,
                "created_at": "2024-09-11T17:00:32.000000Z",
                "updated_at": "2024-09-11T17:00:32.000000Z"
            },
            {
                "id": 2,
                "advertise_type_id": 2,
                "type": "supply",
                "title": "Sample Advertisement Title",
                "price": "100000",
                "is_new": true,
                "status": "review",
                "location": {
                    "province": {
                        "id": 1,
                        "name": "East Azerbaijan"
                    },
                    "city": {
                        "id": 1,
                        "name": "Azarshahr"
                    }
                },
                "images": [
                    {
                        "name": "image3.png",
                        "path": "http://127.0.0.1:8000/upload/image3.png",
                        "type": "png"
                    }
                ],
                "badges": null,
                "attributes": null,
                "created_at": "2024-09-11T17:03:11.000000Z",
                "updated_at": "2024-09-11T17:03:11.000000Z"
            }
        ],
        "links": {
            "first": "http://127.0.0.1:8000/api/v1/advertises/list?page=1",
            "last": "http://127.0.0.1:8000/api/v1/advertises/list?page=1",
            "prev": null,
            "next": null
        },
        "meta": {
            "current_page": 1,
            "from": 1,
            "last_page": 1,
            "path": "http://127.0.0.1:8000/api/v1/advertises/list",
            "per_page": 10,
            "to": 2,
            "total": 2
        }
    }
}
```

---

### 2. **Show an Advertisement (Single)**

- **Endpoint**: `POST /api/v1/advertise/show`
- **Description**: Retrieve detailed information for a specific advertisement using its ID. This endpoint provides
  comprehensive details about the advertisement including location, images, and attributes.
- **Authentication**: No.
- **Permissions**: User or Team.

#### Request Parameters:

| Parameter      | Required/Optional | Type    | Description                              |
|----------------|-------------------|---------|------------------------------------------|
| `advertise_id` | Required          | Integer | The ID of the advertisement to retrieve. |

#### Request Example:

```json
{
    "advertise_id": 1
}
```

#### Response Example:

```json
{
    "status": true,
    "message": "Operation successful!",
    "data": {
        "id": 1,
        "advertise_type_id": 1,
        "category": "House",
        "link": "http://127.0.0.1:8000/advertise/advertisement-title",
        "user_id": 6,
        "team_id": null,
        "type": "supply",
        "title": "Advertisement Title",
        "price": "100000",
        "short_description": "A brief description of the advertisement.",
        "code": "HESO3",
        "slug": "advertisement-title",
        "is_new": true,
        "status": "published",
        "location": {
            "province": {
                "id": 1,
                "name": "آذربایجان شرقی"
            },
            "city": {
                "id": 1,
                "name": "آذرشهر"
            },
            "long": "4344144424.2112",
            "lat": "232321313131.21",
            "show_exact_location": true
        },
        "images": [
            {
                "name": "KmCqLgEBqbCZKNy.png",
                "path": "http://127.0.0.1:8000/upload/KmCqLgEBqbCZKNy.png",
                "type": "png"
            },
            {
                "name": "FruQSqfFsKm0IGn.png",
                "path": "http://127.0.0.1:8000/upload/FruQSqfFsKm0IGn.png",
                "type": "png"
            },
            {
                "name": "OkoyXLlyXH4nhcD.png",
                "path": "http://127.0.0.1:8000/upload/OkoyXLlyXH4nhcD.png",
                "type": "png"
            }
        ],
        "call_is_active": false,
        "chat_is_active": true,
        "attributes": [
            {
                "label": "floor",
                "value": "first"
            },
            {
                "label": "size",
                "value": "87"
            }
        ],
        "created_at": "2024-09-11T17:00:32.000000Z"
    }
}
```

---

### 3. **Create an Advertisement**

- **Endpoint**: `POST /api/v1/advertise/store`
- **Description**: Create a new advertisement for a specified category. This endpoint allows users or teams to submit a
  new advertisement with various details, including category, location, and optional features.
- **Authentication**: Required.
- **Permissions**: User or Team.

#### Request Parameters:

| Parameter                               | Required/Optional             | Type    | Description                                                                                   |
|-----------------------------------------|-------------------------------|---------|-----------------------------------------------------------------------------------------------|
| `category_id`                           | Required                      | Integer | The ID of the category for the advertisement.                                                 |
| `team_id`                               | Optional                      | Integer | The ID of the Team creating the advertisement.                                                |
| `type`                                  | Required                      | String  | The type of advertisement, e.g., `supply` or `demand`.                                        |
| `title`                                 | Required                      | String  | The title of the advertisement.                                                               |
| `price`                                 | Optional                      | Number  | The price of the advertised product or service.                                               |
| `short_description`                     | Required                      | String  | A brief description of the advertisement.                                                     |
| `lat`                                   | Optional                      | Float   | The latitude of the advertiser's location.                                                    |
| `long`                                  | Optional                      | Float   | The longitude of the advertiser's location.                                                   |
| `show_exact_location`                   | Optional                      | Boolean | Whether to show the exact location (1 for yes, 0 for no).                                     |
| `call_is_active`                        | Optional                      | Boolean | Whether call functionality is active (1 for yes, 0 for no).                                   |
| `chat_is_active`                        | Optional                      | Boolean | Whether chat functionality is active (1 for yes, 0 for no).                                   |
| `province_id`                           | Required                      | Integer | The ID of the province where the advertiser is located.                                       |
| `city_id`                               | Required                      | Integer | The ID of the city where the advertiser is located.                                           |
| `is_new`                                | Optional                      | Boolean | Whether the product/service is new (1 for yes, 0 for no).                                     |
| `is_urgent`                             | Optional                      | Boolean | Whether the advertisement is marked as urgent (1 for yes, 0 for no).                          |
| `is_ladder`                             | Optional                      | Boolean | Whether the advertisement is featured on top of the list (1 for yes, 0 for no).               |
| `images`                                | Optional                      | Array   | An array of image URLs (BASE64) or file references for the advertisement.                     |
| `attributes_data`                       | (Based on category attribute) | Array   | An array of attribute data for the advertisement, with each attribute having an ID and value. |
| `attributes_data.plate.attribute_id`    | (Based on category attribute) | Integer | The ID of the attribute.                                                                      |
| `attributes_data.plate.attribute_value` | (Based on category attribute) | Mixed   | The value of the attribute.                                                                   |

#### Request Example:

```json
{
    "category_id": 1,
    "team_id": 1,
    "type": "supply",
    "title": "Sample Advertisement Title",
    "price": 100000,
    "short_description": "This is a test advertisement",
    "lat": 35.6895,
    "long": 139.6917,
    "show_exact_location": 1,
    "call_is_active": 0,
    "chat_is_active": 1,
    "province_id": 1,
    "city_id": 1,
    "is_new": 1,
    "is_urgent": 1,
    "is_ladder": 1,
    "images": [
        "BASE64_IMAGE_CODE_1",
        "BASE64_IMAGE_CODE_2",
        "BASE64_IMAGE_CODE_3"
    ],
    "attributes_data": {
        "floor": {
            "attribute_id": 1,
            "attribute_value": "first"
        },
        "parking": {
            "attribute_id": 2,
            "attribute_value": 1
        }
    }
}
```

#### Response Example:

```json
{
    "status": true,
    "message": "Operation successful!",
    "data": {
        "advertise_id": 1
    }
}
```

###### **NOTICE:

** All newly created advertisements are automatically marked as review. This means they require approval from an
Administrator before being published!

---

If the category type is PAID and the user or Team does not have a package or subscription, or if additional features are
required, the response will include an `order` key:

```json
{
    "status": true,
    "message": "Operation successful!",
    "data": {
        "advertise_id": 1,
        "order": {
            "order_id": 1,
            "amount": 15000,
            "tracking_code": "2024091152409",
            "uuid": "7a9de765-8395-4942-bece-d9f9dbcdeb43"
        }
    }
}
```

---

### 4. **Update an Advertisement**

- **Endpoint**: `POST /api/v1/advertise/update`
- **Description**: Update the details of an existing advertisement. Note that changing the category from free to paid or
  vice versa is not permitted after creation.
- **Authentication**: Required.
- **Permissions**: User or Team.

#### Request Parameters:

| Parameter                               | Required/Optional | Type    | Description                                                               |
|-----------------------------------------|-------------------|---------|---------------------------------------------------------------------------|
| `advertise_id`                          | Required          | Integer | The ID of the advertisement to update.                                    |
| `category_id`                           | Optional          | Integer | The ID of the category for the advertisement.                             |
| `team_id`                               | Optional          | Integer | The ID of the Team responsible for the advertisement.                     |
| `type`                                  | Optional          | String  | The type of advertisement, e.g., `supply` or `demand`.                    |
| `title`                                 | Optional          | String  | The title of the advertisement.                                           |
| `price`                                 | Optional          | Number  | The price of the advertised product or service.                           |
| `short_description`                     | Optional          | String  | A brief description of the advertisement.                                 |
| `lat`                                   | Optional          | Float   | The latitude of the advertisement's location.                             |
| `long`                                  | Optional          | Float   | The longitude of the advertisement's location.                            |
| `show_exact_location`                   | Optional          | Boolean | Whether to show the exact location (1 for yes, 0 for no).                 |
| `call_is_active`                        | Optional          | Boolean | Whether call functionality is active (1 for yes, 0 for no).               |
| `chat_is_active`                        | Optional          | Boolean | Whether chat functionality is active (1 for yes, 0 for no).               |
| `province_id`                           | Optional          | Integer | The ID of the province where the advertisement is located.                |
| `city_id`                               | Optional          | Integer | The ID of the city where the advertisement is located.                    |
| `is_new`                                | Optional          | Boolean | Whether the product/service is new (1 for yes, 0 for no).                 |
| `images`                                | Optional          | Array   | An array of image URLs (BASE64) or file references for the advertisement. |
| `attributes_data`                       | Optional          | Array   | An array of attribute data for the advertisement.                         |
| `attributes_data.plate.attribute_id`    | Optional          | Integer | The ID of the attribute.                                                  |
| `attributes_data.plate.attribute_value` | Optional          | Mixed   | The value of the attribute.                                               |

#### Request Example:

```json
{
    "advertise_id": 1,
    "category_id": 1,
    "team_id": 1,
    "type": "supply",
    "title": "New Advertisement Title",
    "price": 100000,
    "short_description": "This is a new test advertisement",
    "lat": 181201.241414,
    "long": 43441.4124312,
    "show_exact_location": 1,
    "call_is_active": 0,
    "chat_is_active": 1,
    "province_id": 1,
    "city_id": 1,
    "is_new": 1,
    "images": [
        "BASE_64_IMAGE_CODE",
        "BASE_64_IMAGE_CODE"
    ],
    "attributes_data": {
        "floor": {
            "attribute_id": 1,
            "attribute_value": "second"
        },
        "parking": {
            "attribute_id": 1,
            "attribute_value": 0
        }
    }
}
```

#### Response Example:

```json
{
    "status": true,
    "message": "Advertisement updated successfully!",
    "data": {
        "advertise_id": 1
    }
}
```

---

#### Response Example:

```json
{
    "status": true,
    "message": "موفقیت آمیز!",
    "data": true
}
```

---

### 5. **Delete an Advertisement**

- **Endpoint**: `POST /api/v1/advertisers/remove`
- **Description**: Permanently delete an advertisement created by the authenticated user or Team.
- **Authentication**: Required
- **Permissions**: User or Team

#### Request Parameters:

| Parameter      | Required/Optional | Type    | Description                                     |
|----------------|-------------------|---------|-------------------------------------------------|
| `advertise_id` | Required          | Integer | The ID of the advertisement you wish to delete. |

#### Request Example:

```json
{
    "advertise_id": 1
}
```

#### Response Example:

```json
{
    "status": true,
    "message": "Advertisement successfully deleted!",
    "data": true
}
```

---

This version provides a clear description and parameter table for the delete operation, making it easy for developers to
understand and implement.

#### Advertise Sort & Filter

- **Endpoint**: `POST /api/v1/advertise/filter-options`
- **Description**: Get the available sorting and filtering options for advertisements.
  to a category.
- **Authentication**: Required
- **Permissions**: User or team

#### Request Parameters:

| Parameter     | Required/Optional | Type    | Description                                                                                                                 |
|---------------|-------------------|---------|-----------------------------------------------------------------------------------------------------------------------------|
| `category_id` | Optional          | Integer | The ID of the category to get specific sortable and filterable options for (if not provided, default options are returned). |

##### Request Example:

```json
{
    "category_id": 1
}
```

##### Response Example:

```json
{
    "status": true,
    "message": "موفقیت آمیز!",
    "data": {
        "filters": [
            {
                "label": "type",
                "type": "text",
                "name": "type",
                "default_value": "supply"
            },
            {
                "label": "status",
                "type": "text",
                "name": "status",
                "default_value": "new"
            },
            {
                "label": "price",
                "type": "range",
                "name": "price",
                "default_value": null
            }
        ],
        "sort": [
            {
                "label": "newest",
                "name": "newest"
            },
            {
                "label": "cheapest",
                "name": "cheapest"
            },
            {
                "label": "most_expensive",
                "name": "most_expensive"
            }
        ]
    }
}
```

###### **NOTICE:

** Dynamic filter options are also available based on the selected category type and will be included under the filters
key in the response.

---