Referencia de la API REST

Q: ¿Qué método de autenticación debo usar?

Una clave de API (X-API-Key) para todo lo automatizado. La vía POST /api/sdk/token solo funciona en cuentas creadas con correo y contraseña, y su token caduca en una hora.

Q: ¿Cómo evito que me cobren dos veces por un reintento?

Envíe un idempotency_key con la petición de cálculo. Una repetición con la misma clave devuelve el resultado almacenado con meta.replayed: true en vez de volver a calcular, y una repetición concurrente devuelve 409.

Todos los puntos finales de abajo se pueden invocar desde cualquier lenguaje por HTTP simple. Las magnitudes del modelo van en unidades básicas del SI: metros, newtons y pascales. La especificación completa legible por máquina se sirve como OpenAPI 3.1 y puede importarse directamente en un generador de clientes o en una Action de un GPT personalizado de ChatGPT.

La especificación legible por máquina

La especificación completa está en ferscloud.com/api/openapi.json, en formato OpenAPI 3.1. Se sirve con CORS permisivo y está explícitamente permitida en robots.txt, de modo que herramientas y agentes pueden descargarla directamente.

Autentíquese con la cabecera X-API-Key (una clave permanente de su página de perfil) o con un token Bearer de POST /api/sdk/token. La forma con clave funciona con cualquier método de acceso; la del token, solo con cuentas de correo y contraseña.

# The complete machine-readable spec (OpenAPI 3.1).
# Import it into ChatGPT Custom GPT Actions, Postman, or a client generator.
curl https://ferscloud.com/api/openapi.json

Autenticación y claves de API

Cree una clave una vez, guárdela en el servidor y envíela como X-API-Key en cada petición. Las claves se muestran una sola vez al crearlas y pueden revocarse en cualquier momento.

POST /api/sdk/token — Obtener un JWT de corta duración

{
  "description": "Exchange email + password for a 1-hour Bearer token. Requires an email/password account. Google/GitHub users should use an API key (X-API-Key header) instead.",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/token",
    "body": {
      "email": "you@example.com",
      "password": "your_password"
    }
  },
  "response": {
    "token": "<jwt>",
    "expires_at": "2025-01-01T01:00:00Z",
    "is_premium": false,
    "user": {
      "id": "<uuid>",
      "email": "you@example.com"
    }
  }
}

GET /api/sdk/me — Verificar una clave y obtener datos del usuario

{
  "description": "Check the currently authenticated SDK user. Works with both X-API-Key and Bearer token.",
  "request": {
    "method": "GET",
    "url": "https://ferscloud.com/api/sdk/me",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "user_id": "<uuid>",
    "email": "you@example.com",
    "is_premium": false,
    "token_expires_at": "2026-01-01T01:00:00.000Z"
  }
}

POST /api/sdk/api-keys — Crear una clave de API permanente

{
  "description": "Create a named API key (returned once, store it securely). Optionally set expiresInDays for auto-expiry.",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/api-keys",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "name": "My laptop",
      "scopes": [],
      "expiresInDays": null
    }
  },
  "response": {
    "id": "<keyId>",
    "name": "My laptop",
    "key": "<keyId>.<secret>",
    "scopes": [],
    "created_at": "2026-01-01T00:00:00.000Z",
    "expires_at": null,
    "message": "Store this key securely. It will not be shown again."
  }
}

GET /api/sdk/api-keys — Listar claves de API

{
  "description": "List all active (non-revoked) API keys. Secrets are never returned.",
  "request": {
    "method": "GET",
    "url": "https://ferscloud.com/api/sdk/api-keys",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "keys": [
      {
        "id": "<keyId>",
        "name": "My laptop",
        "scopes": [],
        "createdAt": "2026-01-01T00:00:00.000Z",
        "lastUsedAt": null,
        "expiresAt": null
      }
    ]
  }
}

DELETE /api/sdk/api-keys?id=<keyId> — Revocar una clave de API

{
  "description": "Revoke an API key by its ID. Pass the key ID as a query parameter, not a path segment.",
  "request": {
    "method": "DELETE",
    "url": "https://ferscloud.com/api/sdk/api-keys?id=<keyId>",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "message": "API key revoked"
  }
}

Solver

solve y check-beam se miden: cada llamada correcta consume uno de sus 100 cálculos gratuitos semanales y, a partir de ahí, saldo prepago a 0,01 € por cálculo. validate es gratuito y no se mide.

Son los gemelos REST de las herramientas MCP solve_model y check_beam, de modo que un agente y un script recorren exactamente el mismo camino de código.

POST /api/sdk/solve — Ejecutar el solver de elementos finitos

{
  "description": "Solve a FERS model JSON (SI units: metres, newtons, pascals) and get displacements, member forces and reactions. Metered: uses your weekly free solves or prepaid credits (Pro: unlimited). REST twin of the MCP solve_model tool. Errors: 422 solver_error, 402 insufficient_credit, 429 daily_limit / rate_limited, 409 in_flight (same idempotency_key already running).",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/solve",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "model": "<FERS model JSON object or string>",
      "idempotency_key": "optional-unique-id"
    }
  },
  "response": {
    "result": "<solver results: displacements, member forces, reactions, unity checks>",
    "meta": {
      "funding": "free_tier",
      "cost_cents": 0,
      "balance_cents": 0,
      "replayed": false
    }
  }
}

POST /api/sdk/validate — Revisar un modelo sin calcularlo

{
  "description": "Validate a FERS model JSON's structure (required keys, basic integrity) without running the solver. Free and unmetered.",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/validate",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "model": "<FERS model JSON object or string>"
    }
  },
  "response": {
    "valid": false,
    "errors": [
      "Missing required key: \"model.materials\""
    ]
  }
}

POST /api/sdk/check-beam — Comprobación de acero EN 1993-1-1 llave en mano

{
  "description": "Build a single-span steel beam, solve it, and return the EN 1993-1-1 utilizations (bending, shear, N+M, lateral-torsional buckling). Units: span_m in metres, udl in kN/m, point_load in kN (downward). Counts as one solve. REST twin of the MCP check_beam tool. The example below reproduces the published IPE 400 worked example.",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/check-beam",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "span_m": 7.5,
      "section": "IPE400",
      "material": "steel_S355",
      "udl": 13,
      "uls_factor": 1.35,
      "restrained": false
    }
  },
  "response": {
    "check": {
      "section": "IPE400",
      "span_m": 7.5,
      "status": "Yellow",
      "governing_utilization": 0.822,
      "governing_check": "LTB (6.3.2)",
      "passes": true,
      "checks": {
        "Bending z (6.2.5)": 0.266,
        "Shear y (6.2.6)": 0.071,
        "Combined N+M (6.2.1)": 0.266,
        "LTB (6.3.2)": 0.822
      },
      "advice": "Passes (UC 0.822) with lateral-torsional buckling governing. …"
    },
    "meta": {
      "funding": "free_tier",
      "cost_cents": 0,
      "balance_cents": 0,
      "replayed": false
    }
  }
}

Una llamada completa

La comprobación de viga llave en mano es la forma más rápida de confirmar que su clave funciona: construye, calcula y comprueba un vano en una sola petición.

curl -X POST https://ferscloud.com/api/sdk/check-beam \
  -H "X-API-Key: <keyId>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "span_m": 7.5,
    "section": "IPE400",
    "material": "steel_S355",
    "udl": 13,
    "uls_factor": 1.35,
    "restrained": false
  }'

Las unidades de este punto final son pragmáticas en lugar de SI: span_m en metros, udl en kN/m y point_load en kN hacia abajo. Los puntos finales de modelo trabajan en SI de principio a fin.

Modelos guardados

El almacenamiento en la nube es una función Pro. En el plan gratuito conserve los modelos como JSON local: es el mismo formato que estos puntos finales aceptan y devuelven.

GET /api/sdk/models — Listar modelos guardados

{
  "description": "List all models saved to the authenticated account",
  "request": {
    "method": "GET",
    "url": "https://ferscloud.com/api/sdk/models",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "models": [
      {
        "id": "<modelId>",
        "name": "My cantilever",
        "description": null,
        "createdAt": "2025-01-01T00:00:00Z",
        "updatedAt": "2025-01-01T00:00:00Z"
      }
    ]
  }
}

POST /api/sdk/models — Guardar un modelo nuevo

{
  "description": "Save a structural model JSON to your account",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/models",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "name": "My cantilever",
      "description": "5 m IPE 180 cantilever with −1 kN tip load",
      "model": "<model JSON object>"
    }
  },
  "response": {
    "id": "<modelId>",
    "name": "My cantilever",
    "description": "5 m IPE 180 cantilever with −1 kN tip load",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

GET /api/sdk/models/{id} — Descargar un modelo

{
  "description": "Retrieve the full model JSON for a saved model",
  "request": {
    "method": "GET",
    "url": "https://ferscloud.com/api/sdk/models/<modelId>",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "id": "<modelId>",
    "name": "My cantilever",
    "description": null,
    "model": "<full model JSON object>",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
  }
}

PUT /api/sdk/models/{id} — Actualizar un modelo

{
  "description": "Update the name, description, and/or JSON of an existing model. Send only the fields you want to change.",
  "request": {
    "method": "PUT",
    "url": "https://ferscloud.com/api/sdk/models/<modelId>",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "name": "Updated name"
    }
  },
  "response": {
    "id": "<modelId>",
    "name": "Updated name",
    "description": null,
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-02T00:00:00Z"
  }
}

DELETE /api/sdk/models/{id} — Eliminar un modelo

{
  "description": "Permanently delete a saved model",
  "request": {
    "method": "DELETE",
    "url": "https://ferscloud.com/api/sdk/models/<modelId>",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": "204 No Content"
}

Respuestas de error

Los puntos finales medidos usan códigos de estado HTTP para distinguir por qué no se ejecutó una llamada, de modo que un cliente pueda reintentar con criterio en lugar de tratar todos los fallos igual.

Estado	Código	Significado
422	`solver_error`	El modelo llegó al solver y no pudo resolverse.
402	`insufficient_credit`	Cuota gratuita agotada y sin saldo prepago.
429	`daily_limit` / `rate_limited`	Cuota o límite de frecuencia alcanzado. Espere y reintente.
409	`in_flight`	Ya se está ejecutando una petición con el mismo `idempotency_key`.

Pase un idempotency_key en solve para que un reintento se reproduzca en lugar de cobrarse dos veces; el campo meta.replayed de la respuesta indica qué ocurrió.

Otras vías

Servidor MCP: las mismas capacidades como herramientas que un agente de IA puede invocar directamente.
Paquete de JavaScript: calcular en el navegador sin ninguna llamada HTTP.
Paquete de Python: construir modelos con objetos en lugar de JSON en bruto.

Páginas relacionadas

Usar FERS desde JavaScript

Instale el solver WebAssembly desde npm, configure su empaquetador y calcule modelos en el navegador o en Node.

Ejemplos resueltos

Cuatro scripts ejecutables — ménsula, viga biapoyada, pórtico y comprobación según EN 1993-1-1 — cada uno con su cálculo manual.

Véase también

Preguntas frecuentes

¿Qué método de autenticación debo usar?

Una clave de API (X-API-Key) para todo lo automatizado. La vía POST /api/sdk/token solo funciona en cuentas creadas con correo y contraseña, y su token caduca en una hora.

¿Qué unidades usa el JSON del modelo?

Unidades básicas del SI: metros, newtons y pascales; ángulos en grados. El punto final de conveniencia check-beam es la excepción: toma metros, kN/m y kN.

¿Cuánto cuesta una llamada?

100 cálculos correctos por semana móvil son gratuitos. A partir de ahí, 0,01 € por cálculo con saldo prepago, o ilimitados con Pro por 19.95 € al mes. validate y los puntos finales de claves nunca se miden.

¿Puedo importar esto en ChatGPT o Postman?

Sí. /api/openapi.json es un documento OpenAPI 3.1 completo, pensado para importarse como Action de un GPT personalizado de ChatGPT o en cualquier herramienta OpenAPI.

¿Cómo evito que me cobren dos veces por un reintento?

Envíe un idempotency_key con la petición de cálculo. Una repetición con la misma clave devuelve el resultado almacenado con meta.replayed: true en vez de volver a calcular, y una repetición concurrente devuelve 409.

¿Hay límite de frecuencia?

Sí, por cuenta y por minuto, para frenar un bucle de agente desbocado. Al superarlo se devuelve 429 con rate_limited; espere y reintente.