Referință API REST

Q: Ce metodă de autentificare să folosesc?

O cheie API (X-API-Key) pentru tot ce este automatizat. Calea POST /api/sdk/token funcționează doar pentru conturile create cu e-mail și parolă, iar tokenul ei expiră după o oră.

Q: Cum evit să fiu taxat de două ori la o reîncercare?

Trimiteți o idempotency_key odată cu cererea de calcul. O repetare cu aceeași cheie returnează rezultatul memorat, cu meta.replayed: true, în loc să recalculeze, iar o repetare simultană returnează 409.

Fiecare punct final de mai jos poate fi apelat din orice limbaj prin HTTP simplu. Mărimile modelului sunt în unități de bază SI — metri, newtoni și pascali. Specificația completă, citibilă de mașini, este livrată ca OpenAPI 3.1 și poate fi importată direct într-un generator de clienți sau într-o Action de GPT personalizat ChatGPT.

Specificația citibilă de mașini

Specificația completă se află la ferscloud.com/api/openapi.json, în format OpenAPI 3.1. Este livrată cu CORS permisiv și este permisă explicit în robots.txt, astfel încât uneltele și agenții o pot descărca direct.

Autentificați-vă fie cu antetul X-API-Key (o cheie permanentă din pagina de profil), fie cu un token Bearer obținut prin POST /api/sdk/token. Varianta cu cheie funcționează pentru orice metodă de autentificare; cea cu token doar pentru conturile cu e-mail și parolă.

# 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

Autentificare și chei API

Creați o cheie o singură dată, păstrați-o pe server și trimiteți-o ca X-API-Key la fiecare cerere. Cheile sunt afișate doar la creare și pot fi revocate oricând.

POST /api/sdk/token — Obținerea unui JWT de scurtă durată

{
  "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 — Verificarea unei chei și datele utilizatorului

{
  "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 — Crearea unei chei 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 — Listarea cheilor 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> — Revocarea unei chei 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 și check-beam sunt contorizate: fiecare apel reușit consumă unul dintre cele 100 calcule gratuite săptămânale, apoi credit preplătit la 0,01 € pe calcul. validate este gratuit și necontorizat.

Sunt echivalentele REST ale uneltelor MCP solve_model și check_beam, deci un agent și un script parcurg exact aceeași cale de cod.

POST /api/sdk/solve — Rularea solverului cu elemente finite

{
  "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 — Verificarea unui model fără a-l calcula

{
  "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 — Verificare de oțel EN 1993-1-1, gata de utilizat

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

Un apel complet

Verificarea de grindă gata de utilizat este cea mai rapidă cale de a confirma că cheia funcționează — construiește, calculează și verifică o deschidere într-o singură cerere.

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
  }'

Unitățile acestui punct final sunt pragmatice, nu SI: span_m în metri, udl în kN/m și point_load în kN, în jos. Punctele finale pentru modele lucrează integral în SI.

Modele salvate

Stocarea în cloud este o funcție Pro. În planul gratuit păstrați modelele ca JSON local — același format pe care aceste puncte finale îl acceptă și îl returnează.

GET /api/sdk/models — Listarea modelelor salvate

{
  "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 — Salvarea unui model nou

{
  "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} — Descărcarea unui model

{
  "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} — Actualizarea unui model

{
  "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} — Ștergerea unui model

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

Răspunsuri de eroare

Punctele finale contorizate folosesc coduri de stare HTTP pentru a distinge motivele pentru care un apel nu s-a executat, astfel încât un client să poată reîncerca inteligent, în loc să trateze la fel toate eșecurile.

Stare	Cod	Semnificație
422	`solver_error`	Modelul a ajuns la solver și nu a putut fi rezolvat.
402	`insufficient_credit`	Cota gratuită epuizată și fără credit preplătit.
429	`daily_limit` / `rate_limited`	Cotă sau limită de frecvență atinsă. Așteptați și reîncercați.
409	`in_flight`	O cerere cu aceeași `idempotency_key` este deja în curs.

Transmiteți o idempotency_key către solve, astfel încât o cerere reîncercată să fie redată, nu taxată de două ori; câmpul meta.replayed din răspuns arată ce s-a întâmplat.

Alte căi de acces

Server MCP — aceleași capabilități, ca unelte pe care un agent AI le poate apela direct.
Pachetul JavaScript — calcul în browser, fără niciun apel HTTP.
Pachetul Python — construirea modelelor cu obiecte, nu cu JSON brut.

Pagini conexe

Folosirea FERS din JavaScript

Instalați solverul WebAssembly de pe npm, configurați bundlerul și calculați modele în browser sau în Node.

Exemple rezolvate

Patru scripturi executabile — consolă, grindă simplu rezemată, cadru și o verificare EN 1993-1-1 — fiecare cu calculul manual.

Vezi și

Întrebări frecvente

Ce metodă de autentificare să folosesc?

O cheie API (X-API-Key) pentru tot ce este automatizat. Calea POST /api/sdk/token funcționează doar pentru conturile create cu e-mail și parolă, iar tokenul ei expiră după o oră.

Ce unități folosește JSON-ul modelului?

Unități de bază SI: metri, newtoni și pascali; unghiuri în grade. Punctul final de conveniență check-beam face excepție — acesta primește metri, kN/m și kN.

Cât costă un apel?

100 calcule reușite pe săptămână glisantă sunt gratuite. Peste această limită, 0,01 € pe calcul din credit preplătit sau nelimitat cu Pro, la 19.95 € pe lună. validate și punctele finale pentru chei nu sunt niciodată contorizate.

Pot importa acest lucru în ChatGPT sau Postman?

Da. /api/openapi.json este un document OpenAPI 3.1 complet, gândit să fie importat ca Action de GPT personalizat ChatGPT sau în orice unealtă OpenAPI.

Cum evit să fiu taxat de două ori la o reîncercare?

Trimiteți o idempotency_key odată cu cererea de calcul. O repetare cu aceeași cheie returnează rezultatul memorat, cu meta.replayed: true, în loc să recalculeze, iar o repetare simultană returnează 409.

Există o limită de frecvență?

Da, pe cont și pe minut, pentru a opri o buclă de agent scăpată de sub control. Depășirea returnează 429 cu rate_limited; așteptați și reîncercați.