# VirtFusion V6 API Integration

## Overview
EZSCALE uses VirtFusion V6 for VPS provisioning and management. This document outlines the correct API endpoints and parameters.

## API Reference
**OpenAPI Spec**: `virtfusion-api-spec.yaml` (8,309 lines)
**Base URL**: Configured in `.env` as `VIRTFUSION_API_URL`
**Authentication**: Bearer token (configured as `VIRTFUSION_API_TOKEN`)

## Correct API Endpoints (V6)

### Connection Test
```http
GET /connect
Authorization: Bearer {token}
```
**Response**: Returns VirtFusion version and connection status

### Create Server
```http
POST /servers
Content-Type: application/json
Authorization: Bearer {token}

{
  "packageId": 1,        // Required: VirtFusion package ID
  "userId": 1,           // Required: VirtFusion user ID (not email!)
  "hypervisorId": 1      // Required: Hypervisor group ID
}
```
**Response**: Returns server object with ID, UUID, state, IP addresses, etc.

### Get Server Details
```http
GET /servers/{serverId}
Authorization: Bearer {token}
```
**Response**: Full server details including state, suspended status, traffic, etc.

### Suspend Server
```http
POST /servers/{serverId}/suspend
Authorization: Bearer {token}
```
**Response**: 204 No Content on success

### Unsuspend Server
```http
POST /servers/{serverId}/unsuspend
Authorization: Bearer {token}
```
**Response**: 204 No Content on success

### Delete Server
```http
DELETE /servers/{serverId}?delay=0
Authorization: Bearer {token}
```
**Query Parameters**:
- `delay`: Minutes to wait before deletion (0-43800), optional

**Response**: 204 No Content on success

## Plan Configuration

VPS plans in the database need these feature keys:

```json
{
  "virtfusion_package_id": 1,      // Required: VirtFusion package ID
  "virtfusion_user_id": 1,         // Required: VirtFusion user ID for server owner
  "virtfusion_hypervisor_id": 1    // Required: Hypervisor group ID
}
```

## Key Differences from Other Versions

1. **No `/api/v1` prefix** - V6 endpoints start directly with resource names
2. **camelCase parameters** - Use `packageId` not `package_id`
3. **userId not email** - Must provide VirtFusion user ID, not email address
4. **Suspend returns 204** - No response body, check for 204 status code

## Implementation Files

- **Service**: `app/Services/Provisioning/VirtFusionService.php`
- **Settings Controller**: `app/Http/Controllers/Admin/SettingsController.php` (testVirtFusion method)
- **Config**: `config/services.php` (virtfusion section)

## Testing

Test connection via Admin Settings page:
1. Navigate to Admin → Settings → API Credentials
2. Enter VirtFusion API URL and Token
3. Click "Test Connection"
4. Should return: "VirtFusion connection successful. Version: X.X.X"

## API Restrictions

According to deployment notes, the VirtFusion API token is restricted to:
- ✅ Create server
- ✅ Create user
- ✅ Authenticate user

Ensure the token has appropriate permissions for these operations.

## Troubleshooting

### 404 Errors
- ❌ Using `/api/v1/servers` (old format)
- ✅ Use `/servers` (V6 format)

### 400 Bad Request
- Check parameter names are camelCase (`packageId` not `package_id`)
- Ensure `userId` is an integer, not an email
- Verify `packageId` and `hypervisorId` exist in VirtFusion

### 401 Unauthorized
- Verify `VIRTFUSION_API_TOKEN` is correct
- Check token has required permissions
- Ensure `Authorization: Bearer` header is included

### Server Creation Fails
- Verify plan features include `virtfusion_package_id`, `virtfusion_user_id`, and `virtfusion_hypervisor_id`
- Check VirtFusion has available resources (RAM, storage, IP addresses)
- Review `provisioning_logs` table for detailed error messages

## Related Documentation

- VirtFusion Official Docs: https://docs.virtfusion.com/api/
- OpenAPI Spec: `/virtfusion-api-spec.yaml`
- Project Integration: `CLAUDE.md` → Provisioning Services section