# Agent Goals & Reports API Documentation

This document provides API documentation for the Goals & Reports 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

### Goals

#### List Goals

Retrieves a list of agent goals.

**URL**: `/api/agent/goals`

**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)           |
| type      | string | No       | Filter by type (commissions, referrals)          |
| status    | string | No       | Filter by status (active, achieved, expired)     |

**Response**:

```json
{
  "data": [
    {
      "id": 1,
      "type": "commissions",
      "target_value": 5000,
      "target_date": "2023-03-31",
      "description": "Earn $5000 in commissions in Q1",
      "status": "active",
      "progress_value": 3200,
      "progress_percentage": 64,
      "days_remaining": 45,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "type": "referrals",
      "target_value": 20,
      "target_date": "2023-02-28",
      "description": "Get 20 referrals in February",
      "status": "active",
      "progress_value": 12,
      "progress_percentage": 60,
      "days_remaining": 15,
      "created_at": "2023-01-15T00:00:00Z",
      "updated_at": "2023-01-15T00:00:00Z"
    },
    // More goals...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "/api/agent/goals",
    "per_page": 10,
    "to": 2,
    "total": 2,
    "active_count": 2,
    "achieved_count": 0,
    "expired_count": 0
  }
}
```

#### Get Goal

Retrieves a specific goal.

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

**Method**: `GET`

**URL Parameters**:

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

**Response**:

```json
{
  "data": {
    "id": 1,
    "type": "commissions",
    "target_value": 5000,
    "target_date": "2023-03-31",
    "description": "Earn $5000 in commissions in Q1",
    "status": "active",
    "progress_value": 3200,
    "progress_percentage": 64,
    "days_elapsed": 45,
    "days_remaining": 45,
    "achieved_at": null,
    "progress_history": [
      {
        "date": "2023-01-15",
        "value": 1000,
        "percentage": 20
      },
      {
        "date": "2023-01-31",
        "value": 2200,
        "percentage": 44
      },
      {
        "date": "2023-02-15",
        "value": 3200,
        "percentage": 64
      }
    ],
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-02-15T00:00:00Z"
  }
}
```

#### Create Goal

Creates a new goal.

**URL**: `/api/agent/goals`

**Method**: `POST`

**Request Body**:

```json
{
  "type": "commissions",
  "target_value": 10000,
  "target_date": "2023-06-30",
  "description": "Earn $10,000 in commissions in Q2"
}
```

**Response**:

```json
{
  "message": "Goal created successfully",
  "data": {
    "id": 3,
    "type": "commissions",
    "target_value": 10000,
    "target_date": "2023-06-30",
    "description": "Earn $10,000 in commissions in Q2",
    "status": "active",
    "progress_value": 0,
    "progress_percentage": 0,
    "days_elapsed": 0,
    "days_remaining": 130,
    "created_at": "2023-02-21T00:00:00Z",
    "updated_at": "2023-02-21T00:00:00Z"
  }
}
```

#### Update Goal

Updates an existing goal.

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

**Method**: `PUT`

**URL Parameters**:

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

**Request Body**:

```json
{
  "target_value": 12000,
  "target_date": "2023-06-30",
  "description": "Earn $12,000 in commissions in Q2"
}
```

**Response**:

```json
{
  "message": "Goal updated successfully",
  "data": {
    "id": 3,
    "type": "commissions",
    "target_value": 12000,
    "target_date": "2023-06-30",
    "description": "Earn $12,000 in commissions in Q2",
    "status": "active",
    "progress_value": 0,
    "progress_percentage": 0,
    "days_elapsed": 0,
    "days_remaining": 130,
    "created_at": "2023-02-21T00:00:00Z",
    "updated_at": "2023-02-21T01:00:00Z"
  }
}
```

#### Delete Goal

Deletes a goal.

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

**Method**: `DELETE`

**URL Parameters**:

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

**Response**:

```json
{
  "message": "Goal deleted successfully"
}
```

### Reports

#### List Custom Reports

Retrieves a list of custom reports.

**URL**: `/api/agent/reports`

**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)           |
| type      | string | No       | Filter by type (commission, referral, performance) |

**Response**:

```json
{
  "data": [
    {
      "id": 1,
      "name": "Monthly Commission Report",
      "type": "commission",
      "is_scheduled": true,
      "schedule_frequency": "monthly",
      "last_generated_at": "2023-02-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-02-01T00:00:00Z"
    },
    {
      "id": 2,
      "name": "Weekly Referral Report",
      "type": "referral",
      "is_scheduled": true,
      "schedule_frequency": "weekly",
      "last_generated_at": "2023-02-14T00:00:00Z",
      "created_at": "2023-01-15T00:00:00Z",
      "updated_at": "2023-02-14T00:00:00Z"
    },
    // More reports...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "/api/agent/reports",
    "per_page": 10,
    "to": 2,
    "total": 2
  }
}
```

#### Get Custom Report

Retrieves a specific custom report.

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

**Method**: `GET`

**URL Parameters**:

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

**Response**:

```json
{
  "data": {
    "id": 1,
    "name": "Monthly Commission Report",
    "type": "commission",
    "columns": ["created_at", "amount", "status", "source"],
    "filters": {
      "date_from": "2023-01-01",
      "date_to": "2023-01-31",
      "status": "paid"
    },
    "sorting": [
      {
        "column": "created_at",
        "direction": "desc"
      }
    ],
    "is_scheduled": true,
    "schedule_frequency": "monthly",
    "schedule_time": "09:00",
    "last_generated_at": "2023-02-01T00:00:00Z",
    "exports": [
      {
        "id": 1,
        "format": "csv",
        "file_path": "exports/1/monthly_commission_report_2023-01.csv",
        "file_size": 1024,
        "generated_at": "2023-02-01T00:00:00Z"
      },
      {
        "id": 2,
        "format": "pdf",
        "file_path": "exports/1/monthly_commission_report_2023-01.pdf",
        "file_size": 2048,
        "generated_at": "2023-02-01T00:00:00Z"
      }
    ],
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-02-01T00:00:00Z"
  }
}
```

#### Create Custom Report

Creates a new custom report.

**URL**: `/api/agent/reports`

**Method**: `POST`

**Request Body**:

```json
{
  "name": "Quarterly Performance Report",
  "type": "performance",
  "columns": ["period", "commission_amount", "referral_count", "conversion_rate", "growth_rate"],
  "filters": {
    "period_type": "quarterly",
    "date_from": "2023-01-01",
    "date_to": "2023-03-31"
  },
  "sorting": [
    {
      "column": "period",
      "direction": "asc"
    }
  ],
  "is_scheduled": true,
  "schedule_frequency": "quarterly",
  "schedule_time": "10:00"
}
```

**Response**:

```json
{
  "message": "Report created successfully",
  "data": {
    "id": 3,
    "name": "Quarterly Performance Report",
    "type": "performance",
    "columns": ["period", "commission_amount", "referral_count", "conversion_rate", "growth_rate"],
    "filters": {
      "period_type": "quarterly",
      "date_from": "2023-01-01",
      "date_to": "2023-03-31"
    },
    "sorting": [
      {
        "column": "period",
        "direction": "asc"
      }
    ],
    "is_scheduled": true,
    "schedule_frequency": "quarterly",
    "schedule_time": "10:00",
    "last_generated_at": null,
    "created_at": "2023-02-21T00:00:00Z",
    "updated_at": "2023-02-21T00:00:00Z"
  }
}
```

#### Update Custom Report

Updates an existing custom report.

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

**Method**: `PUT`

**URL Parameters**:

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

**Request Body**:

```json
{
  "name": "Quarterly Performance Report",
  "columns": ["period", "commission_amount", "referral_count", "conversion_rate", "growth_rate"],
  "filters": {
    "period_type": "quarterly",
    "date_from": "2023-01-01",
    "date_to": "2023-06-30"
  },
  "sorting": [
    {
      "column": "period",
      "direction": "asc"
    }
  ],
  "is_scheduled": true,
  "schedule_frequency": "quarterly",
  "schedule_time": "09:00"
}
```

**Response**:

```json
{
  "message": "Report updated successfully",
  "data": {
    "id": 3,
    "name": "Quarterly Performance Report",
    "type": "performance",
    "columns": ["period", "commission_amount", "referral_count", "conversion_rate", "growth_rate"],
    "filters": {
      "period_type": "quarterly",
      "date_from": "2023-01-01",
      "date_to": "2023-06-30"
    },
    "sorting": [
      {
        "column": "period",
        "direction": "asc"
      }
    ],
    "is_scheduled": true,
    "schedule_frequency": "quarterly",
    "schedule_time": "09:00",
    "last_generated_at": null,
    "created_at": "2023-02-21T00:00:00Z",
    "updated_at": "2023-02-21T01:00:00Z"
  }
}
```

#### Delete Custom Report

Deletes a custom report.

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

**Method**: `DELETE`

**URL Parameters**:

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

**Response**:

```json
{
  "message": "Report deleted successfully"
}
```

#### Generate Report

Generates a report and returns the results.

**URL**: `/api/agent/reports/{id}/generate`

**Method**: `GET`

**URL Parameters**:

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

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| date_from | string | No       | Override start date (YYYY-MM-DD)                 |
| date_to   | string | No       | Override end date (YYYY-MM-DD)                   |

**Response**:

```json
{
  "data": {
    "report_id": 1,
    "name": "Monthly Commission Report",
    "type": "commission",
    "generated_at": "2023-02-21T02:00:00Z",
    "filters_applied": {
      "date_from": "2023-01-01",
      "date_to": "2023-01-31",
      "status": "paid"
    },
    "results": [
      {
        "created_at": "2023-01-30T15:30:00Z",
        "amount": 250.00,
        "status": "paid",
        "source": "referral"
      },
      {
        "created_at": "2023-01-25T10:15:00Z",
        "amount": 150.00,
        "status": "paid",
        "source": "sale"
      },
      // More results...
    ],
    "summary": {
      "total_count": 10,
      "total_amount": 1500.00,
      "average_amount": 150.00,
      "by_source": {
        "referral": 750.00,
        "sale": 500.00,
        "bonus": 250.00
      }
    }
  }
}
```

#### Export Report

Exports a report in the specified format.

**URL**: `/api/agent/reports/{id}/export`

**Method**: `POST`

**URL Parameters**:

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

**Request Body**:

```json
{
  "format": "csv",
  "date_from": "2023-01-01",
  "date_to": "2023-01-31"
}
```

**Response**:

```json
{
  "message": "Report exported successfully",
  "data": {
    "id": 3,
    "report_id": 1,
    "format": "csv",
    "file_path": "exports/1/monthly_commission_report_2023-01.csv",
    "file_size": 1024,
    "download_url": "https://example.com/api/agent/reports/download/3",
    "generated_at": "2023-02-21T03:00:00Z",
    "expires_at": "2023-03-21T03:00:00Z"
  }
}
```

#### Download Report Export

Downloads a previously exported report.

**URL**: `/api/agent/reports/download/{export_id}`

**Method**: `GET`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| export_id | int  | Yes      | ID of the report export   |

**Response**:

The file will be downloaded directly.

### Performance Metrics

#### Get Performance Metrics

Retrieves performance metrics for the agent.

**URL**: `/api/agent/performance`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| period    | string | No       | Time period (week, month, quarter, year, all)    |
| start_date| string | No       | Start date for custom period (YYYY-MM-DD)        |
| end_date  | string | No       | End date for custom period (YYYY-MM-DD)          |

**Response**:

```json
{
  "data": {
    "commissions": {
      "total": 5000.00,
      "count": 20,
      "average": 250.00,
      "by_source": {
        "referral": 3000.00,
        "sale": 1500.00,
        "bonus": 500.00
      },
      "by_status": {
        "pending": 1000.00,
        "paid": 4000.00
      },
      "trend": {
        "labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
        "values": [500, 750, 1000, 1250, 1500, 0]
      }
    },
    "referrals": {
      "total": 30,
      "converted": 18,
      "conversion_rate": 60.0,
      "by_status": {
        "pending": 5,
        "converted": 18,
        "expired": 7
      },
      "trend": {
        "labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
        "values": [3, 5, 7, 8, 7, 0]
      }
    },
    "goals": {
      "total": 5,
      "active": 3,
      "achieved": 1,
      "expired": 1,
      "achievement_rate": 50.0
    },
    "comparison": {
      "commissions": {
        "current": 5000.00,
        "previous": 4000.00,
        "change": 25.0
      },
      "referrals": {
        "current": 30,
        "previous": 25,
        "change": 20.0
      },
      "conversion_rate": {
        "current": 60.0,
        "previous": 56.0,
        "change": 7.1
      }
    }
  }
}
```

## 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": {
    "target_value": [
      "The target value must be a positive number"
    ],
    "target_date": [
      "The target date must be a date after today"
    ]
  }
}
```

### 500 Server Error

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