# Ticket API Documentation

## Base Information

-   **Base URL:** `https://your-domain.com/api`
-   **Authentication:** Sanctum (Bearer Token or Session)
-   **Middleware:** `auth:sanctum` (all ticket routes require authentication)

---

## API Endpoints

### 1. Create a Support Ticket

**Endpoint:** `POST /api/tickets`  
**Description:** Creates a new support ticket for the authenticated user (either customer or vendor).

#### Headers

```
Authorization: Bearer {token}
Accept: application/json
Content-Type: application/json
```

#### Request Body

```json
{
    "title": "Issue with my order #12345",
    "description": "I received a damaged product and need a replacement."
}
```

#### Validation Rules

-   `title`: required, string, max: 255 characters
-   `description`: required, string

#### Success Response (201 Created)

```json
{
    "message": "Ticket created successfully",
    "ticket": {
        "id": 1,
        "title": "Issue with my order #12345",
        "description": "I received a damaged product and need a replacement.",
        "user_id": 5,
        "vendor_id": null,
        "status": "open",
        "created_at": "2026-05-06T13:00:00.000000Z",
        "updated_at": "2026-05-06T13:00:00.000000Z"
    }
}
```

#### Error Response (422 Unprocessable Entity)

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "title": ["The title field is required."],
        "description": ["The description field is required."]
    }
}
```

---

### 2. List User's Tickets

**Endpoint:** `GET /api/tickets`  
**Description:** Retrieves a paginated list of tickets belonging to the authenticated user. Vendors see tickets where they are the vendor; customers see tickets where they are the user.

#### Headers

```
Authorization: Bearer {token}
Accept: application/json
```

#### Query Parameters (optional)

-   `page` - Page number (default: 1)
-   `per_page` - Items per page (default: 10)

#### Success Response (200 OK)

```json
{
    "tickets": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "title": "Issue with my order #12345",
                "description": "I received a damaged product...",
                "user_id": 5,
                "vendor_id": null,
                "status": "open",
                "created_at": "2026-05-06T13:00:00.000000Z",
                "updated_at": "2026-05-06T13:00:00.000000Z",
                "user": {
                    "id": 5,
                    "name": "John Doe",
                    "email": "john@example.com"
                },
                "vendor": null
            }
        ],
        "first_page_url": "http://your-domain.com/api/tickets?page=1",
        "last_page": 1,
        "per_page": 10,
        "total": 1
    }
}
```

---

### 3. Get Single Ticket Details

**Endpoint:** `GET /api/tickets/{id}`  
**Description:** Retrieves details of a specific ticket. User can only access their own tickets.

#### Headers

```
Authorization: Bearer {token}
Accept: application/json
```

#### URL Parameters

-   `id` - Ticket ID

#### Success Response (200 OK)

```json
{
    "ticket": {
        "id": 1,
        "title": "Issue with my order #12345",
        "description": "I received a damaged product and need a replacement.",
        "user_id": 5,
        "vendor_id": null,
        "status": "open",
        "created_at": "2026-05-06T13:00:00.000000Z",
        "updated_at": "2026-05-06T13:00:00.000000Z",
        "user": {
            "id": 5,
            "name": "John Doe",
            "email": "john@example.com"
        },
        "vendor": null
    }
}
```

#### Error Response (403 Forbidden)

```json
{
    "message": "Unauthorized access"
}
```

#### Error Response (404 Not Found)

```json
{
    "message": "No query results for model [App\\Models\\Ticket] 1"
}
```

---

## Ticket Model Attributes

| Field         | Type     | Description                                 |
| ------------- | -------- | ------------------------------------------- |
| `id`          | integer  | Ticket ID                                   |
| `title`       | string   | Ticket title (max 255 chars)                |
| `description` | text     | Detailed description                        |
| `user_id`     | integer  | ID of regular user (nullable)               |
| `vendor_id`   | integer  | ID of vendor user (nullable)                |
| `status`      | enum     | `open`, `in_progress`, `resolved`, `closed` |
| `created_at`  | datetime | Creation timestamp                          |
| `updated_at`  | datetime | Last update timestamp                       |
| `user`        | relation | BelongsTo User (if user_id set)             |
| `vendor`      | relation | BelongsTo User (if vendor_id set)           |

---

## Notes

-   All routes are under the `auth:sanctum` middleware group (see `routes/api.php` lines 55-82)
-   Ticket status defaults to `"open"` on creation
-   The system automatically determines if the authenticated user is a vendor (if `user_type === 'vendor'` or has a `store`) and sets `vendor_id` accordingly; otherwise sets `user_id`
-   Pagination is fixed at 10 items per page for the index endpoint
-   Authorization is enforced: users can only view tickets they own (either as `user_id` or `vendor_id`)
-   The `user` and `vendor` relationships are eager-loaded on the `show` endpoint

---

## Route Definition (routes/api.php)

```php
Route::middleware('auth:sanctum')->group(function () {
    // Ticket/Support routes (require authentication)
    Route::post('tickets', [TicketController::class, 'store']);
    Route::get('tickets', [TicketController::class, 'index']);
    Route::get('tickets/{id}', [TicketController::class, 'show']);
});
```

---

## Controller Location

`app/Http/Controllers/API/TicketController.php`