Integra tu software con la API del Manager

La API del Manager es la misma que usa el propio panel: todo lo que puedes hacer desde la web (crear y gestionar VPS, encenderlos y apagarlos, firewall, IPs, backups, facturación, tickets...) está disponible como llamadas HTTP con respuestas JSON, listo para integrarlo en tu propio software.

La referencia interactiva

Con tu sesión iniciada en el Manager, abre https://manager.ginernet.com/api: es la referencia completa de la API para clientes (Swagger UI), con más de 300 operaciones organizadas por categorías, cada una con sus parámetros, cuerpo de petición y respuestas. Desde ahí puedes incluso probar llamadas reales con tu propia sesión.

La especificación OpenAPI en formato máquina está en https://manager.ginernet.com/api/doc.json: puedes importarla en Postman o generar un cliente para tu lenguaje con herramientas como openapi-generator. Es accesible con sesión o con un token de API.

Autenticación: tokens de API (recomendado)

La forma recomendada de autenticar tu integración es con un token de API: una credencial que va atada a tu cuenta de cliente y que se envía en cada petición con la cabecera Authorization. Sin usuario, sin contraseña, sin 2FA y sin cookies.

Los tokens se crean en el Manager, en Acceso API (menú lateral). Al crearlo eliges:

• IPs permitidas (recomendado): una lista de IPs o rangos CIDR desde los que el token puede usarse. Cualquier petición desde otra IP se rechaza, así que un token filtrado no sirve de nada fuera de tus servidores.
• Solo lectura: el token solo puede consultar información; ninguna escritura.
• Operaciones sensibles: por defecto un token no puede ejecutar operaciones marcadas como sensibles (revelar credenciales, gestionar accesos, cambios de titularidad...). Actívalo solo si tu integración lo necesita.
• Caducidad opcional.

El token se muestra una sola vez al crearlo (empieza por gcpr_); guárdalo en un gestor de secretos. Usarlo es una cabecera:

curl -H 'Authorization: Bearer gcpr_TU_TOKEN' https://manager.ginernet.com/api/vps

Con token no hay sesión ni contexto que fijar: el token ya sabe a qué cliente pertenece, y las escrituras no necesitan la cabecera Origin (eso es una protección para las sesiones con cookie).

Si una llamada devuelve 401 con token, el token es inválido, ha caducado, ha sido revocado o llega desde una IP no permitida (el mensaje lo indica). Un 403 significa que la operación existe pero ese token no puede ejecutarla (es de solo lectura, o la operación es sensible y el token no lo permite).

Alternativa: sesión con cookie

La API también acepta la misma sesión que usa el panel, pensada para cuando pruebas llamadas desde la referencia interactiva. Resumen del flujo, si la necesitas:

1. POST /api/auth/login con {"identifier": "...", "password": "..."}. Guarda las cookies de la respuesta y reenvíalas en cada llamada. Si el usuario tiene passkey o TOTP, el login exige el segundo factor (step distinto de complete), que un script no puede completar en el caso de la passkey.
2. Toda escritura (POST, PUT, PATCH, DELETE) debe llevar la cabecera Origin: https://manager.ginernet.com (protección CSRF).
3. Fija el cliente activo antes de operar servicios: GET /api/me devuelve accessibleClients y POST /api/auth/context con {"clientId": <id>} lo selecciona.
4. La sesión caduca a los 60 minutos de inactividad: ante un 401, vuelve a hacer login.

Para integraciones de verdad, usa tokens: no dependen de contraseñas, no caducan por inactividad y puedes limitarlos por IP y permisos.

Cómo está organizada la API

Las operaciones se agrupan por categorías. Las principales:

La lista completa, operación a operación, está en la referencia interactiva.

Operaciones asíncronas: las tasks

Todo lo que no es inmediato (crear un VPS, redimensionar, reinstalar, hacer un backup...) devuelve una task. La respuesta incluye su id; consulta el progreso con GET /api/tasks/{id} hasta que status sea succeeded o failed. Sondea cada 10-20 segundos, no en bucle cerrado.

Errores y límites

• Los errores 4xx devuelven {"message": "..."}, a veces con code y details. Un 404 también significa que el recurso no pertenece a tu cliente.
• Los errores 5xx devuelven un mensaje genérico con un errorId: guárdalo e inclúyelo si abres un ticket de soporte.
• Hay limitación de intentos: un 429 significa demasiadas peticiones; espera antes de reintentar. Los intentos fallidos de autenticación con token también se limitan por IP.

Ejemplo completo en PHP

Un script mínimo que lista tus VPS con su estado y su IP principal, usando un token de API:

<?php

// Ejemplo mínimo: lista tus VPS usando un token de API del Manager.
// Requisitos: PHP 8 o superior con la extensión curl.
// Crea el token en el Manager: Acceso API -> Crear token.

const BASE_URL  = 'https://manager.ginernet.com';
const API_TOKEN = 'gcpr_TU_TOKEN'; // mejor desde una variable de entorno

function api(string $method, string $path, ?array $body = null): array
{
    $headers = [
        'Accept: application/json',
        'Authorization: Bearer ' . API_TOKEN,
    ];

    $ch = curl_init(BASE_URL . $path);
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }

    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
    ]);

    $response = (string) curl_exec($ch);
    $status   = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    $data = json_decode($response, true);
    if (!is_array($data)) {
        $data = [];
    }
    if ($status >= 400) {
        throw new RuntimeException(
            "HTTP $status en $method $path: " . ($data['message'] ?? $response)
        );
    }

    return $data;
}

// El token ya va atado a tu cuenta de cliente: sin login ni contexto.
$result = api('GET', '/api/vps');
foreach ($result['items'] as $vps) {
    printf(
        "#%-5d %-25s %-10s %s\n",
        $vps['id'],
        $vps['name'],
        $vps['powerState'],
        $vps['primaryIpAddress']['ipAddress'] ?? 'sin IP',
    );
}

Guárdalo como listar-vps.php, pon tu token y ejecútalo con php listar-vps.php.

Buenas prácticas

• Limita el token por IP: es la protección más efectiva. Un token restringido a las IPs de tus servidores no sirve de nada si se filtra.
• Mínimo permiso necesario: si tu integración solo consulta, crea el token de solo lectura. Deja las operaciones sensibles desactivadas salvo que las necesites.
• El token, fuera del código: cárgalo de una variable de entorno o de un gestor de secretos, nunca en el repositorio. Si se te escapa en un commit, revócalo en el momento desde Acceso API y crea otro.
• Un token por integración: así puedes revocar uno sin romper el resto, y en la columna «Último uso» ves desde qué IP trabaja cada uno.
• Ojo con las operaciones con coste: crear VPS, redimensionar o contratar licencias se cobra del saldo prepago de la cuenta en el momento, y los borrados son irreversibles. Prueba tu integración con lecturas antes de automatizar escrituras.

¿Conectas un agente de IA?

Si lo que quieres conectar es un agente de IA (Claude, Cursor, etc.), no uses la API REST: el Manager tiene un servidor MCP con claves API dedicadas y límites de gasto configurables. Consulta Despliega VPS con IA: servidor MCP.