# Penalty Types API

> Base URL: `/api/v1/penalty-types`

## Overview

The Penalty Types endpoint manages reference data for disciplinary penalty types.
Each penalty type has a `name` (unique) and `status` (Active/Inactive).

### Seeded Reference Data

| # | Name |
|---|------|
| 1 | Written Reprimand |
| 2 | Verbal Reprimand |
| 3 | Suspension |
| 4 | Demotion |
| 5 | Fine |
| 6 | Termination |
| 7 | Forced Resignation |
| 8 | Warning |

---

## List All Penalty Types

```
GET /api/v1/penalty-types
```

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `search` | string | Filter by name (LIKE match) |
| `status` | string | Filter by status: `Active` or `Inactive` |
| `per_page` | integer | Items per page (default: 10) |

### Response (200)

```json
{
  "success": true,
  "message": "Penalty types retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Written Reprimand",
      "status": "Active",
      "created_at": "2026-06-04T00:00:00.000000Z",
      "updated_at": "2026-06-04T00:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 8,
    "last_page": 1
  }
}
```

---

## Create Penalty Type

```
POST /api/v1/penalty-types
```

### Request Body

| Field | Type | Rules |
|-------|------|-------|
| `name` | string | **Required**, max:255, unique |
| `status` | string | Optional, one of: `Active`, `Inactive` (default: `Active`) |

### Response (201)

```json
{
  "success": true,
  "message": "Penalty type created successfully",
  "data": {
    "id": 9,
    "name": "Community Service",
    "status": "Active",
    "created_at": "2026-06-04T00:00:00.000000Z",
    "updated_at": "2026-06-04T00:00:00.000000Z"
  }
}
```

### Error (422 — Validation)

```json
{
  "message": "The name has already been taken.",
  "errors": {
    "name": ["The name has already been taken."]
  }
}
```

---

## Get Penalty Type

```
GET /api/v1/penalty-types/{id}
```

### Response (200)

```json
{
  "success": true,
  "message": "Penalty type retrieved successfully",
  "data": {
    "id": 1,
    "name": "Written Reprimand",
    "status": "Active",
    "created_at": "2026-06-04T00:00:00.000000Z",
    "updated_at": "2026-06-04T00:00:00.000000Z"
  }
}
```

### Error (404)

```json
{
  "success": false,
  "message": "Penalty type not found"
}
```

---

## Update Penalty Type

```
PATCH /api/v1/penalty-types/{id}
```

### Request Body

| Field | Type | Rules |
|-------|------|-------|
| `name` | string | **Required**, max:255, unique (excluding current) |
| `status` | string | Optional, one of: `Active`, `Inactive` |

### Response (200)

```json
{
  "success": true,
  "message": "Penalty type updated successfully",
  "data": {
    "id": 8,
    "name": "Warning Notice",
    "status": "Active",
    "created_at": "2026-06-04T00:00:00.000000Z",
    "updated_at": "2026-06-04T00:00:00.000000Z"
  }
}
```

---

## Soft-Delete (Deactivate) Penalty Type

```
DELETE /api/v1/penalty-types/{id}
```

Sets the penalty type's status to `Inactive`.

### Response (200)

```json
{
  "success": true,
  "message": "Penalty type deactivated successfully"
}
```

---

## Restore Penalty Type

```
POST /api/v1/penalty-types/{id}/restore
```

Restores a deactivated penalty type by setting status back to `Active`.

### Response (200)

```json
{
  "success": true,
  "message": "Penalty type activated successfully",
  "data": {
    "id": 5,
    "name": "Fine",
    "status": "Active",
    "created_at": "2026-06-04T00:00:00.000000Z",
    "updated_at": "2026-06-04T00:00:00.000000Z"
  }
}
```

### Error (500)

```json
{
  "success": false,
  "message": "Failed to activate penalty type",
  "error": "No query results for model [App\\Models\\PenaltyType]"
}
```

---

## Force Delete Penalty Type

```
DELETE /api/v1/penalty-types/{id}/force-delete
```

Permanently removes a deactivated penalty type from the database. Only works on records with `status: Inactive`.

### Response (200)

```json
{
  "success": true,
  "message": "Penalty type permanently deleted"
}
```

---

## List Trashed (Inactive) Penalty Types

```
GET /api/v1/penalty-types/trashed/list
```

### Response (200)

```json
{
  "success": true,
  "message": "Inactive penalty types retrieved successfully",
  "data": [
    {
      "id": 5,
      "name": "Fine",
      "status": "Inactive",
      "created_at": "2026-06-04T00:00:00.000000Z",
      "updated_at": "2026-06-04T00:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 1,
    "last_page": 1
  }
}
```

---

## Error Responses

### 500 — Server Error

```json
{
  "success": false,
  "message": "Failed to [action] penalty type",
  "error": "Detailed error message"
}
```

### 422 — Validation Error

```json
{
  "message": "The [field] field is required. (and X more errors)",
  "errors": {
    "name": ["The name field is required."]
  }
}
```