Contratto API

Rotte per anteprima, conferma dell’inserimento e tavola periodica.

Autenticazione e Origin

Invia X-Formulix-Chave su tutte le rotte /v1/*. La chiave deve essere attiva e l’hostname di Origin deve appartenere ai domini dell’account, inclusi i sottodomini. Origin viene impostato dal browser: non definirlo manualmente in JavaScript. Senza origine valida la chiamata viene rifiutata.

Il preflight OPTIONS accetta origini registrate in un account o di sviluppo, metodi GET/POST e intestazioni Content-Type/X-Formulix-Chave. La chiamata effettiva verifica comunque il dominio dell’account proprietario della chiave. Le risposte usano Vary: Origin e Cache-Control: no-store. L’origine consentita viene riflessa senza carattere jolly. Un’origine rifiutata può apparire solo come errore CORS nel browser.

La chiave è pubblica, non amministrativa; Origin può essere falsificato fuori dai browser. Revoche e modifiche dei domini vengono ricaricate, per impostazione predefinita, in circa 5 secondi.

POST /v1/calc — anteprima

Corpo JSON: { op, dados, idioma, notacao }. op sceglie l’operazione e dados contiene i parametri. Lingua predefinita: en; per l’italiano usa it. notacao è facoltativo, per esempio { "decimal": "," }. La risposta JSON dipende dall’operazione: HTML, LaTeX, SVG o dati ausiliari. Un’anteprima riuscita registra 1 anteprima e 0 inserimenti.

const response = await fetch('https://api.formulix.example/v1/calc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Formulix-Chave': 'YOUR_PUBLIC_KEY'
  },
  body: JSON.stringify({
    op: 'word', dados: { html: '<p>Testo senza equazioni</p>' }, idioma: 'it'
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.erro);
// { eqs: [] }

L’indirizzo di esempio e YOUR_PUBLIC_KEY sono segnaposto. Operazioni riconosciute: divisao, multiplicacao, adicao, subtracao, ruffini, mmc, fatoracao, fracoes, regra3, eq1, eq2, sistema, tabela, estudo, grafico, qeq, qmassa, qdist, qvid, qtit, qpaul, qorg, qcad, qtab, word. I campi di dados variano per operazione: usa l’adattatore per costruire le richieste. Non esiste uno schema unico dei parametri. Gli identificatori API restano invariati.

POST /v1/inserir — risultato finale

Il corpo include tipo, i dati specifici sotto e, facoltativamente, idioma e notacao. La risposta è JSON senza involucro comune.

Esempio di formula; usa le stesse intestazioni dell’anteprima:

{
  "tipo": "formula",
  "latex": "x^2",
  "bloco": false,
  "idioma": "it"
}
// HTTP 200: { "html": "<math ...>...</math>" }

Il client converte SVG in PNG e lo carica tramite la piattaforma. L’API di calcolo non archivia immagini. Ogni conferma accettata conta, anche una modifica; non c’è idempotenza per identificatore. Evita di ripetere automaticamente una conferma se non sai se la prima è stata accettata.

GET /v1/tabela?idioma=it

Restituisce un array { z, s, nome, pos, cor } per la tavola periodica. Richiede chiave e Origin validi anche per questi dati pubblici. Non registra inserimenti o anteprime, ma rispetta il limite al minuto. Lingua predefinita: inglese.

Limiti

• Corpo fino a 15 MiB. Richieste più grandi possono causare la chiusura della connessione dopo la risposta 413.
• 1.200 richieste per chiave al minuto, per processo, incluse anteprime e tavola periodica. Con più processi il tetto non è globale.
• Piano: 500 / 5.000 / 25.000 inserimenti o Rete di scuole senza tetto numerico. Gratuito per account e dominio; a pagamento si somma l’account.
• Sviluppo: tetto separato predefinito di 300 inserimenti/mese/account, configurabile con FORMULIX_DEV_LIMITE. Comprende localhost, sottodomini .localhost, 127.0.0.1, [::1] e domini .test. La chiave valida resta obbligatoria.
• Consumo sincronizzato tra processi, di norma ogni 5 secondi: non è un contatore globale transazionale per richiesta. Il mese segue UTC.

Errori

Gli errori applicativi usano JSON { "erro": "message" }. Le convalide dei calcoli possono avere messaggi tradotti.

/saude restituisce { "ok": true } senza autenticazione; non conferma l’accesso di una chiave al servizio.