# Agent Training & Certification API Documentation

This document provides API documentation for the Training & Certification features of the Agent Module.

## Base URL

All endpoints are relative to the base URL of your application.

## Authentication

All endpoints require authentication. Include the authentication token in the request header:

```
Authorization: Bearer {token}
```

## Endpoints

### Training Materials

#### List Training Materials

Retrieves a list of available training materials.

**URL**: `/api/agent/training`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| page      | int    | No       | Page number for pagination (default: 1)          |
| per_page  | int    | No       | Number of items per page (default: 10)           |
| category  | string | No       | Filter by category                               |
| search    | string | No       | Search term to filter training materials by name |

**Response**:

```json
{
  "data": [
    {
      "id": 1,
      "title": "Introduction to Referrals",
      "description": "Learn the basics of the referral system",
      "type": "video",
      "duration_minutes": 15,
      "has_quiz": true,
      "is_required": true,
      "completed": false,
      "thumbnail_url": "https://example.com/thumbnails/intro.jpg",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    // More training materials...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "/api/agent/training",
    "per_page": 10,
    "to": 10,
    "total": 50
  }
}
```

#### Get Training Material

Retrieves a specific training material.

**URL**: `/api/agent/training/{id}`

**Method**: `GET`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the training material |

**Response**:

```json
{
  "data": {
    "id": 1,
    "title": "Introduction to Referrals",
    "description": "Learn the basics of the referral system",
    "content": "Full content of the training material...",
    "type": "video",
    "video_url": "https://example.com/videos/intro.mp4",
    "document_url": null,
    "duration_minutes": 15,
    "has_quiz": true,
    "is_required": true,
    "completed": false,
    "completion_percentage": 0,
    "quiz_questions": [
      {
        "id": 1,
        "question": "What is the main benefit of referrals?",
        "options": [
          "Increased revenue",
          "Better customer service",
          "More clients",
          "All of the above"
        ]
      },
      // More questions...
    ],
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

#### Mark Training as Completed

Marks a training material as completed.

**URL**: `/api/agent/training/{id}/complete`

**Method**: `POST`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the training material |

**Response**:

```json
{
  "message": "Training marked as completed",
  "data": {
    "id": 1,
    "training_material_id": 1,
    "completed": true,
    "completed_at": "2023-01-15T10:30:00Z",
    "score": null
  }
}
```

#### Submit Quiz

Submits answers for a training quiz.

**URL**: `/api/agent/training/{id}/quiz`

**Method**: `POST`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the training material |

**Request Body**:

```json
{
  "answers": {
    "1": 3,  // Question ID: Selected option index (0-based)
    "2": 1,
    "3": 0
    // More answers...
  }
}
```

**Response**:

```json
{
  "message": "Quiz submitted successfully",
  "data": {
    "id": 1,
    "training_material_id": 1,
    "completed": true,
    "completed_at": "2023-01-15T10:30:00Z",
    "score": 85,
    "passed": true,
    "results": [
      {
        "question_id": 1,
        "correct": true,
        "correct_answer": 3
      },
      {
        "question_id": 2,
        "correct": true,
        "correct_answer": 1
      },
      {
        "question_id": 3,
        "correct": false,
        "correct_answer": 2
      }
      // More results...
    ]
  }
}
```

### Certifications

#### List Certifications

Retrieves a list of available certifications.

**URL**: `/api/agent/certifications`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| page      | int    | No       | Page number for pagination (default: 1)          |
| per_page  | int    | No       | Number of items per page (default: 10)           |
| status    | string | No       | Filter by status (earned, in-progress, available) |

**Response**:

```json
{
  "data": [
    {
      "id": 1,
      "name": "Referral Specialist",
      "description": "Certification for agents who have mastered the referral system",
      "badge_image": "https://example.com/badges/referral-specialist.png",
      "required_training_count": 5,
      "completed_training_count": 3,
      "status": "in-progress",
      "progress_percentage": 60,
      "earned_at": null,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    // More certifications...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "path": "/api/agent/certifications",
    "per_page": 10,
    "to": 10,
    "total": 15
  }
}
```

#### Get Certification

Retrieves a specific certification.

**URL**: `/api/agent/certifications/{id}`

**Method**: `GET`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the certification   |

**Response**:

```json
{
  "data": {
    "id": 1,
    "name": "Referral Specialist",
    "description": "Certification for agents who have mastered the referral system",
    "badge_image": "https://example.com/badges/referral-specialist.png",
    "required_training_count": 5,
    "completed_training_count": 3,
    "status": "in-progress",
    "progress_percentage": 60,
    "earned_at": null,
    "requirements": [
      {
        "id": 1,
        "training_material_id": 1,
        "training_material_title": "Introduction to Referrals",
        "completed": true,
        "completed_at": "2023-01-15T10:30:00Z"
      },
      {
        "id": 2,
        "training_material_id": 2,
        "training_material_title": "Advanced Referral Techniques",
        "completed": true,
        "completed_at": "2023-01-16T14:45:00Z"
      },
      {
        "id": 3,
        "training_material_id": 3,
        "training_material_title": "Referral Compliance",
        "completed": true,
        "completed_at": "2023-01-17T09:15:00Z"
      },
      {
        "id": 4,
        "training_material_id": 4,
        "training_material_title": "Referral Marketing",
        "completed": false,
        "completed_at": null
      },
      {
        "id": 5,
        "training_material_id": 5,
        "training_material_title": "Referral Analytics",
        "completed": false,
        "completed_at": null
      }
    ],
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

### Training Progress

#### Get Training Progress

Retrieves the agent's training progress.

**URL**: `/api/agent/training/progress`

**Method**: `GET`

**Response**:

```json
{
  "data": {
    "total_materials": 20,
    "completed_materials": 12,
    "progress_percentage": 60,
    "total_required_materials": 15,
    "completed_required_materials": 10,
    "required_progress_percentage": 67,
    "total_certifications": 5,
    "earned_certifications": 2,
    "certification_progress_percentage": 40,
    "recent_activity": [
      {
        "id": 1,
        "type": "training_completed",
        "training_material_id": 12,
        "training_material_title": "Customer Relationship Management",
        "completed_at": "2023-01-20T15:30:00Z"
      },
      {
        "id": 2,
        "type": "quiz_passed",
        "training_material_id": 10,
        "training_material_title": "Compliance Training",
        "score": 90,
        "completed_at": "2023-01-19T11:45:00Z"
      },
      {
        "id": 3,
        "type": "certification_earned",
        "certification_id": 2,
        "certification_name": "Compliance Specialist",
        "earned_at": "2023-01-18T09:00:00Z"
      }
      // More activity...
    ]
  }
}
```

## Error Responses

### 401 Unauthorized

```json
{
  "error": "Unauthorized",
  "message": "Authentication token is invalid or expired"
}
```

### 403 Forbidden

```json
{
  "error": "Forbidden",
  "message": "You do not have permission to access this resource"
}
```

### 404 Not Found

```json
{
  "error": "Not Found",
  "message": "The requested resource was not found"
}
```

### 422 Validation Error

```json
{
  "error": "Validation Error",
  "message": "The given data was invalid",
  "errors": {
    "answers": [
      "The answers field is required"
    ],
    "answers.1": [
      "The selected answer is invalid"
    ]
  }
}
```

### 500 Server Error

```json
{
  "error": "Server Error",
  "message": "An unexpected error occurred"
}
```