website/VIRTFUSION_V6_INTEGRATION.md

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

GET /connect
Authorization: Bearer {token}

Response: Returns VirtFusion version and connection status

Create Server

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

GET /servers/{serverId}
Authorization: Bearer {token}

Response: Full server details including state, suspended status, traffic, etc.

Suspend Server

POST /servers/{serverId}/suspend
Authorization: Bearer {token}

Response: 204 No Content on success

Unsuspend Server

POST /servers/{serverId}/unsuspend
Authorization: Bearer {token}

Response: 204 No Content on success

Delete Server

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:

{
  "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